Use mkdocs-macros

.readthedocs.yaml

@@ -0,0 +1,9 @@
+version: 2
+
+mkdocs:
+  configuration: docs/mkdocs.yml
+
+python:
+   version: 3.8
+   install:
+   - requirements: docs/requirements.txt

docs/docs/apps.md

@@ -1,37 +1,35 @@
-<!-- This document describes the usage of the python-appimage utility
+{# This document describes the usage of the python-appimage utility.
 
-The intended audience is developers. In addition, this document also provides
-some tips for packaging Python based applications.
--->
+   The intended audience is developers. In addition, this document also provides
+   some tips for packaging Python based applications.
+#}
 
-<script src="../js/highlight.min.js" defer></script>
-<script src="../js/apps.js" defer></script>
+{{ importjs("highlight.min") }}
+{{ importjs("apps") }}
+
+{% include "references.md" %}
 
 
 # Developers corner
 
-Python [AppImages][APPIMAGE] are built with the `python-appimage`{.inline}
-utility, available from [PyPI][PYPI]. This utility can also help packaging
-Python based applications as AppImages, using an existing Python AppImage and a
-recipe folder.
-{.justify}
+Python [AppImages][APPIMAGE] are built with the `python-appimage` utility,
+available from [PyPI][PYPI]. This utility can also help packaging Python based
+applications as AppImages, using an existing Python AppImage and a recipe
+folder.
 
 !!! Caution
-    The `python-appimage`{.inline} utility can only package applications that
-    can be directly installed with `pip`{.inline}. For more advanced usage, one
-    needs to extract the Python AppImage and to edit it, e.g. as explained in
-    the [Advanced installation](index.md#advanced-installation) section.
-    Additional details on this use case are provided
-    [below](#advanced-packaging).
-    {.justify}
+    The `python-appimage` utility can only package applications that can be
+    directly installed with `pip`. For more advanced usage, one needs to extract
+    the Python AppImage and to edit it, e.g. as explained in the [Advanced
+    installation](index.md#advanced-installation) section.  Additional details
+    on this use case are provided [below](#advanced-packaging).
 
 
 ## Building a Python AppImage
 
-The primary scope of `python-appimage`{.inline} is to relocate an existing
-Python installation inside an AppDir, and to build the corresponding AppImage.
-For example, the following
-{.justify}
+The primary scope of `python-appimage` is to relocate an existing Python
+installation inside an AppDir, and to build the corresponding AppImage.  For
+example, the following
 
 ```bash
 python-appimage build local -p $(which python2)
@@ -41,74 +39,62 @@ should build an AppImage of your local Python 2 installation, provided that it
 exists.
 
 !!! Tip
-    Help on available arguments and options to `python-appimage`{.inline} can be
-    obtained with the `-h`{.inline .language-bash} flag. For example,
-    `python-appimage build local -h`{.inline .language-none} provides help on
-    local builds.
-    {.justify}
+    Help on available arguments and options to `python-appimage` can be obtained
+    with the `-h` flag. For example, `python-appimage build local -h` provides
+    help on local builds.
 
 
-<div markdown="1" class="capsule">
+{{ begin(".capsule") }}
 ### Auxiliary tools
 
-The `python-appimage`{.inline} utility relies on auxiliary tools that are
-downloaded and installed at runtime, on need. Those are
-[appimagetool][APPIMAGETOOL] for building AppImages, and [patchelf][PATCHELF] in
-order to edit ELFs runtime paths (`RPATH`{.inline}). Auxiliary tools are
-installed to the the user space. One can get their location with the
-`which`{.inline .language-none} command word. For example,
-{.justify}
+The `python-appimage` utility relies on auxiliary tools that are downloaded and
+installed at runtime, on need. Those are [appimagetool][APPIMAGETOOL] for
+building AppImages, and [patchelf][PATCHELF] in order to edit ELFs runtime paths
+(`RPATH`). Auxiliary tools are installed to the the user space. One can get
+their location with the `which` command word. For example,
 
 ```bash
 python-appimage which appimagetool
 ```
 
-returns the location of `appimagetool`{.inline}, if it has been installed. If
-not, the `install`{.inline} command word can be used in order to trigger its
-installation.
-{.justify}
-</div>
+returns the location of `appimagetool`, if it has been installed. If not, the
+`install` command word can be used in order to trigger its installation.
+{{ end(".capsule") }}
 
 
 ## Manylinux Python AppImage
 
-AppImages of your local `python`{.inline} are unlikely to be portable, except if
-you run an ancient Linux distribution. Indeed, a core component preventing
-portability across Linuses is the use of different versions of the
-`glibc`{.inline} system library. Hopefully, `glibc`{.inline} is highly backward
-compatible. Therefore, a simple work-around is to compile binaries using the
-oldest Linux distro you can afford to.  This is the strategy used for creating
-portable AppImages, as well as for distributing Python site packages as
-ready-to-use binary [wheels][WHEELS].
-{.justify}
+AppImages of your local `python` are unlikely to be portable, except if you run
+an ancient Linux distribution. Indeed, a core component preventing portability
+across Linuses is the use of different versions of the `glibc` system library.
+Hopefully, `glibc` is highly backward compatible. Therefore, a simple
+work-around is to compile binaries using the oldest Linux distro you can afford
+to.  This is the strategy used for creating portable AppImages, as well as for
+distributing Python site packages as ready-to-use binary [wheels][WHEELS].
 
 The Python Packaging Authority (PyPA) has defined standard platform tags for
 building Python site packages, labelled [manylinux][MANYLINUX].  These build
 platforms are available as Docker images with various versions of Python already
-installed. The `python-appimage`{.inline} utility can be used to package those
-installs as AppImages. For example, the following command
-{.justify}
+installed. The `python-appimage` utility can be used to package those installs
+as AppImages. For example, the following command
 
 ```bash
 python-appimage build manylinux 2014_x86_64 cp310-cp310
 ```
 
 should build an AppImage of Python 3.10 using the CPython (_cp310-cp310_)
-install found in the `manylinux2014_x86_64`{.inline} Docker image.
-{.justify}
+install found in the `manylinux2014_x86_64` Docker image.
 
 !!! Note
     Docker needs to be already installed on your system in order to build
     Manylinux Python images. However, the command above can be run on the host.
     That is, you need **not** to explictly shell inside the manylinux Docker
     image.
-    {.justify}
 
 !!! Tip
     A compilation of ready-to-use Manylinux Python AppImages is available from
-    the [releases][RELEASES] area of the `python-appimage`{.inline} [GitHub
+    the [releases][RELEASES] area of the `python-appimage` [GitHub
     repository][GITHUB]. These AppImages are updated weekly, on every Sunday.
-    {.justify}
 
 
 ## Simple packaging
@@ -116,26 +102,12 @@ install found in the `manylinux2014_x86_64`{.inline} Docker image.
 The recipe folder contains
 the app metadata, a Python requirements file and an entry point script. Examples
 of recipes can be found on GitHub in the [applications][APPLICATIONS] folder.
-{.justify}
 
 
 ## Advanced packaging
 
 Alternatively, you can also manualy extract one of the Python
 [AppImages][APPIMAGE] as explained above and directly modify the content, e.g.
-`pip install`{.inline} your custom packages. Then, simply rebuild the AppImage
-using your favourite tool, e.g.  [appimagetool][APPIMAGETOOL],
-[linuxdeploy][LINUXDEPLOY] or `python-appimage`{.inline}.
-{.justify}
-
-
-[APPIMAGE]: https://appimage.org
-[APPIMAGETOOL]: https://appimage.github.io/appimagetool
-[APPLICATIONS]: https://github.com/niess/python-appimage/tree/master/applications
-[GITHUB]: https://github.com/niess/python-appimage
-[LINUXDEPLOY]: https://github.com/linuxdeploy/linuxdeploy
-[MANYLINUX]: https://github.com/pypa/manylinux
-[PATCHELF]: https://github.com/NixOS/patchelf
-[PYPI]: https://pypi.org/project/python-appimage
-[RELEASES]: https://github.com/niess/python-appimage/releases
-[WHEELS]: https://pythonwheels.com/
+`pip install` your custom packages. Then, simply rebuild the AppImage using your
+favourite tool, e.g.  [appimagetool][APPIMAGETOOL], [linuxdeploy][LINUXDEPLOY]
+or `python-appimage`.

docs/docs/css/extra.css

@@ -1,13 +1,14 @@
 /* Text justification */
-.justify {
+.justify, p {
     text-align: justify;
     text-justify: inter-word;
 }
 
-
 /* Patch for code highlighting */
-code.inline {
-    background: transparent !important;
+.rst-content code,
+.rst-content .admonition code,
+.inline code {
+    background: transparent;
     color: black;
     display: inline;
     overflow-wrap: break-word;

docs/docs/index.md

@@ -1,13 +1,15 @@
-<!-- This document describes the usage of Python AppImages, as runtimes.
+{# This document describes the usage of Python AppImages, as runtimes.
 
-Note that some parts of this document are generated dynamically according to the
-reader's system configuration, and depending on released AppImages. The intent
-is to provide relevant examples to the reader, as well as a dynamic summary of
-available Python AppImages.
--->
+   Note that some parts of this document are generated dynamically according to
+   the reader's system configuration, and depending on released AppImages. The
+   intent is to provide relevant examples to the reader, as well as a dynamic
+   summary of available Python AppImages.
+#}
 
-<script src="js/highlight.min.js" defer></script>
-<script src="js/index.js" defer></script>
+{{ importjs("highlight.min") }}
+{{ importjs("index") }}
+
+{% include "references.md" %}
 
 
 # Python AppImages
@@ -15,110 +17,103 @@ available Python AppImages.
 We provide relocatable Python runtimes for _Linux_ systems, as
 [AppImages][APPIMAGE]. These runtimes have been extracted from
 [manylinux][MANYLINUX] Docker images.
-{.justify .append-releases-list}
+{{ "" | id("append-releases-list") }}
 
 ## Basic installation
 
 Installing Python from an [AppImage][APPIMAGE] is as simple as downloading a
 single file and changing its mode to executable. For example, as
-{.justify}
 
-``` { .bash #basic-installation-example }
+{{ begin("#basic-installation-example") }}
+```bash
 wget https://github.com/niess/python-appimage/releases/download\
 /python3.10/python3.10.2-cp310-cp310-manylinux2014_x86_64.AppImage
 
 chmod +x python3.10.2-cp310-cp310-manylinux2014_x86_64.AppImage
 ```
+{{ end("#basic-installation-example") }}
 
 !!! Note
     As can be seen from the previous [example](#basic-installation-example), the
     AppImage name contains several informations. That are, the Python full
-    version (*3.10.2*{#example-full-version}), the CPython tag
-    (*cp310-cp310*{#example-python-tag}), the Linux compatibility tag
-    (*manylinux2014*{#example-linux-tag}) and the machine architecture
-    (*x86_64*{#example-arch-tag}).
-    {.justify}
+    version ({{ "3.10.2" | id("example-full-version") }}), the CPython tag
+    ({{ "cp310-cp310" | id("example-python-tag") }}), the Linux compatibility
+    tag ({{ "manylinux2014" | id("example-linux-tag") }}) and the machine
+    architecture ({{ "x86_64" | id("example-arch-tag") }}).
 
 !!! Caution
     One needs to **select an AppImage** that matches **system requirements**. A
     summmary of available Python AppImages is provided at the
     [bottom](#available-python-appimages) of this page.
-    {.justify}
 
 
-<div markdown="1" class="capsule">
+{{ begin(".capsule") }}
 ### Creating a symbolic link
 
 Since AppImages native names are rather lengthy, one might create a symbolic
 link, e.g. as
-{.justify}
 
-``` { .bash #basic-installation-example-symlink }
+{{ begin("#basic-installation-example-symlink") }}
+```bash
 ln -s python3.10.2-cp310-cp310-manylinux2014_x86_64.AppImage python3.10
 ```
+{{ end("#basic-installation-example-symlink") }}
 
 Then, executing the AppImage as
-`./python3.10`{#basic-installation-example-execution .inline} should start a
-Python interactive session on _almost_ any Linux, provided that **fuse** is
-supported.
-{.justify}
-</div>
-
+{{ "`./python3.10`" | id("basic-installation-example-execution") }} should
+start a Python interactive session on _almost_ any Linux, provided that **fuse**
+is supported.
+{{ end(".capsule") }}
 
 !!! Tip
     Fuse is not supported on Windows Subsytem for Linux v1 (WSL1), preventing
     AppImages direct execution. Yet, one can still extract the content of Python
     AppImages and use them, as explained in the [Advanced
     installation](#advanced-installation) section.
-    {.justify}
 
 
 ## Installing site packages
 
-Site packages can be installed using `pip`{.inline}, distributed with the
-AppImage. For example, the following
-{.justify}
+Site packages can be installed using `pip`, distributed with the AppImage. For
+example, the following
 
-``` {.bash #site-packages-example}
+{{ begin("#site-packages-example") }}
+```bash
 ./python3.10 -m pip install numpy
 ```
+{{ end("#site-packages-example") }}
 
 installs the numpy package, where it is assumed that a symlink to the AppImage
 has been previously created. When using the **basic installation** scheme, by
 default Python packages are installed to your **user space**, i.e. under
-`~/.local`{.inline} on Linux.
-{.justify}
+`~/.local` on Linux.
 
 !!! Note
     AppImage are read-only. Therefore, site packages cannot be directly
     installed to the AppImage. However, the AppImage can be extracted, as
     explained in the [Advanced installation](#advanced-installation) section.
-    {.justify}
 
 
-<div markdown="1" class="capsule">
+{{ begin(".capsule") }}
 ### Alternative site packages location
 
 One can
 specify an alternative installation directory for site packages using the
-`--target`{.inline .language-bash} option of pip. For example, the following
-{.justify}
+`--target` option of pip. For example, the following
 
-``` {.bash #site-packages-example-target}
+{{ begin("#site-packages-example-target") }}
+```bash
 ./python3.10 -m pip install --target=$(pwd)/packages numpy
 ```
+{{ end("#site-packages-example-target") }}
 
-installs the numpy package besides the AppImage, in a `packages`{.inline}
-folder.
-{.justify}
-</div>
+installs the numpy package besides the AppImage, in a `packages` folder.
+{{ end(".capsule") }}
 
 !!! Tip
-    Packages installed in non standard locations are not automatically
-    found by Python. Their location must be aded to
-    `sys.path`{.inline .language-python}, e.g. using the
-    `PYTHONPATH`{.inline .language-bash} environment variable.
-    {.justify}
+    Packages installed in non standard locations are not automatically found by
+    Python. Their location must be aded to `sys.path`, e.g. using the
+    `PYTHONPATH` environment variable.
 
 !!! Caution
     While Python AppImages are relocatable, site packages might not be. In
@@ -126,40 +121,34 @@ folder.
     location of the Python runtime. If the Python AppImage is moved, then these
     scripts will fail. This can be patched by editing the script
     [shebang][SHEBANG], or be reinstalling the corresponding package.
-    {.justify}
 
 
 ## Isolating from the user space
 
 Python AppImages are not isolated from the user space. Therefore, by default
-site packages located under `~/.local`{.inline} are loaded instead of system
-ones.  Note that this is the usual Python runtime behaviour. However, it can be
-conflictual in some cases.
-{.justify}
+site packages located under `~/.local` are loaded instead of system ones.  Note
+that this is the usual Python runtime behaviour. However, it can be conflictual
+in some cases.
 
-In order to disable user site packages, one can use the
-`-s`{.inline .language-bash} option of the Python runtime. For example,
-invoking the Python AppImage as
-`./python3.10 -s`{.inline .language-bash #user-isolation-example} prevents user
-packages to be loaded.
-{.justify}
+In order to disable user site packages, one can use the `-s` option of the
+Python runtime. For example, invoking the Python AppImage as {{ "`./python3.10
+-s`" | id("user-isolation-example") }} prevents user packages to be loaded.
 
 
 ## Using a virtual environement
 
 Isolation can also be achieved with a [virtual environment][VENV]. Python
-AppImages can create a `venv`{.inline} using the standard syntax, e.g. as
-{.justify}
+AppImages can create a `venv` using the standard syntax, e.g. as
 
-``` {.bash #venv-example}
+{{ begin("#venv-example") }}
+```bash
 ./python3.10 -m venv /path/to/new/virtual/environment
 ```
+{{ end("#venv-example") }}
 
-However, the virtual environment fails setting up `pip`{.inline}, despite the
-latter is packaged with the AppImage. Yet, this can be patched by calling
-`ensurepip`{.inline} from within the `venv`{.inline}, after its creation. For
-example, as
-{.justify}
+However, the virtual environment fails setting up `pip`, despite the latter is
+packaged with the AppImage. Yet, this can be patched by calling `ensurepip` from
+within the `venv`, after its creation.  For example, as
 
 ```bash
 source /path/to/new/virtual/environment/bin/activate
@@ -173,48 +162,47 @@ python -m ensurepip
 The [basic installation](#basic-installation) scheme described previously has
 some limitations when using Python AppImages as a runtime. For example,  site
 packages need to be installed to a separate location. This can be solved by
-extracting a Python AppImage to an `*.AppDir`{.inline} directory, e.g. as
-{.justify}
+extracting a Python AppImage to an `*.AppDir` directory, e.g. as
+
 
-``` {.bash #advanced-installation-example}
+{{ begin("#advanced-installation-example") }}
+```bash
 ./python3.10.2-cp310-cp310-manylinux2014_x86_64.AppImage --appimage-extract
 
 mv squashfs-root python3.10.2-cp310-cp310-manylinux2014_x86_64.AppDir
 
 ln -s python3.10.2-cp310-cp310-manylinux2014_x86_64.AppDir/AppRun python3.10
 ```
+{{ end("#advanced-installation-example") }}
 
 Then, by default **site packages** are installed to the extracted **AppDir**,
-when using `pip`{.inline}. In addition, executable scripts installed by
-`pip`{.inline} are patched in order to use relative [shebangs][SHEBANG].
-Consequently, the AppDir can be freely moved around.
-{.justify}
+when using `pip`. In addition, executable scripts installed by `pip` are patched
+in order to use relative [shebangs][SHEBANG].  Consequently, the AppDir can be
+freely moved around.
 
 !!! Note
     Python AppDirs follow the [manylinux][MANYLINUX] installation scheme.
-    Executable scripts are installed under `AppDir/opt/pythonX.Y/bin`{.inline}
-    where _X_ and _Y_ in _pythonX.Y_ stand for the major and minor version
-    numbers. Site packages are located under
-    `AppDir/opt/pythonX.Y/lib/pythonX.Y/site-packages`{.inline}.
-    {.justify}
+    Executable scripts are installed under `AppDir/opt/pythonX.Y/bin` where _X_
+    and _Y_ in _pythonX.Y_ stand for the major and minor version numbers. Site
+    packages are located under
+    `AppDir/opt/pythonX.Y/lib/pythonX.Y/site-packages`.
 
 !!! Tip
     As for Python AppImages, by default the extracted runtime is [not isolated
     from the user space](#isolating-from-the-user-space). This behaviour can be
-    changed by editing the `AppDir/AppRun`{.inline} wrapper script, and by
-    adding the `-s`{.inline .language-bash} option at the very bottom, where
-    Python is invoked.
-    {.justify}
+    changed by editing the `AppDir/AppRun` wrapper script, and by adding the
+    `-s` option at the very bottom, where Python is invoked.
 
 
-<div markdown="1" class="capsule">
+{{ begin(".capsule") }}
 ### Repackaging the AppImage
 
 An extracted AppDir can be re-packaged as an AppImage using
 [appimagetool][APPIMAGETOOL], e.g. as
-{.justify}
 
-``` {.bash #repackaging-example}
+
+{{ begin("#repackaging-example") }}
+```bash
 wget https://github.com/AppImage/AppImageKit/releases/download/continuous/\
 appimagetool-x86_64.AppImage
 
@@ -224,17 +212,16 @@ chmod +x appimagetool-x86_64.AppImage
     python3.10.2-cp310-cp310-manylinux2014_x86_64.AppDir \
     python3.10.2-cp310-cp310-manylinux2014_x86_64.AppImage
 ```
+{{ end("#repackaging-example") }}
 
 This allows to customize your Python AppImage, for example by adding your
 preferred site packages.
-{.justify}
-</div>
+{{ end(".capsule") }}
 
 !!! Note
     Python AppImages can also be used for packaging Python based applications,
     as AppImages. Additional details are provided in the [developers
     section](apps).
-    {.justify}
 
 
 ## Available Python AppImages
@@ -243,22 +230,13 @@ A summary of available Python AppImages [releases][RELEASES] is provided in the
 [table](#appimages-download-links) below. Clicking on a badge should download
 the corresponding AppImage.
 
+{{ begin("#suggest-appimage-download") }}
 !!! Caution
-    According to your browser, your system would not be compatible with Python
-    Appimages.
-    {.justify #suggest-appimage-download}
-
-<div id="appimages-download-links">
-    <p style="color: red; text-align: center">
-        &lt;could not download release data from
-        https://github.com/niess/python-appimage/releases&gt;
-    </p>
-</div>
-
-
-[APPIMAGE]: https://appimage.org
-[APPIMAGETOOL]: https://appimage.github.io/appimagetool
-[MANYLINUX]: https://github.com/pypa/manylinux
-[RELEASES]: https://github.com/niess/python-appimage/releases
-[SHEBANG]: https://en.wikipedia.org/wiki/Shebang_(Unix)
-[VENV]: https://docs.python.org/3/library/venv.html
+    According to your browser, your system would not be compatible with
+    Python Appimages.
+{{ end("#suggest-appimage-download") }}
+
+{{ begin("#appimages-download-links") }}
+!!! Danger
+    Could not download releases metadata from {{ github_api.releases | url }}.
+{{ end("#appimages-download-links") }}

docs/docs/js/apps.js

@@ -1,5 +1,2 @@
 /* Perform the syntaxic highlighting */
-hljs.configure({
-    cssSelector: "code"
-});
 hljs.highlightAll();

docs/docs/js/index.js

@@ -61,7 +61,7 @@ $.getJSON("https://api.github.com/repos/niess/python-appimage/releases").done(fu
         for (const release of releases) {
             elements.push(`<a href="${release.url}">${release.version}</a>`)
         }
-        $(".append-releases-list").append(
+        $("#append-releases-list").append(
             " Available Python versions are " +
             elements.slice(0, -1).join(", ") +
             " and " +
@@ -86,9 +86,14 @@ $.getJSON("https://api.github.com/repos/niess/python-appimage/releases").done(fu
     /* Strip blocks of whitespaces, e.g. at line start */
     function stripws (s) { return s.replace(/  +/g, ""); }
 
+    /* Utility function for setting an inline code */
+    function set_inline (selector, code) {
+        $(selector).children().html(stripws(code));
+    }
+
     /* Utility function for setting a code snippet */
     function set_snippet (selector, code) {
-        $(selector).children().html(stripws(code));
+        $(selector).children().children().html(stripws(code));
     }
 
     /* Generate the examples */
@@ -128,7 +133,7 @@ $.getJSON("https://api.github.com/repos/niess/python-appimage/releases").done(fu
             ln -s ${asset.name} python${release.version}
         `);
 
-        $("#basic-installation-example-execution").html(
+        set_inline("#basic-installation-example-execution",
             `./python${release.version}`
         );
 
@@ -140,8 +145,9 @@ $.getJSON("https://api.github.com/repos/niess/python-appimage/releases").done(fu
             ./python${release.version} -m pip install --target=$(pwd)/packages numpy
         `);
 
-        $("#user-isolation-example").html(
-            `./python${release.version} -s`);
+        set_inline("#user-isolation-example",
+            `./python${release.version} -s`
+        );
 
         set_snippet("#venv-example", `\
             ./python${release.version} -m venv /path/to/new/virtual/environment
@@ -234,27 +240,24 @@ $.getJSON("https://api.github.com/repos/niess/python-appimage/releases").done(fu
         html.push("<caption>Summary of available Python AppImages.</caption>");
         html.push("</table>");
 
-        $("#appimages-download-links").html(html.join("\n"));
+        const element = $("#appimages-download-links");
+        element.html(html.join("\n"));
     }
 
     /* Suggest an AppImage */
     if (host_arch != undefined) {
-        const body = $("#suggest-appimage-download");
-        body.html(stripws(`\
+        const main = $("#suggest-appimage-download").children().first();
+        main.attr("class", "admonition tip");
+        const children = main.children();
+        children.first().text("Tip");
+        children.eq(1).html(stripws(`\
             According to your browser, your system is an ${host_arch} Linux.
             Therefore, we recommend that you download an ${host_arch} AppImage
             with Manylinux ${suggested_appimage.linux} compatibility. For
             example, ${badge(suggested_appimage, false)}.
         `));
-
-        const parents = body.parent();
-        parents.attr("class", "admonition tip");
-        parents.children().first().text("Tip");
     }
 
     /* Perform the syntaxic highlighting */
-    hljs.configure({
-        cssSelector: "code"
-    });
     hljs.highlightAll();
 });

docs/include/references.md

@@ -0,0 +1,14 @@
+{# References used in the documentation #}
+
+[APPIMAGE]: https://appimage.org/
+[APPIMAGETOOL]: https://appimage.github.io/appimagetool/
+[APPLICATIONS]: {{ config.repo_url }}tree/master/applications/
+[GITHUB]: {{ config.repo_url }}
+[LINUXDEPLOY]: https://github.com/linuxdeploy/linuxdeploy/
+[MANYLINUX]: https://github.com/pypa/manylinux/
+[PATCHELF]: https://github.com/NixOS/patchelf/
+[PYPI]: https://pypi.org/project/python-appimaAge/
+[RELEASES]: {{ config.repo_url }}releases/
+[SHEBANG]: https://en.wikipedia.org/wiki/Shebang_(Unix)/
+[VENV]: https://docs.python.org/3/library/venv.html/
+[WHEELS]: https://pythonwheels.com/

docs/main.py

@@ -0,0 +1,93 @@
+import os
+
+def define_env(env):
+    """Custom filters and macros"""
+
+    def format_attributes(*args, **kwargs):
+        """Format HTML attributes"""
+        if args:
+            cls, id_ = [], None
+            for arg in args:
+                if arg[0] == ".":
+                    cls.append(arg[1:])
+                elif arg[0] == "#":
+                    id_ = arg[1:]
+                else:
+                    raise ValueError(f"Invalid attribute ({arg})")
+
+            if cls:
+                try:
+                    kwargs["class"] += " " + " ".join(cls)
+                except KeyError:
+                    kwargs["class"] = " ".join(cls)
+
+            if id_:
+                kwargs["id"] = id_
+
+        if kwargs:
+            attr = []
+            for k, v in kwargs.items():
+                attr.append(f"{k} = \"{v}\"")
+            attr = " ".join(attr)
+        else:
+            attr = ""
+
+        return attr
+
+
+    @env.filter
+    def attr(text, *args, **kwargs):
+        """Add HTML attributes to a text using a <span>"""
+
+        attr = format_attributes(*args, **kwargs)
+
+        return f"<span {attr} markdown=\"1\">{text}</span>"
+
+
+    @env.filter
+    def cls(text, *args):
+        """Add HTML class(es) to a text using a <span>"""
+
+        cls = " ".join(args)
+
+        return f"<span class=\"{cls}\" marckdown=\"1\">{text}</span>"
+
+
+    @env.filter
+    def id(text, id_):
+        """Add HTML id to a text using a <span>"""
+
+        return f"<span id=\"{id_}\" markdown=\"1\">{text}</span>"
+
+
+    @env.filter
+    def url(raw):
+        """Wrap a raw URL with a link"""
+
+        return f"[{raw}]({raw})"
+
+
+    @env.macro
+    def begin(*args, **kwargs):
+        """Start a new HTML <div>"""
+
+        attr = format_attributes(*args, **kwargs)
+
+        return f"<div {attr} markdown=\"1\">"
+
+
+    @env.macro
+    def end(comment=None):
+        """End an HTML <div>"""
+
+        return "</div>"
+
+
+    @env.macro
+    def importjs(name):
+        """Import a JavaScript script"""
+
+        current = "/" + env.page.url
+        relpath = os.path.relpath("/js", start=current)
+
+        return f"<script src=\"{relpath}/{name}.js\" defer></script>"

docs/mkdocs.yml

@@ -3,8 +3,8 @@ site_description: AppImage distributions of Python
 site_author: Valentin Niess
 copyright: GPL-3.0
 
-repo_url: https://github.com/niess/python-appimage
-edit_uri: edit/master/docs/docs
+repo_url: https://github.com/niess/python-appimage/
+edit_uri: edit/master/docs/
 
 nav:
   - Python AppImages: index.md
@@ -15,9 +15,19 @@ theme:
   navigation_depth: 3
   highlightjs: no
 
+plugins:
+  - macros:
+      include_dir: docs/include
+  - search
+
 markdown_extensions:
   - admonition
-  - attr_list
   - md_in_html
 
 extra_css: [css/extra.css, css/nord.min.css]
+
+extra_javascript: [js/apps.js, js/highlight.min.js, js/index.js]
+
+extra:
+  github_api:
+    releases: https://api.github.com/repos/niess/python-appimage/releases

docs/requirements.txt

@@ -1 +1,2 @@
 mkdocs==1.2.3
+mkdocs-macros-plugin==0.6.4