diff options
| author | p4bl0 <r@uzy.me> | 2015-03-05 09:34:49 +0100 |
|---|---|---|
| committer | p4bl0 <r@uzy.me> | 2015-03-05 09:34:49 +0100 |
| commit | a4fd45118ba0001ccf01cd6da98b79dbac416e99 (patch) | |
| tree | 0450efa21058a81890333665804f0a0efcd64d97 /README | |
| parent | 01dd453e46f55a28c51d346a29be85ff381822eb (diff) | |
rename README into README.html
Diffstat (limited to 'README')
| -rw-r--r-- | README | 423 |
1 files changed, 0 insertions, 423 deletions
@@ -1,423 +0,0 @@ -fugitive: README - -<h2 id="info">Info</h2> - -<p> - fugitive is a blog engine running on top of git using hooks to generate - static html pages and thus having only git as dependency. -</p> -<p> - In its hooks, fugitive uses only standard UNIX® tools that are included in - the GNU core-utils package, plus sh as script interpreter. That's it.<br /> - Moreover, everything that can be done using git, is.<br /> - No dependencies like rack, heroku, or whatever Ruby gems you can think of. No - configuration files. No metadata in your articles files. Hell, if you want to - you could even make a <a href="#templating">template</a> that use git log as - storage backend, which means <em>no files</em> either, just and only git. -</p> - -<h2 id="install">Install</h2> - -<h3 id="build">Build</h3> -<p> - If you want to build fugitive from the source, clone the git repository: - <br /> - <code>git clone git://gitorious.org/fugitive/fugitive.git fugitive</code> - <br /> - Then go in the newly created directory: <code>cd fugitive</code>, and - run the build script: <code>./build.sh</code>. - <br /> - This will generate an executable file "fugitive" which you can use - to create your blog. -</p> -<h3 id="create">Create a blog</h3> -<p> - There are two install modes for fugitive: local and remote. The local mode - should be used to install a repository where you edit your blog, and the - remote mode for a repository to which you're going to push to publish your - blog.<br /> - The local mode can also be used to publish if you edit your files directly on - your server. -</p> -<p> - To create your blog run the command:<br /> - <code>fugitive --install-<em>mode</em> <dir></code>, - where <em>mode</em> is either "local" or "remote". - <br /> - This will create a git repository with appropriate hooks, config and files in - <dir>. - <br /> - If <dir> isn't specified then the current working directory is used. -</p> -<p class="important"> - Once you have installed your blog you need to set the <em>blog-url</em> - parameter in your git configuration. See <a href="#config">configuration</a> - for details. -</p> - -<h2 id="config">Configuration</h2> - -<p> - All these settings are in the "fugitive" section of the git config. - You can change them with the command <br /> - <code>git config fugitive.<em>parameter</em> <em>value</em></code>, - where <em>parameter</em> is one of the following: -</p> -<dl> - <dt>blog-url</dt> - <dd> - This is the public URL of the generated blog. <strong>You need to set - it</strong> as soon as possible since it's required for the RSS feed (and - used in the default footer template). - </dd> - <dt>public-dir*</dt> - <dd> - This is the path to the directory that will contain the generated html - files. Default value is "_public". You could set it to - "_public/blog" for instance if you want to have have a website in - "_public" and your blog in "/blog". - </dd> - <dt>articles-dir*</dt> - <dd> - This is the path where fugitive will look for published articles. Default - value is "_articles". - </dd> - <dt>templates-dir*</dt> - <dd> - This is the path where fugitive will look for templates files. Default - value is "_templates". - </dd> - <dt>preproc</dt> - <dd> - If you want your article to be preprocessed by an external tool (markdown, - textile...) you need to set <em>preproc</em> to a command line that will - read on stdin and write to stdout. - </dd> -</dl> -<p class="note"> - * Those paths are relative to the root of the git repository, must be in it - and must not start with "." neither have a '/' at the end. Example: - "dir/subdir" is valid but "./dir/subdir" and - "dir/subdir/" are not. -</p> - -<h2 id="usage">Usage</h2> - -<h3 id="general-use">General use</h3> -<p> - Articles you want to publish should be a file without the .html extension in the - <em>articles-dir</em> directory (see <a href="#config">configuration</a>). - The first line of the file will be used as a title and the rest of the file as - the content of the article. -</p> -<p> - By default there's a "_drafts" directory in which you can put - articles you are writing and you want to version control in your git - repository but you don't want to publish yet. -</p> -<p> - When you commit change to a fugitive git repository, the post-commit hook - looks in the <em>articles-dir</em> directory - (see <a href="#config">configuration</a>) for newly added articles, modified - articles and deleted ones. Then it does the following things: -</p> -<ul> - <li>it generates static html files for newly added articles,</li> - <li>it regenerates static html files for modified articles,</li> - <li>it deletes static html files for deleted articles,</li> - <li>it regenerates static html files for articles that are just before and - after newly added and deleted articles (this to maintain the - "previous" and "next" links alive),</li> - <li>it regenerates the archives.html, tags.html, and feed.xml files,</li> - <li>and finally it copies the static html file of the last article to - "index.html".</li> -</ul> -<p class="note"> - If a change happen in the <em>templates-dir</em> directory - (see <a href="#config">configuration</a>), then static html files for - everything is regenerated to make the change effective. -</p> -<p> - All generated files are created in the <em>public-dir</em> directory - (see <a href="#config">configuration</a>). -<p> - When you push to a remote repository installed with fugitive, the same thing - will happen but instead of looking only at the last commit, the hook will - analyse every changes since the last push and then (re)generate html files - accordingly. -</p> -<p class="warning"> - Do not create an article file named "archives".<br /> - Do not create an article file named "index". -</p> -<h3 id="templating">Template system</h3> -<p> - The better explanation about the templates system is to see what the default - templates looks like. But since they do not use all the offered - possibilities, here are some more explanations... -</p> -<p> - The fugitive template system uses xml preprocessor - syntax: <code><?fugitive <em>var</em> ?></code> is rendered as the - value of <em>var</em>. This choice has been made because with this syntax - templates are still valid xml (and html) document, and it is semantically - more accurate than xml comments (<code><!-- <em>var</em> --></code>). -</p> -<p> - In addition to variable rendering, there is a conditional and a foreach loop - constructs, plus an include directive. -</p> -<p> - The syntax of the include directive is <code><?fugitive - include:<em>file</em> ?></code> where <em>file</em> is relative to - the <em>templates-dir</em> directory - (see <a href="#config">configuration</a>). The includes are processed before - anything else. -</p> -<p> - The foreach loop construct is specific to the archives.html, tags.html, and - feed.xml templates and will therefore be described at the same time. Where - available, the loops are processed right after the includes. -</p> -<p> - The syntax of the conditional construct is as follows: -</p> -<pre><<span class="keyword">?fugitive</span> ifset:<em>var</em> ?> - Template code which is ignored if <em>var</em> value is empty, and - which typically includes <<span class="function-name">code</span>><<span class="keyword">?fugitive</span> <em>var</em> ?></<span class="function-name">code</span>>. -<<span class="keyword">?fugitive</span> endifset:<em>var</em> ?></pre> -<p class="note"> - Not every variable can be used in the conditional construct, this is indicated - in the description of those which can't. -</p> -<p>The following variables are available everywhere:</p> -<dl> - <dt>page_title</dt> - <dd> - Its value is "archives" in the archives.html template, - "feed" in the feed.xml template, or the article title in the - article.html template. - </dd> - <dt>blog_url</dt> - <dd> - The <em>blog-url</em> value in the "fugitive" section of the git - configuration (see <a href="#config">configuration</a>). - </dd> - <dt>commit_Hash</dt> - <dd> - Its value is the hash corresponding to the last commit that provoked the - (re)generation of the file. - </dd> - <p class="note"> - This is case-sensitive. Compare this with the next one. - </p> - <dt>commit_hash</dt> - <dd> - Its value is the short hash (the seven first digit of the hash) - corresponding to the last commit that provoked the (re)generation of the - file. - </dd> - <dt>commit_author</dt> - <dd> - Its value is the name of the author of the last commit that provoked the - (re)generation of the file. - </dd> - <dt>commit_author_email</dt> - <dd> - Its value is the email of the author of the last commit that provoked the - (re)generation of the file (with '@' replaced by "[at]" and '.' - replaced by "(dot)"). - </dd> - <dt>commit_datetime</dt> - <dd> - Its value is the date and time of the last commit that provoked the - (re)generation of the file. - </dd> - <dt>commit_datetime_html5</dt> - <dd> - Its value is the date and time of the last commit that provoked the - (re)generation of the file, <em>but in an html5 <code><time></code> - compliant format</em>. - </dd> - <dt>commit_date</dt> - <dd> - Its value is the date of the last commit that provoked the (re)generation - of the file. - </dd> - <dt>commit_time</dt> - <dd> - Its value is the time of the last commit that provoked the (re)generation - of the file. - </dd> - <dt>commit_timestamp</dt> - <dd> - Its value is the unix timestamp of the last commit that provoked the - (re)generation of the file. - </dd> - <dt>commit_subject</dt> - <dd> - Its value is the subject (first line of the commit message) of the last - commit that provoked the (re)generation of the file. - </dd> - <dt>commit_body</dt> - <dd> - Its value is the body (the rest of the commit message) of the last commit - that provoked the (re)generation of the file. <strong>This variable can't - be used in the conditional construct.</strong> - </dd> - <dt>commit_slug</dt> - <dd> - Its value is the subject of the last commit that provoked the - (re)generation of the file but formatted to be file name friendly. - </dd> -</dl> -<h4>Variables specific to the article.html template:</h4> -<dl> - <dt>article_title</dt> - <dd> - Its value is the title of the article (the first line of the file). - </dd> - <dt>article_content</dt> - <dd> - Its value is the content of the article (the rest of the - file). <strong>This variable can't be used in the conditional - construct.</strong> - </dd> - <dt>article_file</dt> - <dd> - Its value is the file name of the article (without the .html extension). - </dd> - <dt>article_cdatetime</dt> - <dd> - Its value is the date and time of the publication of the article (the date - of the commit which added the article to the repository in - the <em>articles-dir</em> directory - (see <a href="#config">configuration</a>)). - </dd> - <dt>article_cdatetime_html5</dt> - <dd> - Same as previous, but in an html5 <code><time></code> compliant - format. - </dd> - <dt>article_cdate</dt> - <dd> - Its value is the date of the publication of the article. - </dd> - <dt>article_ctime</dt> - <dd> - Its value is the time of the publication of the article. - </dd> - <dt>article_ctimestamp</dt> - <dd> - Its value is the timestamp of the publication of the article. - </dd> - <dt>article_mdatetime</dt> - <dd> - Its value is the date and time of the last modification of the article - (the date of the last commit which changed the article file). - </dd> - <dt>article_mdatetime_html5</dt> - <dd> - Same as previous, but in an html5 <code><time></code> compliant - format. - </dd> - <dt>article_mdate</dt> - <dd> - Its value is the date of the last modification of the article. - </dd> - <dt>article_mtime</dt> - <dd> - Its value is the time of the last modification of the article. - </dd> - <dt>article_mtimestamp</dt> - <dd> - Its value is the timestamp of the last modification of the article. - </dd> - <dt>article_cauthor</dt> - <dd> - Its value is the author of the commit which added the article to the - repository. - </dd> - <dt>article_cauthor_email</dt> - <dd> - Its value is the email of the author of the commit which added the article - to the repository (with '@' replaced by "[at]" and '.' replaced - by "(dot)"). - </dd> - <dt>article_mauthor</dt> - <dd> - Its value is the author of the last commit which changed the article file. - </dd> - <dt>article_mauthor_email</dt> - <dd> - Its value is the email of the author of the last commit which changed the - article file (with '@' replaced by "[at]" and '.' replaced by - "(dot)"). - </dd> - <dt>article_previous_file</dt> - <dd> - Its value is the file name (without .html extension) of the previous - article ordered by publication date. - </dd> - <dt>article_previous_title</dt> - <dd> - Its value is the title of the previous article ordered by publication date. - </dd> - <dt>article_next_file</dt> - <dd> - Its value is the file name (without .html extension) of the next article - ordered by publication date. - </dd> - <dt>article_next_title</dt> - <dd> - Its value is the title of the next article ordered by publication date. - </dd> -</dl> -<h4>foreach loops in archives.html and feed.xml:</h4> -<p> - Two foreach loops are available: <code>foreach:article</code> - and <code>foreach:commit</code>. The syntax is as follows: -</p> -<pre><<span class="keyword">?fugitive</span> foreach:article ?> - Template code that will be repeated for each article and - where the values of <<span class="function-name">code</span>>article_*</<span class="function-name">code</span>> variables are - set in accordance with the article each time. -<<span class="keyword">?fugitive</span> endforeach:article ?></pre> -<pre><<span class="keyword">?fugitive</span> foreach:commit ?> - Template code that will be repeated for each commit and - where the values of <<span class="function-name">code</span>>commit_*</<span class="function-name">code</span>> variables are - set in accordance with the commit each time. -<<span class="keyword">?fugitive</span> endforeach:commit ?></pre> -<p> - The only difference between the archives.html and feed.xml templates is that - in feed.xml these constructs only loop on the five last articles and commits. -</p> - -<h2 id="hacking">Hacking fugitive</h2> -<p> - If you want to hack fugitive code to customize the behavior of the hooks, you - can either edit the hooks directly in your fugitive blog repository, or edit - them in the fugitive source code, then rebuild the <code>fugitive</code> - executable using the <code>build.sh</code> script provided in the source code - repository. -</p> -<p> - In the latter case and if you already have a fugitive blog running, you'll - need to install the new hooks. This can be done by running the command:<br /> - <code>fugitive --install-hooks <dir></code>, where <dir> is the - path to your fugitive blog repository, if it isn't specified then the current - working directory is used. -</p> -<p> - This can be handy if you decide for instance that you want to have the - last <em>n</em> articles on your index.html page rather than a mere copy of - the last article. -</p> - -<h2 id="issues">Known issues</h2> -<p> - There seems to be some issues with the version of git provided in Debian - Lenny (1.5.*), I didn't investigate it yet, and I don't know if I'll do it, - because at this time Squeeze is already frozen and git 1.7.* is available in - the backports which are now officially supported by Debian. -</p> |