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" />
#+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. Using Org mode for designing,
building and publishing a website brings the following 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.


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


** Location

Two possible publishing locations are considered:

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

#+NAME: org-publish-location
#+BEGIN_SRC elisp
  (setq org-publish-location
        (read-answer
         "Should the website be built on the local or remote target? "
         '(("/tmp/"
            ?l "build website on the local machine")
           ("/ssh:root@192.162.71.223:/var/www/"
            ?r "build website on the remote machine"))))
#+END_SRC


** Components

We outline three components: the main site, the wiki, and the blog.

#+NAME: org-publish-component
#+begin_src elisp
  (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")
           ("all"
            ?a "build all websites"))))
#+end_src


* Resources


** CSS

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


** JS

The 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= and
=blog.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 elisp :noweb yes
  (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>>
          ("all"
           :components ("mlnp.fr"
                        "wiki.mlnp.fr"
                        "blog.mlnp.fr"))))
#+END_SRC


** =mlnp.fr=

#+NAME: mlnp.fr
#+BEGIN_SRC emacs-lisp
  ("mlnp.fr"
   :components ("mlnp-main-pages"
                "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 "mlnp.fr/")
   :recursive nil ; Main site pages are all in top-level org directory.
   :publishing-function org-html-publish-to-html)
  ("mlnp-resources"
   :base-directory "resources/"
   :base-extension "css\\|js"
   :publishing-directory ,(concat org-publish-location "mlnp.fr/resources/")
   :publishing-function org-publish-attachment)
  ("resources-pages"
   :base-directory "resources/"
   :base-extension "org"
   :publishing-directory ,(concat org-publish-location "mlnp.fr/resources/")
   :publishing-function org-html-publish-to-html)
  ("mlnp-fonts"
   :base-directory "resources/fonts/"
   :base-extension "ttf\\|otf"
   :publishing-directory ,(concat org-publish-location "mlnp.fr/resources/fonts/")
   :publishing-function org-publish-attachment)
#+END_SRC


** =wiki.mlnp.fr=

#+NAME: wiki.mlnp.fr
#+BEGIN_SRC emacs-lisp
  ("wiki.mlnp.fr"
   :components ("wiki-main-pages"
                "wiki-resources"
                "wiki-fonts"))
  ("wiki-main-pages"
   :base-directory "wiki/"
   :base-extension "org"
   :publishing-directory ,(concat org-publish-location "wiki.mlnp.fr/")
   :recursive t
   :html-head "<link rel='stylesheet' type='text/css' href='http://wiki.mlnp.fr/resources/mlnp.css'>"
   :auto-sitemap t
   :sitemap-title "Sitemap for [[http://wiki.mlnp.fr][wiki.mlnp.fr]]"
   :publishing-function org-html-publish-to-html)
  ("wiki-resources"
   :base-directory "resources/"
   :base-extension "css\\|js"
   :publishing-directory ,(concat org-publish-location "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 "wiki.mlnp.fr/resources/fonts/")
   :publishing-function org-publish-attachment)
#+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 "blog.mlnp.fr/")
   :recursive t
   :html-head "<link rel='stylesheet' type='text/css' href='http://blog.mlnp.fr/resources/mlnp.css'>"
   :auto-sitemap t
   :sitemap-title "Sitemap for [[http://blog.mlnp.fr][blog.mlnp.fr]]"
   :sitemap-sort-files anti-chronologically
   :publishing-function org-html-publish-to-html)
  ("blog-resources"
   :base-directory "resources/"
   :base-extension "css\\|js"
   :publishing-directory ,(concat org-publish-location "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 "blog.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 elisp :noweb no-export
  <<org-publish-location>>
  <<org-publish-component>>
  <<org-publish-project-alist>>

  (org-babel-tangle-file "resources/css.org")
  (org-publish-remove-all-timestamps)

  (org-publish org-publish-component)
  (format "Successfully built %s!" org-publish-component)
#+END_SRC

#+RESULTS: main
: Successfully built wiki.mlnp.fr component!


Link to the locally built homepages:

- Main site :: [[file:/tmp/mlnp.fr/index.html]]
- Wiki :: [[file:/tmp/wiki.mlnp.fr/index.html]]
- Blog :: [[file:/tmp/blog.mlnp.fr/index.html]]


* TODO Export resume to txt upon publishing