From 4de84e095d0f1fa7f3b5db8904496ffd2752d73e Mon Sep 17 00:00:00 2001
From: Jan Tojnar <jtojnar@gmail.com>
Date: Wed, 25 May 2022 18:51:04 +0200
Subject: [PATCH] doc: Introduce pre-processor for adding anchors to text

It is now possible to use the following syntax to insert anchors into the text:

    []{#anchor-name}

The anchor will allow linking to the location it is placed by appending #anchor-name to the URL.

Additionally, it is possible to create a link pointing to its own location by adding text between the square brackets:

    [`--add-root`]{#opt-add-root}
---
 doc/manual/anchors.py | 56 +++++++++++++++++++++++++++++++++++++++++++
 doc/manual/book.toml  |  3 +++
 doc/manual/local.mk   |  2 +-
 3 files changed, 60 insertions(+), 1 deletion(-)
 create mode 100755 doc/manual/anchors.py

diff --git a/doc/manual/anchors.py b/doc/manual/anchors.py
new file mode 100755
index 000000000..2a93b2a67
--- /dev/null
+++ b/doc/manual/anchors.py
@@ -0,0 +1,56 @@
+#!/usr/bin/env python3
+
+import argparse
+import json
+import re
+import sys
+
+
+empty_anchor_regex = re.compile(r"\[\]\{#(?P<anchor>[^\}]+?)\}")
+anchor_regex = re.compile(r"\[(?P<text>[^\]]+?)\]\{#(?P<anchor>[^\}]+?)\}")
+
+
+def transform_anchors_html(content):
+    content = empty_anchor_regex.sub(r'<a name="\g<anchor>"></a>', content)
+    content = anchor_regex.sub(r'<a href="#\g<anchor>" id="\g<anchor>">\g<text></a>', content)
+    return content
+
+
+def transform_anchors_strip(content):
+    content = empty_anchor_regex.sub(r'', content)
+    content = anchor_regex.sub(r'\g<text>', content)
+    return content
+
+
+def map_contents_recursively(transformer, chapter):
+    chapter["Chapter"]["content"] = transformer(chapter["Chapter"]["content"])
+    for sub_item in chapter["Chapter"]["sub_items"]:
+        map_contents_recursively(transformer, sub_item)
+
+
+def supports_command(args):
+    sys.exit(0)
+
+
+def process_command(args):
+    context, book = json.load(sys.stdin)
+    transformer = transform_anchors_html if context["renderer"] == "html" else transform_anchors_strip
+    for section in book["sections"]:
+        map_contents_recursively(transformer, section)
+    print(json.dumps(book))
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(
+        description="mdBook preprocessor adding anchors."
+    )
+    parser.set_defaults(command=process_command)
+
+    subparsers = parser.add_subparsers()
+
+    supports_parser = subparsers.add_parser("supports", help="Check if given renderer is supported")
+    supports_parser.add_argument("renderer", type=str)
+    supports_parser.set_defaults(command=supports_command)
+
+    args = parser.parse_args()
+    args.command(args)
diff --git a/doc/manual/book.toml b/doc/manual/book.toml
index fee41dfb3..75554d11f 100644
--- a/doc/manual/book.toml
+++ b/doc/manual/book.toml
@@ -1,2 +1,5 @@
 [output.html]
 additional-css = ["custom.css"]
+
+[preprocessor.anchors]
+command = "python3 doc/manual/anchors.py"
diff --git a/doc/manual/local.mk b/doc/manual/local.mk
index c1ce8aaeb..910d0a03b 100644
--- a/doc/manual/local.mk
+++ b/doc/manual/local.mk
@@ -97,7 +97,7 @@ doc/manual/generated/man1/nix3-manpages: $(d)/src/command-ref/new-cli
 	done
 	@touch $@
 
-$(docdir)/manual/index.html: $(MANUAL_SRCS) $(d)/book.toml $(d)/custom.css $(d)/src/SUMMARY.md $(d)/src/command-ref/new-cli $(d)/src/command-ref/conf-file.md $(d)/src/expressions/builtins.md $(call rwildcard, $(d)/src, *.md)
+$(docdir)/manual/index.html: $(MANUAL_SRCS) $(d)/book.toml $(d)/anchors.py $(d)/custom.css $(d)/src/SUMMARY.md $(d)/src/command-ref/new-cli $(d)/src/command-ref/conf-file.md $(d)/src/expressions/builtins.md $(call rwildcard, $(d)/src, *.md)
 	$(trace-gen) RUST_LOG=warn mdbook build doc/manual -d $(DESTDIR)$(docdir)/manual
 
 endif