diff options
authorThomas Letan <>2020-08-29 11:36:59 +0200
committerThomas Letan <>2020-08-29 12:11:46 +0200
commit23e5c85eea4d7c7086392ca4b14e097682cb3829 (patch)
parentf5c04971fa2f64b467c4f0de176b9251848378a9 (diff)
Start the documentation of the theme build process
4 files changed, 61 insertions, 29 deletions
diff --git a/.gitignore b/.gitignore
index 002b3cc..1907ea8 100644
--- a/.gitignore
+++ b/.gitignore
@@ -21,9 +21,9 @@ plugins/external-urls.lua
diff --git a/site/ b/site/
index e5f8437..67fd917 100644
--- a/site/
+++ b/site/
@@ -36,7 +36,7 @@ written as literate programs.
<article class="index">
-- [[./cleopatra/][Theming with SASS ~(TODO)~]] ::
+- [[./cleopatra/][Theming and Templating]] ::
- [[file:cleopatra/][Authoring Contents As Coq Documents ~(TODO)~]] ::
diff --git a/site/cleopatra/ b/site/cleopatra/
index df6c513..e6f7a9a 100644
--- a/site/cleopatra/
+++ b/site/cleopatra/
@@ -128,6 +128,9 @@ dl
font : normal normal normal 11px/1 ForkAwesome
+ padding-left : 2rem
+ .org-src-tangled-to,
font-family : 'Fira Code', monospace
font-size : 70%
diff --git a/site/cleopatra/ b/site/cleopatra/
index 79f1921..fe68690 100644
--- a/site/cleopatra/
+++ b/site/cleopatra/
@@ -2,40 +2,37 @@
<h1>Theming and Templating</h1>
-#+BEGIN_SRC makefile :tangle
-SASS := site/style/main.sass
-CSS := $(SASS:.sass=.css)
-theme-build : ${SASS}
- @cleopatra echo Compiling "${CSS}"
- @sassc --style=compressed --sass ${SASS} ${CSS}
+The purpose of this build process is to implement the default layout of this
+website. To that end, it provides a template file (~main.html~), and a
+collection of SASS files that *~cleopatra~* then compiles into a single CSS file
+using ~sassc~.
-soupault-build : theme-build
+We first discuss the structure of the website, by defining the default HTML
+template =soupault= will use to generate the website. Then, we specify its
+minimal design, implemented in SASS. Finally, we discuss the necessary build
+instructions for *~cleopatra~*.
* Main HTML Template
-#+BEGIN_SRC html :tangle templates/main.html :noweb no-export
+#+BEGIN_SRC html :tangle templates/main.html :noweb yes
<html lang="en">
- <<head>>
+ <head>
+ <<meta-tags>>
+ <title><!-- page title will be inserted here --></title>
+ <<syncloading_html>>
+ <<asyncloading_html>>
+ </head></head>
** ~<head>~
-#+NAME: head
+#+NAME: meta-tags
#+BEGIN_SRC html :noweb no-export
- <meta charset="utf-8">
- <meta name="viewport"
- content="width=device-width, initial-scale=1.0">
- <title></title>
- <<syncloading_html>>
- <<asyncloading_html>>
+<meta charset="utf-8">
+<meta name="viewport"
+ content="width=device-width, initial-scale=1.0">
*** Assets Loading
@@ -74,7 +71,7 @@ noscript.parentNode.removeChild(noscript);
#+NAME: body
#+BEGIN_SRC html :noweb no-export
-<body id="default">
<li> <a href="/news">News</a></li>
@@ -83,8 +80,7 @@ noscript.parentNode.removeChild(noscript);
- <!-- your page content will be inserted here,
- see the content_selector option in soupault.conf -->
+ <!-- page content will be inserted here -->
<img src=""
@@ -102,8 +98,8 @@ noscript.parentNode.removeChild(noscript);
This website has been generated using a collection of <a
href="/posts/Thanks.html">awesome free software projects</a>. You can have
- a look at <a href="">the source of
- this webpage</a> or <a href="/cleopatra.html">how it is being
+ a look at <a href="">the source
+ of this website</a> or <a href="/cleopatra.html">how it is being
generated</a>, and if you have find an error, feel free to <a
href="">shoot me a friendly email</a>.
@@ -179,3 +175,36 @@ pre
@import org
@import coq
+* Build Instructions
+The build instruction are pretty straightforward. We start by how to compile the
+main CSS file.
+#+BEGIN_SRC makefile :tangle
+SASS := $(wildcard site/style/*.sass)
+MAIN_SASS := site/style/main.sass
+CSS := $(MAIN_SASS:.sass=.css)
+${CSS} : ${SASS}
+ @cleopatra echo Compiling "${CSS}"
+ @sassc --style=compressed --sass ${MAIN_SASS} ${CSS}
+Since the HTML template does not need any particular processing, the
+=theme-build= phase is only responsible for generating the main CSS file. The
+[[./][=soupault= build phase]] needs to start after the CSS file is
+compiled (since it copies all relevant files to the ~build/~ directory), so we
+explicit this dependency.
+#+BEGIN_SRC makefile :tangle
+theme-build : ${CSS}
+soupault-build : theme-build
+Therefore, at the end of this generation process only one file has been
+#+BEGIN_SRC makefile :tangle