home · contact · privacy
Add workaround for redo-ifcreate not working as expected.
[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/. If you
30 provide or edit a file suffixed .links to basename of an article file, these
31 links will be added as article-specific linkbacks to the .html file and the feed
32 entry.
33
34 Some metadata files will also be generated below ./metadata/: For each article,
35 there will be generated a .automatic_metadata (to contain an article's UUID,
36 checksum, and creation/modification dates) and a .intermediate file (to contain
37 pandoc-formatted article content like title and body); furthermore, files for
38 data used in ./feed.xml and ./index.html will, if non-existant, be built there
39 and can be edited to customize the blog – namely the files url, author, title,
40 index.tmpl, index_snippet.tmpl, article.tmpl, linkback.tmpl. A blog-specific
41 UUID and creation date is stored in ./metadata/automatic_metadata
42
43 recipe to remotely manage a redo blog with git
44 ----------------------------------------------
45
46 On your server, install the dependencies listed above. Then set up a repository
47 for your blog files. Let's assume we want it to sit in our home directory and be
48 called `blog`:
49
50     cd ~
51     mkdir blog
52     git init --bare blog.git
53     cat << EOF > blog.git/hooks/post-update
54     #!/bin/sh
55     blog_dir=~/blog
56     export GIT_DIR=\$(pwd)
57     export GIT_WORK_TREE="\$blog_dir"
58     git checkout -f
59     cd "\$GIT_WORK_TREE"
60     redo
61     git add metadata/author metadata/url metadata/title metadata/*.tmpl metadata/automatic_metadata
62     count=\$(ls -1 metadata/*.automatic_metadata 2>/dev/null | wc -l)
63     if [ "\$count" != 0 ]; then
64       git add metadata/*.automatic_metadata
65     fi
66     status=\$(git status -s)
67     n_updates=\$(printf "\$status" | grep -vE '^\?\?' | wc -l)
68     if [ "\$n_updates" -gt 0 ]; then
69       git commit -a -m 'Update metadata'
70     fi
71     EOF
72     chmod a+x blog.git/hooks/post-update
73
74 Enable management of `~/blog` via redo-blog:
75
76     git clone https://github.com/plomlompom/redo-blog/
77     cd redo-blog/
78     ./add_dir.sh ~/blog
79     mkdir ~/blog/public
80
81 Link to the `public` subdirectory from wherever your web server expects your
82 public web content to sit:
83
84     ln -s ~/blog/public /var/www/html/blog
85
86 Client-side, do this (you obviously need to customize this code; at least
87 replace the username `user` and the server name `example.org`):
88
89     cd ~
90     git init blog
91     cd blog
92     git remote add origin ssh://user@example.org:/home/user/blog.git
93     mkdir metadata
94     echo 'https://example.org/blog/' > metadata/url
95     git add metadata/url
96     git commit -m 'set up blog metadata'
97     git push origin master
98
99 If successful, the git hook will furthermore commit some ~/blog/metadata/ files
100 generated by redo, that can be pulled into the client-side local repository:
101
102     git pull origin master
103
104 bugs and peculiarities
105 ----------------------
106
107 Don't create a index.rst or index.md in the redo-managed directory, that will
108 break things.
109
110 The article title is derived in .md files from a first line prefixed with `%`,
111 while all other headings are treated as sub-headings. In .rst files, the title
112 is derived from a heading that must be at the top of the document, and be of an
113 adornment style (such as underlining with `=`) used only once in it.
114
115 Symbolic links in public/ to removed article pages are currently not removed.