From a4fd45118ba0001ccf01cd6da98b79dbac416e99 Mon Sep 17 00:00:00 2001 From: p4bl0 Date: Thu, 5 Mar 2015 09:34:49 +0100 Subject: rename README into README.html --- README | 423 ------------------------------------------------------------ README.html | 423 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ build.sh | 2 +- install.sh | 4 +- 4 files changed, 426 insertions(+), 426 deletions(-) delete mode 100644 README create mode 100644 README.html diff --git a/README b/README deleted file mode 100644 index 72d2b69..0000000 --- a/README +++ /dev/null @@ -1,423 +0,0 @@ -fugitive: README - -

Info

- -

- fugitive is a blog engine running on top of git using hooks to generate - static html pages and thus having only git as dependency. -

-

- 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.
- Moreover, everything that can be done using git, is.
- 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 template that use git log as - storage backend, which means no files either, just and only git. -

- -

Install

- -

Build

-

- If you want to build fugitive from the source, clone the git repository: -
- git clone git://gitorious.org/fugitive/fugitive.git fugitive -
- Then go in the newly created directory: cd fugitive, and - run the build script: ./build.sh. -
- This will generate an executable file "fugitive" which you can use - to create your blog. -

-

Create a blog

-

- 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.
- The local mode can also be used to publish if you edit your files directly on - your server. -

-

- To create your blog run the command:
- fugitive --install-mode <dir>, - where mode is either "local" or "remote". -
- This will create a git repository with appropriate hooks, config and files in - <dir>. -
- If <dir> isn't specified then the current working directory is used. -

-

- Once you have installed your blog you need to set the blog-url - parameter in your git configuration. See configuration - for details. -

- -

Configuration

- -

- All these settings are in the "fugitive" section of the git config. - You can change them with the command
- git config fugitive.parameter value, - where parameter is one of the following: -

-
-
blog-url
-
- This is the public URL of the generated blog. You need to set - it as soon as possible since it's required for the RSS feed (and - used in the default footer template). -
-
public-dir*
-
- 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". -
-
articles-dir*
-
- This is the path where fugitive will look for published articles. Default - value is "_articles". -
-
templates-dir*
-
- This is the path where fugitive will look for templates files. Default - value is "_templates". -
-
preproc
-
- If you want your article to be preprocessed by an external tool (markdown, - textile...) you need to set preproc to a command line that will - read on stdin and write to stdout. -
-
-

- * 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. -

- -

Usage

- -

General use

-

- Articles you want to publish should be a file without the .html extension in the - articles-dir directory (see configuration). - The first line of the file will be used as a title and the rest of the file as - the content of the article. -

-

- 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. -

-

- When you commit change to a fugitive git repository, the post-commit hook - looks in the articles-dir directory - (see configuration) for newly added articles, modified - articles and deleted ones. Then it does the following things: -

- -

- If a change happen in the templates-dir directory - (see configuration), then static html files for - everything is regenerated to make the change effective. -

-

- All generated files are created in the public-dir directory - (see configuration). -

- 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. -

-

- Do not create an article file named "archives".
- Do not create an article file named "index". -

-

Template system

-

- 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... -

-

- The fugitive template system uses xml preprocessor - syntax: <?fugitive var ?> is rendered as the - value of var. 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 (<!-- var -->). -

-

- In addition to variable rendering, there is a conditional and a foreach loop - constructs, plus an include directive. -

-

- The syntax of the include directive is <?fugitive - include:file ?> where file is relative to - the templates-dir directory - (see configuration). The includes are processed before - anything else. -

-

- 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. -

-

- The syntax of the conditional construct is as follows: -

-
<?fugitive ifset:var ?>
-  Template code which is ignored if var value is empty, and
-  which typically includes <code><?fugitive var ?></code>.
-<?fugitive endifset:var ?>
-

- Not every variable can be used in the conditional construct, this is indicated - in the description of those which can't. -

-

The following variables are available everywhere:

-
-
page_title
-
- Its value is "archives" in the archives.html template, - "feed" in the feed.xml template, or the article title in the - article.html template. -
-
blog_url
-
- The blog-url value in the "fugitive" section of the git - configuration (see configuration). -
-
commit_Hash
-
- Its value is the hash corresponding to the last commit that provoked the - (re)generation of the file. -
-

- This is case-sensitive. Compare this with the next one. -

-
commit_hash
-
- 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. -
-
commit_author
-
- Its value is the name of the author of the last commit that provoked the - (re)generation of the file. -
-
commit_author_email
-
- 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)"). -
-
commit_datetime
-
- Its value is the date and time of the last commit that provoked the - (re)generation of the file. -
-
commit_datetime_html5
-
- Its value is the date and time of the last commit that provoked the - (re)generation of the file, but in an html5 <time> - compliant format. -
-
commit_date
-
- Its value is the date of the last commit that provoked the (re)generation - of the file. -
-
commit_time
-
- Its value is the time of the last commit that provoked the (re)generation - of the file. -
-
commit_timestamp
-
- Its value is the unix timestamp of the last commit that provoked the - (re)generation of the file. -
-
commit_subject
-
- Its value is the subject (first line of the commit message) of the last - commit that provoked the (re)generation of the file. -
-
commit_body
-
- Its value is the body (the rest of the commit message) of the last commit - that provoked the (re)generation of the file. This variable can't - be used in the conditional construct. -
-
commit_slug
-
- Its value is the subject of the last commit that provoked the - (re)generation of the file but formatted to be file name friendly. -
-
-

Variables specific to the article.html template:

-
-
article_title
-
- Its value is the title of the article (the first line of the file). -
-
article_content
-
- Its value is the content of the article (the rest of the - file). This variable can't be used in the conditional - construct. -
-
article_file
-
- Its value is the file name of the article (without the .html extension). -
-
article_cdatetime
-
- 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 articles-dir directory - (see configuration)). -
-
article_cdatetime_html5
-
- Same as previous, but in an html5 <time> compliant - format. -
-
article_cdate
-
- Its value is the date of the publication of the article. -
-
article_ctime
-
- Its value is the time of the publication of the article. -
-
article_ctimestamp
-
- Its value is the timestamp of the publication of the article. -
-
article_mdatetime
-
- 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). -
-
article_mdatetime_html5
-
- Same as previous, but in an html5 <time> compliant - format. -
-
article_mdate
-
- Its value is the date of the last modification of the article. -
-
article_mtime
-
- Its value is the time of the last modification of the article. -
-
article_mtimestamp
-
- Its value is the timestamp of the last modification of the article. -
-
article_cauthor
-
- Its value is the author of the commit which added the article to the - repository. -
-
article_cauthor_email
-
- 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)"). -
-
article_mauthor
-
- Its value is the author of the last commit which changed the article file. -
-
article_mauthor_email
-
- 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)"). -
-
article_previous_file
-
- Its value is the file name (without .html extension) of the previous - article ordered by publication date. -
-
article_previous_title
-
- Its value is the title of the previous article ordered by publication date. -
-
article_next_file
-
- Its value is the file name (without .html extension) of the next article - ordered by publication date. -
-
article_next_title
-
- Its value is the title of the next article ordered by publication date. -
-
-

foreach loops in archives.html and feed.xml:

-

- Two foreach loops are available: foreach:article - and foreach:commit. The syntax is as follows: -

-
<?fugitive foreach:article ?>
-  Template code that will be repeated for each article and
-  where the values of <code>article_*</code> variables are
-  set in accordance with the article each time.
-<?fugitive endforeach:article ?>
-
<?fugitive foreach:commit ?>
-  Template code that will be repeated for each commit and
-  where the values of <code>commit_*</code> variables are
-  set in accordance with the commit each time.
-<?fugitive endforeach:commit ?>
-

- 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. -

- -

Hacking fugitive

-

- 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 fugitive - executable using the build.sh script provided in the source code - repository. -

-

- 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:
- fugitive --install-hooks <dir>, where <dir> is the - path to your fugitive blog repository, if it isn't specified then the current - working directory is used. -

-

- This can be handy if you decide for instance that you want to have the - last n articles on your index.html page rather than a mere copy of - the last article. -

- -

Known issues

-

- 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. -

diff --git a/README.html b/README.html new file mode 100644 index 0000000..72d2b69 --- /dev/null +++ b/README.html @@ -0,0 +1,423 @@ +fugitive: README + +

Info

+ +

+ fugitive is a blog engine running on top of git using hooks to generate + static html pages and thus having only git as dependency. +

+

+ 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.
+ Moreover, everything that can be done using git, is.
+ 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 template that use git log as + storage backend, which means no files either, just and only git. +

+ +

Install

+ +

Build

+

+ If you want to build fugitive from the source, clone the git repository: +
+ git clone git://gitorious.org/fugitive/fugitive.git fugitive +
+ Then go in the newly created directory: cd fugitive, and + run the build script: ./build.sh. +
+ This will generate an executable file "fugitive" which you can use + to create your blog. +

+

Create a blog

+

+ 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.
+ The local mode can also be used to publish if you edit your files directly on + your server. +

+

+ To create your blog run the command:
+ fugitive --install-mode <dir>, + where mode is either "local" or "remote". +
+ This will create a git repository with appropriate hooks, config and files in + <dir>. +
+ If <dir> isn't specified then the current working directory is used. +

+

+ Once you have installed your blog you need to set the blog-url + parameter in your git configuration. See configuration + for details. +

+ +

Configuration

+ +

+ All these settings are in the "fugitive" section of the git config. + You can change them with the command
+ git config fugitive.parameter value, + where parameter is one of the following: +

+
+
blog-url
+
+ This is the public URL of the generated blog. You need to set + it as soon as possible since it's required for the RSS feed (and + used in the default footer template). +
+
public-dir*
+
+ 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". +
+
articles-dir*
+
+ This is the path where fugitive will look for published articles. Default + value is "_articles". +
+
templates-dir*
+
+ This is the path where fugitive will look for templates files. Default + value is "_templates". +
+
preproc
+
+ If you want your article to be preprocessed by an external tool (markdown, + textile...) you need to set preproc to a command line that will + read on stdin and write to stdout. +
+
+

+ * 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. +

+ +

Usage

+ +

General use

+

+ Articles you want to publish should be a file without the .html extension in the + articles-dir directory (see configuration). + The first line of the file will be used as a title and the rest of the file as + the content of the article. +

+

+ 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. +

+

+ When you commit change to a fugitive git repository, the post-commit hook + looks in the articles-dir directory + (see configuration) for newly added articles, modified + articles and deleted ones. Then it does the following things: +

+ +

+ If a change happen in the templates-dir directory + (see configuration), then static html files for + everything is regenerated to make the change effective. +

+

+ All generated files are created in the public-dir directory + (see configuration). +

+ 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. +

+

+ Do not create an article file named "archives".
+ Do not create an article file named "index". +

+

Template system

+

+ 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... +

+

+ The fugitive template system uses xml preprocessor + syntax: <?fugitive var ?> is rendered as the + value of var. 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 (<!-- var -->). +

+

+ In addition to variable rendering, there is a conditional and a foreach loop + constructs, plus an include directive. +

+

+ The syntax of the include directive is <?fugitive + include:file ?> where file is relative to + the templates-dir directory + (see configuration). The includes are processed before + anything else. +

+

+ 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. +

+

+ The syntax of the conditional construct is as follows: +

+
<?fugitive ifset:var ?>
+  Template code which is ignored if var value is empty, and
+  which typically includes <code><?fugitive var ?></code>.
+<?fugitive endifset:var ?>
+

+ Not every variable can be used in the conditional construct, this is indicated + in the description of those which can't. +

+

The following variables are available everywhere:

+
+
page_title
+
+ Its value is "archives" in the archives.html template, + "feed" in the feed.xml template, or the article title in the + article.html template. +
+
blog_url
+
+ The blog-url value in the "fugitive" section of the git + configuration (see configuration). +
+
commit_Hash
+
+ Its value is the hash corresponding to the last commit that provoked the + (re)generation of the file. +
+

+ This is case-sensitive. Compare this with the next one. +

+
commit_hash
+
+ 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. +
+
commit_author
+
+ Its value is the name of the author of the last commit that provoked the + (re)generation of the file. +
+
commit_author_email
+
+ 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)"). +
+
commit_datetime
+
+ Its value is the date and time of the last commit that provoked the + (re)generation of the file. +
+
commit_datetime_html5
+
+ Its value is the date and time of the last commit that provoked the + (re)generation of the file, but in an html5 <time> + compliant format. +
+
commit_date
+
+ Its value is the date of the last commit that provoked the (re)generation + of the file. +
+
commit_time
+
+ Its value is the time of the last commit that provoked the (re)generation + of the file. +
+
commit_timestamp
+
+ Its value is the unix timestamp of the last commit that provoked the + (re)generation of the file. +
+
commit_subject
+
+ Its value is the subject (first line of the commit message) of the last + commit that provoked the (re)generation of the file. +
+
commit_body
+
+ Its value is the body (the rest of the commit message) of the last commit + that provoked the (re)generation of the file. This variable can't + be used in the conditional construct. +
+
commit_slug
+
+ Its value is the subject of the last commit that provoked the + (re)generation of the file but formatted to be file name friendly. +
+
+

Variables specific to the article.html template:

+
+
article_title
+
+ Its value is the title of the article (the first line of the file). +
+
article_content
+
+ Its value is the content of the article (the rest of the + file). This variable can't be used in the conditional + construct. +
+
article_file
+
+ Its value is the file name of the article (without the .html extension). +
+
article_cdatetime
+
+ 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 articles-dir directory + (see configuration)). +
+
article_cdatetime_html5
+
+ Same as previous, but in an html5 <time> compliant + format. +
+
article_cdate
+
+ Its value is the date of the publication of the article. +
+
article_ctime
+
+ Its value is the time of the publication of the article. +
+
article_ctimestamp
+
+ Its value is the timestamp of the publication of the article. +
+
article_mdatetime
+
+ 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). +
+
article_mdatetime_html5
+
+ Same as previous, but in an html5 <time> compliant + format. +
+
article_mdate
+
+ Its value is the date of the last modification of the article. +
+
article_mtime
+
+ Its value is the time of the last modification of the article. +
+
article_mtimestamp
+
+ Its value is the timestamp of the last modification of the article. +
+
article_cauthor
+
+ Its value is the author of the commit which added the article to the + repository. +
+
article_cauthor_email
+
+ 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)"). +
+
article_mauthor
+
+ Its value is the author of the last commit which changed the article file. +
+
article_mauthor_email
+
+ 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)"). +
+
article_previous_file
+
+ Its value is the file name (without .html extension) of the previous + article ordered by publication date. +
+
article_previous_title
+
+ Its value is the title of the previous article ordered by publication date. +
+
article_next_file
+
+ Its value is the file name (without .html extension) of the next article + ordered by publication date. +
+
article_next_title
+
+ Its value is the title of the next article ordered by publication date. +
+
+

foreach loops in archives.html and feed.xml:

+

+ Two foreach loops are available: foreach:article + and foreach:commit. The syntax is as follows: +

+
<?fugitive foreach:article ?>
+  Template code that will be repeated for each article and
+  where the values of <code>article_*</code> variables are
+  set in accordance with the article each time.
+<?fugitive endforeach:article ?>
+
<?fugitive foreach:commit ?>
+  Template code that will be repeated for each commit and
+  where the values of <code>commit_*</code> variables are
+  set in accordance with the commit each time.
+<?fugitive endforeach:commit ?>
+

+ 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. +

+ +

Hacking fugitive

+

+ 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 fugitive + executable using the build.sh script provided in the source code + repository. +

+

+ 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:
+ fugitive --install-hooks <dir>, where <dir> is the + path to your fugitive blog repository, if it isn't specified then the current + working directory is used. +

+

+ This can be handy if you decide for instance that you want to have the + last n articles on your index.html page rather than a mere copy of + the last article. +

+ +

Known issues

+

+ 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. +

diff --git a/build.sh b/build.sh index 172c086..344b764 100755 --- a/build.sh +++ b/build.sh @@ -13,7 +13,7 @@ include_file() { cp install.sh tmp1 i=1 -for f in README *-*.sh default-files/*; do +for f in README.html *-*.sh default-files/*; do j=$((1 - i)) include_file tmp$i "$f" > tmp$j i=$j diff --git a/install.sh b/install.sh index 68f00ec..9185665 100644 --- a/install.sh +++ b/install.sh @@ -107,10 +107,10 @@ EOF echo "done." echo "Writing dummy article (README) and adding it to the repos... " (base64 -d | gunzip) > _articles/fugitive-readme </dev/null echo "done." fi -- cgit v1.2.3