preprocess microkit tutorial for Jekyll

- process {{#include ... }} directives
- replace {{#tab ... }} directives with Jekyll includes

Signed-off-by: Gerwin Klein <gerwin.klein@proofcraft.systems>

.gitignore

@@ -9,3 +9,4 @@ projects/virtualization/docs/api/
 .jekyll-cache/
 vendor/
 node_modules/
+_processed/microkit-tutorial/

Makefile

@@ -57,6 +57,18 @@ _repos/tutes/%.md: _repos/sel4proj/sel4-tutorials/tutorials/% _repos/tutes
 TUTORIALS:= $(filter-out index.md get-the-tutorials.md how-to.md pathways.md setting-up.md,$(notdir $(wildcard Tutorials/*.md)))
 tutorials: ${TUTORIALS:%=_repos/tutes/%}
 
+PROCESS_MDBOOK = _scripts/process-mdbook.py
+MICROKIT_TUT_DST = _processed/microkit-tutorial
+MICROKIT_TUT_SRC = _repos/au-ts/microkit_tutorial/website/src
+MICROKIT_TUT_SRC_FILES = $(wildcard $(MICROKIT_TUT_SRC)/*.md)
+MICROKIT_TUT_DST_FILES = $(patsubst $(MICROKIT_TUT_SRC)/%, $(MICROKIT_TUT_DST)/%, $(MICROKIT_TUT_SRC_FILES))
+
+$(MICROKIT_TUT_DST)/%.md: $(MICROKIT_TUT_SRC)/%.md
+	@echo "$<  ==>  $@"
+	@$(PROCESS_MDBOOK) $< $(dir $@)
+
+microkit-tutorial: $(MICROKIT_TUT_DST_FILES)
+
 _generate_api_pages: $(REPOSITORIES)
 	$(MAKE) markdown -C _repos/sel4/sel4/manual
 
@@ -93,7 +105,7 @@ docker_build:
 serve: build
 	JEKYLL_ENV=$(JEKYLL_ENV) bundle exec jekyll serve
 
-build: generate_api ruby_deps $(REPOSITORIES)
+build: generate_api ruby_deps microkit-tutorial $(REPOSITORIES)
 	$(MAKE) tutorials
 ifeq ($(JEKYLL_ENV),production)
 	$(MAKE) generate_data_files

_processed/README.md

@@ -0,0 +1,16 @@
+<!--
+    Copyright 2025 Proofcraft Pty Ltd
+    SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# Target directory for generated files
+
+This is target directory directory for generated/processed files based on data
+or input taken from other repositories in `../_repos`.
+
+- `tutes/` contains processed md files from the sel4-tutorials repository
+
+- `microkit-tutorial/` contains processed md files from the microkit-tutorial
+  repo.
+
+These files will then be included via Jekyll/Liquid tags elsewhere in the site.

_scripts/process-mdbook.py

@@ -0,0 +1,68 @@
+#! /usr/bin/env python3
+
+# Copyright 2025 Proofcraft Pty Ltd
+# SPDX-License-Identifier: BSD-2-Clause
+
+# Process mdbook .md files to
+#  - execute `{{#include "path/to/file.md"}}` directives
+#  - convert tab directives Jekyll includes used in the docsite
+
+import os
+import re
+import argparse
+
+def inclusion_content(input_path, match):
+    include_path = match.group(1)
+    start_line = match.group(2)
+    end_line = match.group(3)
+
+    full_path = os.path.join(input_path, include_path)
+    if os.path.exists(full_path):
+        with open(full_path, 'r', encoding='utf-8') as inc_file:
+            lines = inc_file.read().splitlines()
+            if start_line is None:
+                start_line = 1
+            if end_line is None:
+                end_line = len(lines)
+            else:
+                end_line = int(end_line)
+            # Return the specified lines as a string
+            return '\n'.join(lines[int(start_line)-1:end_line])
+    else:
+        print(f'Include file {include_path} not found in {input_path}')
+        return f'<!-- Include file {include_path} not found -->'
+
+def process_mdbook(input_file, output_dir):
+    if not os.path.exists(output_dir):
+        os.makedirs(output_dir)
+
+    # Read entire input file
+    with open(input_file, 'r', encoding='utf-8') as f:
+        content = f.read()
+
+    # Process include directives with line numbers
+    include_pattern = re.compile(r'{{#include[ ]*([^ :]+)(?::(\d+):(\d+))?[ ]*}}')
+    input_path = os.path.dirname(input_file)
+    content = re.sub(include_pattern, lambda match: inclusion_content(input_path, match), content)
+
+    # Convert tab directives to Jekyll includes
+    # {{#tabs }}, {{#endtabs }}, {{#endtab }}
+    pat = re.compile(r'{{#([a-z]*tabs?)[ ]*}}')
+    content = re.sub(pat, r'{% include \1.html %}', content)
+
+    # "{{#tab name="Linux" }}"
+    pat = re.compile(r'{{#tab name="([^"]+)"[ ]*}}')
+    content = re.sub(pat, r'{% include tab.html title="\1" %}', content)
+
+    # Write processed content
+    output_file = os.path.join(output_dir, os.path.basename(input_file))
+    with open(output_file, 'w', encoding='utf-8') as f:
+        f.write(content)
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description='Process mdbook .md files for includes and tabs.')
+    parser.add_argument('input_file', help='Path to the input .md file')
+    parser.add_argument('output_dir', help='Directory to save the processed output')
+
+    args = parser.parse_args()
+    process_mdbook(args.input_file, args.output_dir)

projects/microkit/tutorial/end.md

@@ -5,4 +5,4 @@ SPDX-FileCopyrightText: 2025 Ivan Velickovic
 ---
 
 {% include include_external_markdown.md
-           file="_repos/au-ts/microkit_tutorial/website/src/end.md" %}
+           file="_processed/microkit-tutorial/end.md" %}

projects/microkit/tutorial/part0.md

@@ -5,4 +5,4 @@ SPDX-FileCopyrightText: 2025 Ivan Velickovic
 ---
 
 {% include include_external_markdown.md
-           file="_repos/au-ts/microkit_tutorial/website/src/part0.md" %}
+           file="_processed/microkit-tutorial/part0.md" %}

projects/microkit/tutorial/part1.md

@@ -5,4 +5,4 @@ SPDX-FileCopyrightText: 2025 Ivan Velickovic
 ---
 
 {% include include_external_markdown.md
-           file="_repos/au-ts/microkit_tutorial/website/src/part1.md" %}
+           file="_processed/microkit-tutorial/part1.md" %}

projects/microkit/tutorial/part2.md

@@ -5,4 +5,4 @@ SPDX-FileCopyrightText: 2025 Ivan Velickovic
 ---
 
 {% include include_external_markdown.md
-           file="_repos/au-ts/microkit_tutorial/website/src/part2.md" %}
+           file="_processed/microkit-tutorial/part2.md" %}

projects/microkit/tutorial/part3.md

@@ -5,4 +5,4 @@ SPDX-FileCopyrightText: 2025 Ivan Velickovic
 ---
 
 {% include include_external_markdown.md
-           file="_repos/au-ts/microkit_tutorial/website/src/part3.md" %}
+           file="_processed/microkit-tutorial/part3.md" %}

projects/microkit/tutorial/part4.md

@@ -5,4 +5,4 @@ SPDX-FileCopyrightText: 2025 Ivan Velickovic
 ---
 
 {% include include_external_markdown.md
-           file="_repos/au-ts/microkit_tutorial/website/src/part4.md" %}
+           file="_processed/microkit-tutorial/part4.md" %}

projects/microkit/tutorial/rpi3b.md

@@ -5,4 +5,4 @@ SPDX-FileCopyrightText: 2025 Ivan Velickovic
 ---
 
 {% include include_external_markdown.md
-           file="_repos/au-ts/microkit_tutorial/website/src/rpi3b.md" %}
+           file="_processed/microkit-tutorial/rpi3b.md" %}

projects/microkit/tutorial/welcome.md

@@ -5,4 +5,4 @@ SPDX-FileCopyrightText: 2025 Ivan Velickovic
 ---
 
 {% include include_external_markdown.md
-           file="_repos/au-ts/microkit_tutorial/website/src/welcome.md" %}
+           file="_processed/microkit-tutorial/welcome.md" %}