Commit 847ca7b9 authored by Ambrevar's avatar Ambrevar

blog-architecture: Add editing argument + Git support

parent 1b049ecf
#+TITLE: A blog in pure Org/Lisp
#+SUBTITLE: A pamphlet for hackable website systems
#+DATE: <2018-08-13 Mon>
* The importance of blogging
......@@ -36,6 +37,46 @@ points where Org really shines:
- It has excellent support for multiple export formats, including LaTeX and PDFs.
* Version control system
A significant downside of printed books and documents is that they can't be
updated. That is to say, unless you acquire a new edition, should there be any.
The Internet comes with the advantage that it allows to update content
worldwide, in a fraction of an instant.
Updating is important: originals are hardly ever typo-free; speculations might
turn out to be wrong; phrasing could prove ambiguous. And most importantly, the
readers feedback can significantly help improve the argumentation and need be
taken into account.
The general trend around blogging seems to go in the other direction: articles
are often published and left as-is, never to be edited.
As such, many blog articles are struck by the inescapable flail of time and
technological advancement: they run out of fashion and lose much of their
original value.
But there is a motivation behind this immobility: the ability to edit removes
the guarantee that readers can access the article in its original
form. Content could be lost in the process. External references become
meaningless if the content has been removed or changed from the source they
refer to.
Thankfully there is a solution to this problem: version control systems. They
keep all versions available to the world and make editing fully transparent.
I keep the source of my website at
https://gitlab.com/ambrevar/ambrevar.gitlab.io, in a public [[https://git-scm.com/][Git]] repository.
I cannot stress enough the importance of [[../vcs/index.org][keeping your projects under version
control]] in a /publicly readable repository/:
- It allows not only you but also all visitors to keep track of /all/ changes.
This gives a /guarantee of transparency/ to your readers.
- It makes it trivial for anyone to /clone/ the repository locally: the website
can be read offline in the Org format!
* Publishing requirements
[[https://orgmode.org/worg/org-blog-wiki.html][Worg has a list of blogging systems]] that work with the Org format. Most of them
......@@ -58,9 +99,13 @@ important requirements:
generation process. I don't want to be restricted by a non-Turing-complete
configuration file or a dumb programming language.
Last but not least, the process as the whole must be as immediate and
friction-less as possible, or else I take the risk of feeling too lazy to
publish new posts and update the content.
- Ease of use. :: The process as a whole must be as immediate and friction-less
as possible, or else I take the risk of feeling too lazy to
publish new posts and update the content.
- Hackability. :: Last but not least, and this probably supersedes all other
requirements: /The system must be hackable/. Lisp-based
systems are prime contenders in that area.
* Org-publish
......@@ -80,25 +125,48 @@ Org-publish comes with [[https://orgmode.org/manual/Publishing.html][lots of opt
post list]] with anti-chronological sorting). It supports code highlighting
through the =htmlize= package.
** Webfeeds
One thing it lacked for me however was the generation of web feeds (RSS or
Atom). I looked at the existing possibilities in Emacs Lisp but I could not
find anything satisfying. There is =ox-rss= in Org-contrib, but it only works
over a single Org file, which does not suit my needs of one file per blog post.
So I went ahead and implemented [[https://gitlab.com/ambrevar/ambrevar.gitlab.io/blob/master/feed-builder.el][my own generator]].
* Version control system
** History of changes (dates and logs)
I keep the source of my website at
https://gitlab.com/ambrevar/ambrevar.gitlab.io, in a [[https://git-scm.com/][Git]] repository.
Org-publish comes with a timestamp system that proves handy to avoid building
unchanged files twice. It's not so useful though to retrieve the date of last
modification because a file may be rebuilt for external reasons (e.g. change in
the publishing script).
I cannot stress enough the importance of [[../vcs/index.org][keeping your projects under version
control]] in a /publicly readable repository/:
Since I use the version control system (here Git), it should be most natural to
keep track of the creation dates and last modification date of the article.
- It allows not only you but also all visitors to keep track of /all/ changes.
This gives a /guarantee of transparency/ to your readers.
Org-publish does not provide direct support for Git, but thanks to Lisp this
feature can only be a simple hack away:
- It makes it trivial for anyone to /clone/ the repository locally: the website
can be read offline in the Org format!
#+BEGIN_SRC elisp
(defun ambrevar/git-creation-date (file)
"Return the first commit date of FILE.
Format is %Y-%m-%d."
(with-temp-buffer
(call-process "git" nil t nil "log" "--reverse" "--date=short" "--pretty=format:%cd" file)
(goto-char (point-min))
(buffer-substring-no-properties (line-beginning-position) (line-end-position))))
(defun ambrevar/git-last-update-date (file)
"Return the last commit date of FILE.
Format is %Y-%m-%d."
(with-output-to-string
(with-current-buffer standard-output
(call-process "git" nil t nil "log" "-1" "--date=short" "--pretty=format:%cd" file))))
#+END_SRC
Then only ~org-html-format-spec~ is left to hack so that the ~%d~ and ~%C~
specifiers (used by ~org-html-postamble-format~) rely on Git instead.
See [[https://gitlab.com/ambrevar/ambrevar.gitlab.io/blob/master/publish.el][my publishing script]] for the full implementation.
* Personal domain and HTTPS
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment