phyks/blogit
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

README well formatted

Browse Source
This commit is contained in:
Phyks 2014-01-23 01:04:18 +01:00
parent e1df874bad
commit f296a8b771
1 changed files with 54 additions and 35 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

89
README.md
View File

@ -1,26 +1,36 @@
Blogit Blogit ======
======
This script aims at building a static blog above a git repo. This way, you can use git abilities to have full archives and backups of your blog. Many scripts aims at doing this, and this is just one more. I needed something more personal and fitted to my needs, so I came up with this code. It's not very beautiful, can mostly be optimized but it's working for me. It may not be fitted to your needs, but it's up to you to see it. This script aims at building a static blog above a git repo. This way, you can
use git abilities to have full archives and backups of your blog. Many scripts
aims at doing this, and this is just one more. I needed something more personal
and fitted to my needs, so I came up with this code. It's not very beautiful,
can mostly be optimized but it's working for me. It may not be fitted to your
needs, but it's up to you to see it.
This script is just a python script that should be run as a git hook. You can see a working version at http://phyks.me and the repository behind it is publicly viewable at http://git.phyks.me/Blog. This script is just a python script that should be run as a git hook. You can
see a working version at http://phyks.me and the repository behind it is
publicly viewable at http://git.phyks.me/Blog.
This script has been developped by Phyks (phyks@phyks.me). For any suggestion or remark, please send me an e-mail. This script has been developped by Phyks (phyks@phyks.me). For any suggestion
or remark, please send me an e-mail.
## Installation ## Installation
1. Clone this repo. 1. Clone this repo.
2. Clear the .git directory and initialize a new empty git repo to store your blog. 2. Clear the .git directory and initialize a new empty git repo to store your
blog.
3. Move the `pre-commit.py` script to `.git/hooks/pre-commit` 3. Move the `pre-commit.py` script to `.git/hooks/pre-commit`
4. Edit the `raw/params` and edit it to fit your needs. 4. Edit the `raw/params` and edit it to fit your needs.
5. The `raw` folder comes with an example of blog architecture. Delete it and make your own. 5. The `raw` folder comes with an example of blog architecture. Delete it and
make your own.
6. You are ready to go ! 6. You are ready to go !
## Params ## Params
Available options in `raw/params` are : Available options in `raw/params` are :
* `BLOG_TITLE` : The title of the blog, to display in the <title> element in rendered pages. * `BLOG_TITLE` : The title of the blog, to display in the <title> element
in rendered pages.
* `NB_ARTICLES_INDEX` : Number of articles to display on index page. * `NB_ARTICLES_INDEX` : Number of articles to display on index page.
* `BLOG_URL` : Your blog base URL. * `BLOG_URL` : Your blog base URL.
* `IGNORE_FILES` : A comma-separated list of files to ignore. * `IGNORE_FILES` : A comma-separated list of files to ignore.
@ -28,7 +38,8 @@ Available options in `raw/params` are :
* `LANGUAGE` : Language param to put in RSS feed. * `LANGUAGE` : Language param to put in RSS feed.
* `DESCRIPTION` : Blog description, for the RSS feed. * `DESCRIPTION` : Blog description, for the RSS feed.
* `COPYRIGHT` : Copyright information, for the RSS feed. * `COPYRIGHT` : Copyright information, for the RSS feed.
* `SEARCH` : comma-separated list of elements to search for and replaced (custom regex, see code for more info) * `SEARCH` : comma-separated list of elements to search for and replaced
(custom regex, see code for more info)
* `REPLACE` : corresponding elements for replacement. * `REPLACE` : corresponding elements for replacement.
## Usage ## Usage
@ -36,44 +47,53 @@ Available options in `raw/params` are :
This script will use three folders: This script will use three folders:
* `raw/` will contain your raw files * `raw/` will contain your raw files
* `blog/` will contain the fully generated files to serve _via_ your http server * `blog/` will contain the fully generated files to serve _via_ your http
server
* `gen/` will store temporary intermediate files * `gen/` will store temporary intermediate files
All the files you have to edit are located in the `raw/` folder. It contains by default an example version of a blog. You should start by renaming it and making your own. All the files you have to edit are located in the `raw/` folder. It contains by
default an example version of a blog. You should start by renaming it and
making your own.
Articles can be edited in HTML directly or in Markdown. They must be located in a `raw/year/month` folder, according to their date of publication and end with .html for html articles and .md for markdown articles. The basic content of an article is: Articles can be edited in HTML directly or in Markdown. They must be located in
```` a `raw/year/month` folder, according to their date of publication and end with
<!-- .html for html articles and .md for markdown articles. The basic content of an
@author=AUTHOR_NAME article is: ```` <!-- @author=AUTHOR_NAME @date=DDMMYYYY-HHMM @title=TITLE
@date=DDMMYYYY-HHMM @tags=TAGS --> CONTENT ````
@title=TITLE
@tags=TAGS
-->
CONTENT
````
where TAGS is a comma-separated list. Tags are automatically created if they do not exist yet. The HTML comment *must* be at the beginning of the document and is parsed to set the metadata of the article. where TAGS is a comma-separated list. Tags are automatically created if they do
not exist yet. The HTML comment *must* be at the beginning of the document and
is parsed to set the metadata of the article.
CONTENT is then either a HTML string or a markdown formatted one. CONTENT is then either a HTML string or a markdown formatted one.
You can ignore an article to not make it publicly visible during redaction, simply by adding a .ignore extension. You can ignore an article to not make it publicly visible during redaction,
simply by adding a .ignore extension.
When you finish editing your article, you can add the files to git and commit, to launch the script. You can also manually call the script with the `--force-regen` option if you want to rebuild your entire blog. When you finish editing your article, you can add the files to git and commit,
to launch the script. You can also manually call the script with the
`--force-regen` option if you want to rebuild your entire blog.
## Header file ## Header file
You can use the `@blog_url` syntax anywhere. It will be replaced by the URL of the blog, as defined in the parameters (and this is useful to include CSS etc.). You can use the `@blog_url` syntax anywhere. It will be replaced by the URL of
the blog, as defined in the parameters (and this is useful to include CSS
etc.).
You can also use `@tags` that will be replaced by the list of tags and `@articles` for the list of last articles. You can also use `@tags` that will be replaced by the list of tags and
`@articles` for the list of last articles.
## Static files ## Static files
In static files, in raw folder (such as `divers.html` in the demo code), you can use `#base_url` that will be replaced by the base url of the blog, as defined in the parameters. This is useful to make some links. In static files, in raw folder (such as `divers.html` in the demo code), you
can use `#base_url` that will be replaced by the base url of the blog, as
defined in the parameters. This is useful to make some links.
## Alternatives ## Alternatives
There exist many alternatives to this script, but they didn't fit my needs (and were not all tested) : There exist many alternatives to this script, but they didn't fit my needs (and
were not all tested) :
* fugitive : http://shebang.ws/fugitive-readme.html * fugitive : http://shebang.ws/fugitive-readme.html
* Jekyll : http://jekyllrb.com/ and Oktopress : http://octopress.org/ * Jekyll : http://jekyllrb.com/ and Oktopress : http://octopress.org/
@ -82,11 +102,10 @@ There exist many alternatives to this script, but they didn't fit my needs (and
## LICENSE ## LICENSE
-------------------------------------------------------------------------------- --------------------------------------------------------------------------------
"THE NO-ALCOHOL BEER-WARE LICENSE" (Revision 42): "THE NO-ALCOHOL BEER-WARE LICENSE" (Revision 42): Phyks
Phyks (webmaster@phyks.me) wrote this file. As long as you retain this notice you (webmaster@phyks.me) wrote this file. As long as you retain this notice you
can do whatever you want with this stuff (and you can also do whatever you want can do whatever you want with this stuff (and you can also do whatever you
with this stuff without retaining it, but that's not cool...). If we meet some want with this stuff without retaining it, but that's not cool...). If we
day, and you think this stuff is worth it, you can buy me a <del>beer</del> soda meet some day, and you think this stuff is worth it, you can buy me a
in return. <del>beer</del> soda in return. Phyks
Phyks
--------------------------------------------------------------------------------- ---------------------------------------------------------------------------------