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