Kozea · srkunze · Apr 19, 2026
diff --git a/1.1.html b/1.1.html
@@ -1,11 +1,11 @@
 <!DOCTYPE html>
 <html lang="en">
 <meta charset="utf-8">
-<noscript><meta http-equiv="Refresh" content="0; url=v1.html"></noscript>
+<noscript><meta http-equiv="Refresh" content="0; url=html/v1/index.html"></noscript>
 <meta name="viewport" content="width=device-width, initial-scale=1">
 <link href="https://github.com/Kozea/Radicale/releases.atom" type="application/atom+xml" rel="alternate" title="Radicale Releases">
 <title>Redirect</title>
-<p>Please follow <a href="v1.html" id="link">this link</a>.</p>
+<p>Please follow <a href="html/v1/index.html" id="link">this link</a>.</p>
 <script>
   link.href += (window.location.search || "") + (window.location.hash || "");
   window.location.replace(link.href);

diff --git a/2.1.html b/2.1.html
@@ -1,11 +1,11 @@
 <!DOCTYPE html>
 <html lang="en">
 <meta charset="utf-8">
-<noscript><meta http-equiv="Refresh" content="0; url=v2.html"></noscript>
+<noscript><meta http-equiv="Refresh" content="0; url=html/v2/index.html"></noscript>
 <meta name="viewport" content="width=device-width, initial-scale=1">
 <link href="https://github.com/Kozea/Radicale/releases.atom" type="application/atom+xml" rel="alternate" title="Radicale Releases">
 <title>Redirect</title>
-<p>Please follow <a href="v2.html" id="link">this link</a>.</p>
+<p>Please follow <a href="html/v2/index.html" id="link">this link</a>.</p>
 <script>
   link.href += (window.location.search || "") + (window.location.hash || "");
   window.location.replace(link.href);

diff --git a/3.3.html b/3.3.html
@@ -1,11 +1,11 @@
 <!DOCTYPE html>
 <html lang="en">
 <meta charset="utf-8">
-<noscript><meta http-equiv="Refresh" content="0; url=v3.html"></noscript>
+<noscript><meta http-equiv="Refresh" content="0; url=html/v3/index.html"></noscript>
 <meta name="viewport" content="width=device-width, initial-scale=1">
 <link href="https://github.com/Kozea/Radicale/releases.atom" type="application/atom+xml" rel="alternate" title="Radicale Releases">
 <title>Redirect</title>
-<p>Please follow <a href="v3.html" id="link">this link</a>.</p>
+<p>Please follow <a href="html/v3/index.html" id="link">this link</a>.</p>
 <script>
   link.href += (window.location.search || "") + (window.location.hash || "");
   window.location.replace(link.href);

diff --git a/README.md b/README.md
@@ -1,15 +1,56 @@
-# Documentation
+# Documentation for Radical Documentation Generation
 
 For the complete documentation, please visit [Radicale Documentation](https://radicale.org/).
 
+
 ## Generator
 
-The HTML documentation is automatically generated from the markdown file
-`DOCUMENTATION.md` in every git branch.
+### Location and Requirements
+The HTML documentation is automatically generated from the markdown files
+in docs/ in every git branch.
+The documentation generator script is located at the `documentation-generator/run.py`.
+Make sure that all MD files added, have `## ...` sections as their top-level
+headings.
+Python 3.9 and Pandoc installable from apt is required.
+
+### Tool Structure
+The script comprise the top-level script `run.py`, a Pandoc filter
+file `filter.py` and an HTML template file `template.html`.
+
+### Functional Principle
+For each git release branch, we restore the complete `docs/` folder of
+the last release commit and move it to `md/{release_name}/`.
+We do so, by using the `git restore` command in order to avoid messing
+with the working copy.
+
+HINT: make sure that all MD files are sorted by prefix `00_`, `01_`, `02_`, ...
+Otherwise, we don't know what content to put first, second, etc.
+
+Then, again for each git release branch, we convert all respective MD files into
+a single large HTML file and postprocess it to ensure integrity.
+We also augment links by their respective future HTML file.
+
+The last step is to extract smaller HTML files per MD file provided.
+As the hrefs have already been fixed in the previous step, links will
+still work.
+
+For Github Actions, we make sure to install all dependencies first and
+add, commit + push all changes into the current branch.
+
+### Static assets
+
+Static assets live in `assets/`.
+
+
+## Usage
+
+### locally
+Set your working directory somewhere inside the repository so git finds it.
+Python 3.9 is required.
+Install all dependencies listed in the Python function `install_dependencies`.
+
+### by Github Actions
+`documentation-generator/run.py` is executed by the GitHub Actions workflow `.github/workflows/generate-documentation.yml`.
 
-The documentation generator script is located in the `documentation-generator`
-directory.
-It is executed by the GitHub Actions workflow
-`.github/workflows/generate-documentation.yml`.
 Generated HTML files and `index.html` that redirects to the latest version are
-committed to this branch.
+committed to branch gh-pages.
diff --git a/assets/navigation.js b/assets/navigation.js
@@ -14,7 +14,8 @@ window.addEventListener("DOMContentLoaded", function() {
     let sections = [[document.querySelector("main"), null]];
     for (let section of document.querySelectorAll("section")) {
         let id = section.getAttribute("id");
-        let link = nav.querySelector("a[href=\\#" + id.replace(/\//g, "\\/") + "]");
+        let filename = window.location.pathname.split('/').pop();
+        let link = nav.querySelector("a[href='./" + filename + "#" + id.replace(/\//g, "\\/") + "']");
         if (link) {
             link = link.parentElement;
             link.classList.remove("active");

diff --git a/documentation-generator/filter.py b/documentation-generator/filter.py
diff --git a/documentation-generator/postprocessor.py b/documentation-generator/postprocessor.py