My Website built using Org mode

• Building the website
  • TL;DR
  • Incremental builds
  • Layout
  • Export
  • Use CI to handle the deployment
• Writing content

This repository hosts the sources for pierre-antoine-comby.fr, my personal website.

• It is built directly from Org mode to static HTML: no Hugo, no Markdown intermediate.
• Rendering is a thin export backend derived from ox-html (lisp/ox-pac.el). Its overridden transcoders author their markup as S-expressions and serialize them with esxml, through a small authoring layer (lisp/sxml-html.el).
• The earlier ox-hugo/Blowfish and sxml-publish pipelines are retired; they only live in git history.

Building the website

TL;DR

1. Have emacs (29.1+), python3 with fontTools, git, make, rclone and latexmk installed.
2. Clone this repository. Emacs packages (xkcd, emacsql, htmlize, esxml) are installed into .packages/ on first build.
3. Build the resume PDF and the website into public/:

./build.sh

1. Deploy with rclone (the remote config is not in this repo):

make deploy

make alone only publishes the site; ./build.sh also builds the resume (resume/CV2.tex, via latexmk) and copies it to assets/CV2.pdf.

The build fetches from the network: each xkcd: link queries xkcd's API (cached in a local sqlite db).

Incremental builds

Pages are published incrementally through org-publish's timestamp cache, kept in .cache/org-timestamps/. It only tracks .org sources, so after changing anything in lisp/ or publish-config.el, force a full rebuild:

make cleanall && make

A full build takes about a minute.

Layout

publish-config.el

entry point. Bootstraps packages, loads lisp/, sets the site description (nav, social links, footer), defines org-publish-project-alist, and publishes.

lisp/sxml-html.el

S-expression to HTML authoring layer on top of esxml.

lisp/ox-pac.el

the pac export backend (page template, talks and projects pages, link handling, post index and tag pages).

lisp/pac-icons.el

replaces Nerd Font glyphs with inline SVG, extracted by tools/nerd_icon_svg.py and cached in static/icons/generated/.

lisp/xkcd-extras.el

renders xkcd:NUM links as images.

content-org/

the Org sources.

static/

CSS, JS, fonts and icons, published verbatim.

resume/

the LaTeX CV.

Export

org-publish-project-alist is made of:

pages

top-level content-org/*.org pages (intro.org is excluded and spliced into index.org and about.org with #+INCLUDE).

post

content-org/posts/, recursive, drafts excluded; also builds posts/index.html and posts/tags/<tag>.html.

content-images, static, assets

copied as-is with org-publish-attachment.

site

the umbrella component.

Publish only, without the resume:

emacs -Q --script publish-config.el

TODO Use CI to handle the deployment

For now I do it manually, but it would be nice to have a CI pipeline to do it automatically.

Writing content

• Blog posts live in content-org/posts/*.org with #+TITLE:, #+DATE: and #+FILETAGS:. Park drafts in content-org/posts/drafts/.
• Page type is chosen per file with #+template: (home, post, talks-page, projects-page, default page).
• Use xkcd:NUM, pep:NUM, github:user/repo and gitlab:user/repo rather than raw URLs.
• Talks and projects take per-heading metadata in :PROPERTIES: drawers (talks: DATE, LOCATION, SLIDES, POSTER, RECORDING, PAPER, WEBSITE; projects: IMAGE). A project is a top-level headline in projects.org whose first paragraph is a one-line blurb.
• Existing URLs (/talks.html, /posts/foo.html, /posts/tags/<tag>.html) must be kept.

See CLAUDE.md for the architecture in more detail.