Org-publish comes with [[https://orgmode.org/manual/Publishing.html][lots of options]], including sitemap generation (here [[../articles.org][my
post list]] with anti-chronological sorting). It supports code highlighting
through the =htmlize= package.
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]].
* Personal domain and HTTPS
I previously stressed out the importance of keeping the URL permanents. Which
means that we should not rely on the domain offered by a hosting platform such
as [[https://about.gitlab.com/features/pages/][GitLab Pages]], since changing host implies changing domain, thus invalidating
all format post URLs. Acquiring a domain is a necessary step.
This might turn off those looking for the cheapest option, but in fact getting
domain name comes close to 0 cost if you are not limitating yourself to just a
subset of popular options. For a personal blog, the domain name and the
top-level domain should not matter much and can be easily adjusted to bring the
costs to a minimum.
There are many registrars to choose from. One of the biggest, GoDaddy has [[https://en.wikipedia.org/wiki/GoDaddy#Controversies][a
debatable reputation]]. I've opted for https://www.gandi.net/.
With a custom domain, we also need a certificate for HTTPS. This used to come
at a price but is now free and straightforward with [[https://letsencrypt.org/][Let's Encrypt]]. Here is a
[[https://about.gitlab.com/2016/04/11/tutorial-securing-your-gitlab-pages-with-tls-and-letsencrypt/][tutorial for GitLab pages]]. (Note that the commandline tool is called [[https://certbot.eff.org][certbot]]
now.)
* Permanent URLs and folder organization pitfalls
[[https://nullprogram.com/blog/2017/09/01/][Chris Wellons]] has some interesting insights about the architecture of a blog.
[[https://www.w3.org/Provider/Style/URI][URLs are forever]], and as such a key requirement of every website is to ensure
all its URLs will remain permanent. Thus the folder organization of the blog
has to be thought of beforehand.
- Keep the URLs human-readable and easy to remember. :: Make them short and
meaningful.
- Avoid dates in URLs. :: This is a very frequent mishappen with blogs. There
are usually no good reason to encode the date in the URL of a post, it only
makes it harder to remember and more prone to change when moving platform.
- Avoid hierarchies. :: Hierarchies usually don't help with the above points,
put everything under the same folder instead. Even if some pages belong to
different "categories" (for instance "articles" and "projects"), this is
only a matter of presentation on the sitemap (or the welcome page). It
should not influence the URLs. When the category is left out, it's one
thing less to remember whether the page =foo= was an article or a project.
- Place =index.html= files in dedicated folders. :: If the page extension does
not matter (e.g. between =.html= and =.htm=), you can easily avoid the
visitors any further guessing by storing your =foo= article in
=foo/index.html=. Thus browsing =https://domain.tld/foo/= will
automatically retrieve the right document. It's easier and shorter than
=https://domain.tld/foo.htm=.
- Don't rename files. :: Think twice before naming a file: while you can later
tweak some virtual mapping between the URL and a renamed file, it's better
to stick to the initial names to keep the file-URL association as
straightforward as possible.
* Other publishing systems
- [[https://github.com/greghendershott/frog][Frog]] is a blog generator written in [[https://racket-lang.org/][Racket]]. While it may be one of the best
of its kind, it sadly does not support the Org format as of this writing.
Some blogs generated with Frog:
- https://alex-hhh.github.io
- http://jao.io/pages/about.html
- [[https://dthompson.us/projects/haunt.html][Haunt]] is a blog generator written in [[https://www.gnu.org/software/guile/][Guile]]. It seems to be very complete and
extensible, but sadly it does not support the Org format as of this writing.
Some blogs generated with Haunt:
- https://dthompson.us/index.html
- https://www.gnu.org/software/guix/
* Other Org-blogs
- https://explog.in/: [[https://explog.in/config.html][Also in pure Org/Lisp]]?
- http://jgkamat.gitlab.io/: [[http://jgkamat.gitlab.io/blog/website1.html][Also in pure Org/Lisp]].
- https://ogbe.net/: [[https://ogbe.net/blog/blogging_with_org.html][Also in pure Org/Lisp]].
- http://sadiqpk.org/: [[http://sadiqpk.org/blog/2018/08/08/blogging-with-org-mode.html][Also in pure Org/Lisp]].
- http://endlessparentheses.com/: [[http://endlessparentheses.com/how-i-blog-one-year-of-posts-in-a-single-org-file.html][Generated with Jekyll]].
- https://gjhenrique.com/: [[https://gjhenrique.com/meta.html][Generated with Jekyll]].
- http://juanreyero.com/: [[http://juanreyero.com/open/org-jekyll/][Generated with Jekyll]].
- https://babbagefiles.xyz/: [[https://babbagefiles.xyz/new-blog/][Generated with Hugo]].
- http://cestlaz.github.io/: [[http://cestlaz.github.io/posts/using-emacs-35-blogging/][Generated with Nikola]].
