Publish
Guide to publishing this very website.

In the spirit of literate programming encouraged by Org mode, this entire website's build process is documented on this very page. In order to build this website, Emacs parses and executes the code blocks contained on this page. By mixing behavior with the behavior's documentation, we can future-proof our understanding of the build logic, making it possible to efficiently revisit and upgrade this website at a later date.

Table of Contents

1. Introduction

This entire website is built with Org mode, an Emacs mode designed for literate programming among other things.

1.1. Benefits

Work within Emacs
This advantage concerns existing Emacs users.
Literate programming
Org files contain a mix of plain text associated with documentation, and code that can be executed. A documentation-centered workflow encourages us to describe our thought process as we write a program, this increases the likelihood of remembering why a particular piece of code was written.

1.2. Project structure

My three websites—main, wiki, and blog—are edited in the same directory, but can be exported to different locations. This enables me to assign subdomains to each website, as is recommended for uncorrelated content. 

tree -F -L 2

./
├── README.org
├── about.org
├── apps/
│   ├── index.org
│   └── sitemap.org
├── blog/
│   ├── 2022/
│   ├── 2023/
│   ├── 2024/
│   └── index.org
├── cv.org
├── cv.txt
├── index.org
├── publish-mlnp.org
├── resources/
│   ├── css-cv.org
│   ├── css-global.org
│   ├── cv.css
│   ├── favicon.png
│   ├── favicon.xcf
│   ├── global.css
│   ├── photo.jpg
│   └── topnav.html
├── sitemap.org
└── wiki/
    ├── emacs/
    ├── engineering/
    ├── fitness/
    ├── images/
    ├── index.org
    ├── languages/
    ├── linux/
    ├── programming/
    ├── sitemap.org
    └── typography/

16 directories, 20 files

2. Publishing targets

This first section lays out the interactive prompts used to bind export-related symbols with the following publishing targets:

Location
Where should the website be published?
Components
What parts of the website should be built?

2.1. Locations

Two publishing locations are prompted, if undefined:

Local
The website is built on the local machine. This is useful for website development.
Remote
The website is built on the specified remote server. This is used to publish the website on the internet, it then becomes visible at mlnp.fr.

We follow the recommendation outlined in the manual's uploading files section: in the case of remote publishing, we first publish locally, then rsync the local copy with the remote one. This is much more efficient for small updates—when attempting to publish to the remote target directly, tramp will `dumbly' check files for changes one by one, instead of checking the overall delta, which rsync does. 

(unless (boundp 'org-publish-location-local)
  (setq org-publish-location-local
        (read-string
         "Local target: " "/tmp/")))

(unless (boundp 'org-publish-location-remote)
  (setq org-publish-location-remote
        (read-string
         "Remote target: " "root@192.162.71.223:/var/www/")))

2.2. Components

We outline three significant components: the main site, the wiki, and the blog. We define an additional component to publish only styling information, as it changes pretty frequently. 

(setq org-publish-component
      (read-answer
       "Which `org-publish-project-alist' component should be built? "
       '(("mlnp.fr"
          ?m "build the main website")
         ("wiki.mlnp.fr"
          ?w "build the wiki")
         ("blog.mlnp.fr"
          ?b "build the blog")
         ("apps.mlnp.fr"
          ?a "build the apps homepage")
         ("everything"
          ?e "build everything for all websites")
         ("all-styles"
          ?s "build only websites' styles"))))

3. Resources

3.1. CSS

The website styling information is described on the CSS page.

3.2. JS

A goal of this website is to not have to rely on JavaScript.

4. Project components

The org-publish-project-alist variable is used by org-publish to identify website components and their properties upon export. It enables us to target different directories when publishing; I can write this website in a single, version-controlled directory, whilst maintaining separate export directories for wiki.mlnp.fr, blog.mlnp.fr, and apps.mlnp.fr.

Both the wiki and the blog call for css and font resources hosted on mlnp.fr, so these resources need only be exported once—to the mlnp.fr/resources/ folder. 

(require 'ox-publish)
(setq org-publish-project-alist
      `( ;; This line left blank to avoid noweb honoring `( prefix.
        <<mlnp.fr>>
        <<wiki.mlnp.fr>>
        <<blog.mlnp.fr>>
        <<apps.mlnp.fr>>
        <<all-styles>>
        ("everything"
         :components ("mlnp.fr"
                      "wiki.mlnp.fr"
                      "blog.mlnp.fr"
                      "apps.mlnp.fr"))))

4.1. All styles

We specify a separate publishing component for website styling information according to the following rationale:

  1. the page nesting hierarchy is subject to change;
  2. thus, pages should use absolute paths to reference their stylesheet in order to access it reliably, i.e. the remote URL;
  3. thus, pages built locally also require the remote stylesheet.

→ If the stylesheet isn't published remotely, it wouldn't be reflected on locally published pages. 

("all-styles"
 :components ("styles-mlnp"
              "styles-wiki"
              "styles-blog"
              "styles-apps"))
("styles-mlnp"
 :base-directory "resources/"
 :base-extension "css"
 :publishing-directory ,(concat org-publish-location-local "mlnp.fr/resources/")
 :publishing-function org-publish-attachment)
("styles-wiki"
 :base-directory "resources/"
 :base-extension "css"
 :publishing-directory ,(concat org-publish-location-local "wiki.mlnp.fr/resources/")
 :publishing-function org-publish-attachment)
("styles-blog"
 :base-directory "resources/"
 :base-extension "css"
 :publishing-directory ,(concat org-publish-location-local "blog.mlnp.fr/resources/")
 :publishing-function org-publish-attachment)
("styles-apps"
 :base-directory "resources/"
 :base-extension "css"
 :publishing-directory ,(concat org-publish-location-local "apps.mlnp.fr/resources/")
 :publishing-function org-publish-attachment)

4.2. mlnp.fr

("mlnp.fr"
 :components ("mlnp-main-pages"
              "mlnp-cv-txt"
              "mlnp-resources"
              "resources-pages"	; Only hosted on the main website.
              "mlnp-fonts"))
("mlnp-main-pages"
 :base-directory "./"
 :base-extension "org"
 :publishing-directory ,(concat org-publish-location-local "mlnp.fr/")
 :recursive nil ; Main site pages are all in top-level org directory.
 :auto-sitemap t
 :sitemap-title "Sitemap for [[https://mlnp.fr][mlnp.fr]]"
 :publishing-function org-html-publish-to-html)
("mlnp-cv-txt"
 :base-directory "./"
 :base-extension "txt"
 :publishing-directory ,(concat org-publish-location-local "mlnp.fr/")
 :publishing-function org-publish-attachment)
("mlnp-resources"
 :base-directory "resources/"
 :base-extension "css\\|js\\|png\\|jpg"
 :publishing-directory ,(concat org-publish-location-local "mlnp.fr/resources/")
 :publishing-function org-publish-attachment)
("resources-pages"
 :base-directory "resources/"
 :base-extension "org"
 :publishing-directory ,(concat org-publish-location-local "mlnp.fr/resources/")
 :recursive t ; Resource files could be nested deep inside resources/ folder.
 :publishing-function org-html-publish-to-html)
("mlnp-fonts"
 :base-directory "resources/fonts/"
 :base-extension "ttf\\|otf"
 :publishing-directory ,(concat org-publish-location-local "mlnp.fr/resources/fonts/")
 :publishing-function org-publish-attachment)

4.3. wiki.mlnp.fr

We use triple dashes in component names so that they convert to em dashes when exported to the sitemap titles. 

("wiki.mlnp.fr"
 :components ("wiki-main-pages"
              "wiki-resources"
              "wiki-fonts"
              "wiki-images"))
("wiki-main-pages"
 :components ("wiki-sitemap"
              "wiki-index"
              "wiki---engineering"
              "wiki---emacs"
              "wiki---languages"
              "wiki---fitness"
              "wiki---linux"
              "wiki---programming"
              "wiki---typography"))
<<wiki-sitemap>>
<<wiki-index>>
<<wiki---engineering>>
<<wiki---emacs>>
<<wiki---languages>>
<<wiki---fitness>>
<<wiki---linux>>
<<wiki---programming>>
<<wiki---typography>>
("wiki-resources"
 :base-directory "resources/"
 :base-extension "css\\|js\\|png"
 :publishing-directory ,(concat org-publish-location-local "wiki.mlnp.fr/resources/")
 :publishing-function org-publish-attachment)
("wiki-fonts"
 :base-directory "resources/fonts/"
 :base-extension "ttf\\|otf"
 :publishing-directory ,(concat org-publish-location-local "wiki.mlnp.fr/resources/fonts/")
 :publishing-function org-publish-attachment)
("wiki-images"
 :base-directory "wiki/images/"
 :base-extension "png\\|jpg"
 :publishing-directory ,(concat org-publish-location-local "wiki.mlnp.fr/images/")
 :publishing-function org-publish-attachment)

4.3.1. Sitemap

("wiki-sitemap"
 :base-directory "wiki/"
 :base-extension "org"
 :publishing-directory ,(concat org-publish-location-local "wiki.mlnp.fr/")
 :recursive t ; Encompass all wiki pages.
 :html-head "<link rel='stylesheet' type='text/css' href='https://wiki.mlnp.fr/resources/global.css'/>
       <link rel='icon' type='image/png' href='https://wiki.mlnp.fr/resources/favicon.png'/>"
 :auto-sitemap t
 :sitemap-title "Full sitemap for [[https://wiki.mlnp.fr][wiki.mlnp.fr]]"
 :publishing-function org-html-publish-to-html)

4.3.2. Index

("wiki-index"
 :base-directory "wiki/"
 :base-extension "org"
 :publishing-directory ,(concat org-publish-location-local "wiki.mlnp.fr/")
 :recursive nil ; Only top-level wiki pages.
 :html-head "<link rel='stylesheet' type='text/css' href='https://wiki.mlnp.fr/resources/global.css'/>
      <link rel='icon' type='image/png' href='https://wiki.mlnp.fr/resources/favicon.png'/>"
 :auto-sitemap nil
 :publishing-function org-html-publish-to-html)

4.3.3. Engineering

("wiki---engineering"
 :base-directory "wiki/engineering"
 :base-extension "org"
 :publishing-directory ,(concat org-publish-location-local "wiki.mlnp.fr/engineering")
 :recursive t
 :html-head "<link rel='stylesheet' type='text/css' href='https://wiki.mlnp.fr/resources/global.css'/>
      <link rel='icon' type='image/png' href='https://wiki.mlnp.fr/resources/favicon.png'/>"
 :auto-sitemap t
 :sitemap-filename "index.org"
 :html-link-up "https://wiki.mlnp.fr/engineering/"
 :html-link-home "https://wiki.mlnp.fr"
 :publishing-function org-html-publish-to-html)

4.3.4. Emacs

("wiki---emacs"
 :base-directory "wiki/emacs"
 :base-extension "org"
 :publishing-directory ,(concat org-publish-location-local "wiki.mlnp.fr/emacs")
 :recursive t
 :html-head "<link rel='stylesheet' type='text/css' href='https://wiki.mlnp.fr/resources/global.css'/>
      <link rel='icon' type='image/png' href='https://wiki.mlnp.fr/resources/favicon.png'/>"
 :auto-sitemap t
 :sitemap-filename "index.org"
 :html-link-up "https://wiki.mlnp.fr/emacs/"
 :html-link-home "https://wiki.mlnp.fr"
 :publishing-function org-html-publish-to-html)

4.3.5. Languages

("wiki---languages"
 :base-directory "wiki/languages"
 :base-extension "org"
 :publishing-directory ,(concat org-publish-location-local "wiki.mlnp.fr/languages")
 :recursive t
 :html-head "<link rel='stylesheet' type='text/css' href='https://wiki.mlnp.fr/resources/global.css'/>
      <link rel='icon' type='image/png' href='https://wiki.mlnp.fr/resources/favicon.png'/>"
 :auto-sitemap t
 :sitemap-filename "index.org"
 :html-link-up "https://wiki.mlnp.fr/languages/"
 :html-link-home "https://wiki.mlnp.fr"
 :publishing-function org-html-publish-to-html)

4.3.6. Linux

("wiki---linux"
 :base-directory "wiki/linux"
 :base-extension "org"
 :publishing-directory ,(concat org-publish-location-local "wiki.mlnp.fr/linux")
 :recursive t
 :html-head "<link rel='stylesheet' type='text/css' href='https://wiki.mlnp.fr/resources/global.css'/>
      <link rel='icon' type='image/png' href='https://wiki.mlnp.fr/resources/favicon.png'/>"
 :auto-sitemap t
 :sitemap-filename "index.org"
 :html-link-up "https://wiki.mlnp.fr/linux/"
 :html-link-home "https://wiki.mlnp.fr"
 :publishing-function org-html-publish-to-html)

4.3.7. Programming

("wiki---programming"
 :base-directory "wiki/programming"
 :base-extension "org"
 :publishing-directory ,(concat org-publish-location-local "wiki.mlnp.fr/programming")
 :recursive t
 :html-head "<link rel='stylesheet' type='text/css' href='https://wiki.mlnp.fr/resources/global.css'/>
      <link rel='icon' type='image/png' href='https://wiki.mlnp.fr/resources/favicon.png'/>"
 :auto-sitemap t
 :sitemap-filename "index.org"
 :html-link-up "https://wiki.mlnp.fr/programming/"
 :html-link-home "https://wiki.mlnp.fr"
 :publishing-function org-html-publish-to-html)

4.3.8. Fitness

("wiki---fitness"
 :base-directory "wiki/fitness"
 :base-extension "org"
 :publishing-directory ,(concat org-publish-location-local "wiki.mlnp.fr/fitness")
 :recursive t
 :html-head "<link rel='stylesheet' type='text/css' href='https://wiki.mlnp.fr/resources/global.css'/>
      <link rel='icon' type='image/png' href='https://wiki.mlnp.fr/resources/favicon.png'/>"
 :auto-sitemap t
 :sitemap-filename "index.org"
 :html-link-up "https://wiki.mlnp.fr/fitness/"
 :html-link-home "https://wiki.mlnp.fr"
 :publishing-function org-html-publish-to-html)

4.3.9. Typography

("wiki---typography"
 :base-directory "wiki/typography"
 :base-extension "org"
 :publishing-directory ,(concat org-publish-location-local "wiki.mlnp.fr/typography")
 :recursive t
 :html-head "<link rel='stylesheet' type='text/css' href='https://wiki.mlnp.fr/resources/global.css'/>
      <link rel='icon' type='image/png' href='https://wiki.mlnp.fr/resources/favicon.png'/>"
 :auto-sitemap t
 :sitemap-filename "index.org"
 :html-link-up "https://wiki.mlnp.fr/typography/"
 :html-link-home "https://wiki.mlnp.fr"
 :publishing-function org-html-publish-to-html)

4.4. blog.mlnp.fr

("blog.mlnp.fr"
 :components ("blog-main-pages"
              "blog-resources"
              "blog-fonts"))
("blog-main-pages"
 :base-directory "blog/"
 :base-extension "org"
 :publishing-directory ,(concat org-publish-location-local "blog.mlnp.fr/")
 :recursive t
 :html-head "<link rel='stylesheet' type='text/css' href='https://blog.mlnp.fr/resources/global.css'/>
<link rel='icon' type='image/png' href='https://blog.mlnp.fr/resources/favicon.png'/>"
 :auto-sitemap t
 :sitemap-filename "index.org"
 :sitemap-title "Sitemap for [[https://blog.mlnp.fr][blog.mlnp.fr]]"
 :sitemap-sort-files chronologically
 :publishing-function org-html-publish-to-html)
("blog-resources"
 :base-directory "resources/"
 :base-extension "css\\|js\\|png"
 :publishing-directory ,(concat org-publish-location-local "blog.mlnp.fr/resources/")
 :publishing-function org-publish-attachment)
("blog-fonts"
 :base-directory "resources/fonts/"
 :base-extension "ttf\\|otf"
 :publishing-directory ,(concat org-publish-location-local "blog.mlnp.fr/resources/fonts/")
 :publishing-function org-publish-attachment)

4.5. apps.mlnp.fr

("apps.mlnp.fr"
 :components ("apps-homepage"
              "apps-resources"
              "apps-fonts"))
("apps-homepage"
 :base-directory "apps/"
 :base-extension "org"
 :publishing-directory ,(concat org-publish-location-local "apps.mlnp.fr/")
 :recursive t
 :html-head "<link rel='stylesheet' type='text/css' href='https://apps.mlnp.fr/resources/global.css'/>
<link rel='icon' type='image/png' href='https://apps.mlnp.fr/resources/favicon.png'/>"
 :auto-sitemap t
 :sitemap-filename "sitemap.org"
 :sitemap-title "Sitemap for [[https://apps.mlnp.fr][apps.mlnp.fr]]"
 :sitemap-sort-files chronologically
 :publishing-function org-html-publish-to-html)
("apps-resources"
 :base-directory "resources/"
 :base-extension "css\\|js\\|png"
 :publishing-directory ,(concat org-publish-location-local "apps.mlnp.fr/resources/")
 :publishing-function org-publish-attachment)
("apps-fonts"
 :base-directory "resources/fonts/"
 :base-extension "ttf\\|otf"
 :publishing-directory ,(concat org-publish-location-local "apps.mlnp.fr/resources/fonts/")
 :publishing-function org-publish-attachment)

5. Main publishing logic   main

This is the main publishing logic. Execute the following source block to build the entire website. 

;; Never interrupt website publishing by asking to confirm evaluation
;; of source blocks.
(setq org-confirm-babel-evaluate nil)

<<org-publish-locations>>
<<org-publish-component>>
<<org-publish-project-alist>>

;; (org-publish-remove-all-timestamps)

;; Prepare resources:
(org-babel-tangle-file "resources/css-global.org")
(org-babel-tangle-file "resources/css-cv.org")
(save-window-excursion
  (find-file "cv.org")
  (org-ascii-export-to-ascii))

(org-publish org-publish-component)

;; Publish selected resources:
(let* ((local org-publish-location-local)
       (local-websites (concat local "*mlnp.fr"))
       (remote org-publish-location-remote)
       (sync-command (format "rsync -azvP %s %s --chown=mpeter:www-data" local-websites remote)))
  (if (not (yes-or-no-p "Push local changes to remote target? "))
      (message "Didn't publish remotely to %s." remote)
    (message
     "Publishing local changes at %s to remote %s." local remote)
    (async-shell-command sync-command)))

The following links to the locally built homepages are useful after building the website locally, to check that everything proceeded smoothly.

Main site
file:///tmp/mlnp.fr/index.html
Wiki
file:///tmp/wiki.mlnp.fr/index.html
Blog
file:///tmp/blog.mlnp.fr/index.html
Apps
file:///tmp/apps.mlnp.fr/index.html

Date: 2022-01-26 Wed 00:00

Author: Marius Peter

Created: 2024-01-02 Tue 19:35

Validate