path: root/publish-mlnp.org

# -*- mode: org; -*-

#+TITLE: Publish
#+SUBTITLE: Guide to publishing this very website.
#+AUTHOR: Marius Peter
#+DATE: <2022-01-26 Wed>
#+OPTIONS: toc:nil

#+HTML_HEAD: <link rel="stylesheet" type="text/css" href="resources/mlnp.css"/>
#+HTML_HEAD: <link rel="icon" type="image/png" href="resources/favicon.png"/>
#+INCLUDE: resources/topnav.html export html


#+begin_abstract
In the spirit of [[https://en.wikipedia.org/wiki/Literate_programming][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.
#+end_abstract

#+TOC: headlines 3


* Introduction

This entire website is built with [[https://orgmode.org/][Org mode]], an Emacs mode designed for
literate programming among other things.


** 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.


** 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.

#+NAME: tree
#+BEGIN_SRC bash :results verbatim :exports both
  tree -F -L 2
#+END_SRC

#+RESULTS: tree
#+begin_example
./
├── README.org
├── about.org
├── apps/
│   ├── index.org
│   └── sitemap.org
├── blog/
│   ├── 2022/
│   ├── 2023/
│   └── index.org
├── cv.org
├── cv.txt
├── index.org
├── publish-mlnp.html
├── publish-mlnp.org
├── resources/
│   ├── css.org
│   ├── favicon.png
│   ├── favicon.xcf
│   ├── fonts/
│   ├── mlnp.css
│   └── topnav.html
├── sitemap.org
└── wiki/
    ├── emacs/
    ├── engineering/
    ├── fitness/
    ├── images/
    ├── index-with-images.org.bkp
    ├── index.html
    ├── index.org
    ├── languages/
    ├── linux/
    ├── programming/
    ├── sitemap.org
    └── typography/

15 directories, 20 files
#+end_example


* 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?


** 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 [[http://mlnp.fr/][mlnp.fr]].

We follow the recommendation outlined in the manual's [[https://orgmode.org/manual/Uploading-Files.html][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.

#+NAME: org-publish-locations
#+BEGIN_SRC emacs-lisp
  (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/")))
#+END_SRC


** 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.

#+NAME: org-publish-component
#+begin_src emacs-lisp
  (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"))))
#+end_src


* Resources


** CSS

The website styling information is described on the [[file:resources/css.org][CSS]] page.


** JS

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


* COMMENT HTML preamble

#+NAME: org-publish-html-preamble
#+BEGIN_SRC emacs-lisp
  (setq org-publish-html-preamble nil)
  ;; (setq org-publish-html-preamble
  ;;       (concat
  ;;        "<nav id='topnav'>
  ;; <a href='index.html' id='home'><code>home</code></a>
  ;; <label for='hamburger'>&#9776;</label>
  ;; <input type='checkbox' id='hamburger'/>"
  ;;        (progn
  ;;        (save-window-excursion
  ;;          (find-file "resources/topnav-items.org")
  ;;          (org-html-export-to-html nil nil nil t nil))
  ;;          (org-file-contents "resources/topnav-items.html"))
  ;;        "</nav>"))
#+END_SRC


* 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.

#+NAME: org-publish-project-alist
#+BEGIN_SRC emacs-lisp :noweb no-export :results pp
    (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"))))
#+END_SRC


** 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.

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

#+NAME: all-styles
#+BEGIN_SRC emacs-lisp
  ("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)
#+END_SRC


** =mlnp.fr=

#+NAME: mlnp.fr
#+BEGIN_SRC emacs-lisp
  ("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"
   :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)
#+END_SRC


** =wiki.mlnp.fr=

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

#+NAME: wiki.mlnp.fr
#+BEGIN_SRC emacs-lisp :noweb no-export
  ("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)
#+END_SRC


*** Sitemap

#+NAME: wiki-sitemap
#+BEGIN_SRC emacs-lisp
  ("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/mlnp.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)
#+END_SRC


*** Index

#+NAME: wiki-index
#+BEGIN_SRC emacs-lisp
  ("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/mlnp.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)
#+END_SRC


*** Engineering

#+NAME: wiki---engineering
#+BEGIN_SRC emacs-lisp
  ("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/mlnp.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)
#+END_SRC


*** Emacs

#+NAME: wiki---emacs
#+BEGIN_SRC emacs-lisp
  ("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/mlnp.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)
#+END_SRC


*** Languages

#+NAME: wiki---languages
#+BEGIN_SRC emacs-lisp
  ("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/mlnp.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)
#+END_SRC


*** Linux

#+NAME: wiki---linux
#+BEGIN_SRC emacs-lisp
  ("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/mlnp.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)
#+END_SRC


*** Programming

#+NAME: wiki---programming
#+BEGIN_SRC emacs-lisp
  ("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/mlnp.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)
#+END_SRC


*** Fitness

#+NAME: wiki---fitness
#+BEGIN_SRC emacs-lisp
  ("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/mlnp.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)
#+END_SRC


*** Typography

#+NAME: wiki---typography
#+BEGIN_SRC emacs-lisp
  ("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/mlnp.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)
#+END_SRC


** =blog.mlnp.fr=

#+NAME: blog.mlnp.fr
#+BEGIN_SRC emacs-lisp
   ("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/mlnp.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)
#+END_SRC


** =apps.mlnp.fr=

#+NAME: apps.mlnp.fr
#+BEGIN_SRC emacs-lisp
   ("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/mlnp.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)
#+END_SRC


* Main publishing logic                                     :main:

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

#+NAME: main
#+BEGIN_SRC emacs-lisp :noweb no-export
  ;; 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.org")
  (save-window-excursion
    (find-file "cv.org")
    (org-ascii-export-to-ascii))

  (org-publish org-publish-component)

  (let* ((local org-publish-location-local)
         (local-websites (concat local "*mlnp.fr"))
         (remote org-publish-location-remote)
         (sync-command (format "rsync -azvP %s %s" 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)))
#+END_SRC

#+RESULTS: main
: #<window 257 on *Async Shell 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]]