home · contact · privacy
Improve feed update dating code, add fallback to feed uuid file lastmod.
[redo-blog] / README.md
1 redo-blog
2 =========
3
4 small blog system using the redo build system, with blog article files written
5 in (pandoc) Markdown or ReStructured Text.
6
7 dependencies
8 ------------
9
10 - redo
11 - python3
12 - uuidgen (Debian package: uuid-runtime)
13 - html2text
14 - pandoc
15
16 testing
17 -------
18
19 Run ./test.sh.
20
21 setup
22 -----
23
24 To set up a directory with symbolic links to the relevant files in ./processor/,
25 run ./add_dir.sh DIRECTORY.
26
27 You can then enter the directory and run redo there. This will generate article
28 .html files from all .md and .rst files, plus a ./index.html, and a ./feed.xml.
29 These files will be linked to symbolically in a directory ./public/.
30
31 Some metadata files will also be generated below ./metadata/: For each article,
32 there will be generated a .uuid and a .intermediate file; furthermore, files for
33 data used in ./feed.xml and ./index.html will, if non-existant, be built there
34 and can be edited to customize the blog – namely the files url, author, uuid,
35 title, index.tmpl, index_snippet.tmpl, article.tmpl.
36
37 recipe to remotely manage a redo blog with git
38 ----------------------------------------------
39
40 On your server, install the dependencies listed above. Then set up a repository
41 for your blog files. Let's assume we want it to sit in our home directory and be
42 called `blog`:
43
44     cd ~
45     mkdir blog
46     git init --bare blog.git
47     cat << EOF > blog.git/hooks/post-update
48     #!/bin/sh
49     BLOGDIR=~/blog
50     GIT_WORK_TREE=\$BLOGDIR git checkout -f
51     cd \$BLOGDIR
52     redo
53     EOF
54     chmod a+x blog.git/hooks/post-update
55
56 Enable management of `~/blog` via redo-blog:
57
58     git clone https://github.com/plomlompom/redo-blog/
59     cd redo-blog/
60     ./add_dir.sh ~/blog
61     mkdir ~/blog/public
62
63 Link to the `public` subdirectory from wherever your web server expects your
64 public web content to sit:
65
66     ln -s ~/blog/public /var/www/html/blog
67
68 Client-side, do this (you obviously need to customize this code; at least
69 replace the username `user` and the server name `example.org`):
70
71     cd ~
72     git init blog
73     cd blog
74     git remote add origin ssh://user@example.org:/home/user/blog.git
75     mkdir metadata
76     echo 'https://example.org/blog/' > metadata/url
77     git add metadata/url
78     git commit -m 'set up blog metadata'
79     git push origin master
80
81 bugs and peculiarities
82 ----------------------
83
84 Don't create a index.rst or index.md in the redo-managed directory, that will
85 break things.
86
87 The article title is derived in .md files from a first line prefixed with "% ",
88 while all other headings are treated as sub-headings. In .rst files, the title
89 is derived from a heading that must be at the top of the document, and be of an
90 adornment style (such as underlining with "=") that must be used only once in
91 it.