Add internal link rewriting for navigation and improve section switching logic

- Automatically rewrite markdown file links to section anchors
- Preserve external links and non-section markdown links
- Monitor hash links and enable section switching without page reloads
- Centralize functionality with added tests for validation

Author: Martin Mahner

CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## Version 1.1.0 (TBD)
+
+### Added
+
+- **Internal link rewriting** - Automatically converts markdown file links to section navigation
+  - Links to files that are included as sections (e.g., `[CHANGELOG](CHANGELOG.md)`) are rewritten to section anchors (`#changelog`)
+  - Preserves external links and links to files that aren't sections
+  - Centralized hash link monitoring with Alpine.js integration
+  - Clicking any hash link now properly triggers section switching without page reloads
+  - Added 4 tests for link rewriting functionality in `test_builder.py`
+
 ## Version 1.0.0 (2025-11-13)
 
 🎉 **First stable release!** Microdocs is now production-ready with comprehensive test coverage, CI/CD workflows, and a stable API.

microdocs/builder.py

@@ -8,6 +8,7 @@
 from __future__ import annotations
 
 import html
+import re
 import sys
 from datetime import UTC, datetime
 from pathlib import Path
@@ -93,6 +94,37 @@ def convert_plain_text_to_html(text_content: str) -> str:
     return f"<div>{html_with_breaks}</div>"
 
 
+def rewrite_internal_links(html_content: str, section_ids: set[str]) -> str:
+    """
+    Rewrite links to markdown files into section navigation links.
+
+    If a link points to a file that exists as a section (e.g., CHANGELOG.md),
+    rewrite it to navigate to that section instead of loading the file.
+
+    Args:
+        html_content: HTML content with links
+        section_ids: Set of section IDs (lowercased file stems)
+
+    Returns:
+        HTML with rewritten internal links
+
+    """
+
+    def replace_link(match: re.Match[str]) -> str:
+        href = match.group(1)
+        # Check if link is to a markdown file
+        if href.endswith((".md", ".markdown")):
+            # Extract the stem (filename without extension) and lowercase it
+            link_stem = Path(href).stem.lower()
+            # If this matches a section ID, rewrite to section link
+            if link_stem in section_ids:
+                return f'href="#{link_stem}"'
+        return match.group(0)
+
+    # Match href attributes in anchor tags
+    return re.sub(r'href="([^"]+)"', replace_link, html_content)
+
+
 def build_documentation(
     input_files: Sequence[Path],
     output_path: Path,
@@ -134,6 +166,9 @@ def build_documentation(
         sys.stdout.write(f"Reading CSS from {css_path}\n")
         inlined_css = css_path.read_text(encoding="utf-8")
 
+    # First pass: collect section IDs
+    section_ids = {input_file.stem.lower() for input_file in input_files}
+
     # Process each markdown file
     converted_sections = []
     extracted_title = None
@@ -156,6 +191,9 @@ def build_documentation(
             sys.stdout.write(f"Converting {input_file.name} as plain text...\n")
             html_content = convert_plain_text_to_html(file_content)
 
+        # Rewrite internal links to point to sections instead of files
+        html_content = rewrite_internal_links(html_content, section_ids)
+
         # Build section data
         section_id = input_file.stem.lower()
         converted_sections.append(

microdocs/templates/default.html

@@ -31,15 +31,29 @@
             document.documentElement.setAttribute('data-theme', value);
             });
             document.documentElement.setAttribute('data-theme', theme);
+
+            // Monitor hash link clicks and update activeSection
+            document.addEventListener('click', (e) => {
+            const link = e.target.closest('a[href^=\'#\']');
+            if (link) {
+            const hash = link.getAttribute('href');
+            const sectionId = hash.substring(1);
+            const sectionIds = [{% for section in sections %}'{{ section.id }}'{% if not loop.last %}, {% endif %}{% endfor %}];
+            if (sectionIds.includes(sectionId)) {
+            e.preventDefault();
+            activeSection = sectionId;
+            }
+            }
+            });
            ">
     <!-- Header -->
     <header class="z-50 sticky top-0 bg-doc-bg border-b border-doc-border">
       <div class="max-w-5xl mx-auto px-4 py-3 sm:px-6 sm:py-4">
         <!-- Desktop Layout -->
         <div class="hidden sm:flex sm:gap-8 sm:items-center">
           <!-- Logo/Title -->
-          <h1 class="font-heading font-semibold text-doc-heading text-xl cursor-pointer" @click="activeSection = '{{ sections[0].id }}'">
-            <a @click="activeSection = '{{ sections[0].id }}'" href="">{{ title }}</a>
+          <h1 class="font-heading font-semibold text-doc-heading text-xl">
+            <a href="#{{ sections[0].id }}" class="cursor-pointer">{{ title }}</a>
           </h1>
 
           <!-- Navigation -->
@@ -86,8 +100,8 @@ <h1 class="font-heading font-semibold text-doc-heading text-xl cursor-pointer" @
         <div class="sm:hidden">
           <!-- Top Row: Title and Icons -->
           <div class="flex gap-4 items-center justify-between mb-3">
-            <h1 class="font-heading font-semibold text-doc-heading text-lg cursor-pointer" @click="activeSection = '{{ sections[0].id }}'">
-              <a @click="activeSection = '{{ sections[0].id }}'" href=".">{{ title }}</a>
+            <h1 class="font-heading font-semibold text-doc-heading text-lg">
+              <a href="#{{ sections[0].id }}" class="cursor-pointer">{{ title }}</a>
             </h1>
 
             <div class="flex shrink-0 gap-3 items-center">

microdocs/tests/test_builder.py

@@ -406,3 +406,92 @@ def test_build_documentation_file_not_found(temp_output_path: Path) -> None:
             input_files=[Path("/nonexistent/file.md")],
             output_path=temp_output_path,
         )
+
+
+# Tests for rewrite_internal_links
+
+
+def test_rewrite_internal_links_rewrites_section_links(tmp_path: Path) -> None:
+    """Test that links to markdown files that are sections get rewritten."""
+    readme = tmp_path / "README.md"
+    readme.write_text(
+        "# Main\n\nSee the [CHANGELOG](CHANGELOG.md) for details.",
+        encoding="utf-8",
+    )
+
+    changelog = tmp_path / "CHANGELOG.md"
+    changelog.write_text("# Changelog\n\n## v1.0", encoding="utf-8")
+
+    output = tmp_path / "output.html"
+    build_documentation(
+        input_files=[readme, changelog],
+        output_path=output,
+    )
+
+    content = output.read_text(encoding="utf-8")
+    # Link should be rewritten to section anchor
+    assert 'href="#changelog"' in content
+    # Original file link should not be present
+    assert "CHANGELOG.md" not in content or 'href="#changelog"' in content
+
+
+def test_rewrite_internal_links_preserves_external_links(tmp_path: Path) -> None:
+    """Test that external links are not rewritten."""
+    readme = tmp_path / "README.md"
+    readme.write_text(
+        "# Main\n\nVisit [GitHub](https://github.com)",
+        encoding="utf-8",
+    )
+
+    output = tmp_path / "output.html"
+    build_documentation(
+        input_files=[readme],
+        output_path=output,
+    )
+
+    content = output.read_text(encoding="utf-8")
+    # External link should remain unchanged
+    assert 'href="https://github.com"' in content
+
+
+def test_rewrite_internal_links_preserves_non_section_markdown_links(
+    tmp_path: Path,
+) -> None:
+    """Test that links to markdown files that aren't sections remain unchanged."""
+    readme = tmp_path / "README.md"
+    readme.write_text(
+        "# Main\n\nSee [other doc](other.md)",
+        encoding="utf-8",
+    )
+
+    output = tmp_path / "output.html"
+    build_documentation(
+        input_files=[readme],
+        output_path=output,
+    )
+
+    content = output.read_text(encoding="utf-8")
+    # Link to non-section file should remain as-is
+    assert 'href="other.md"' in content
+
+
+def test_rewrite_internal_links_case_insensitive(tmp_path: Path) -> None:
+    """Test that link rewriting is case-insensitive."""
+    readme = tmp_path / "README.md"
+    readme.write_text(
+        "# Main\n\nSee [Action](ACTION.md)",
+        encoding="utf-8",
+    )
+
+    action = tmp_path / "ACTION.md"
+    action.write_text("# Action\n\nDetails", encoding="utf-8")
+
+    output = tmp_path / "output.html"
+    build_documentation(
+        input_files=[readme, action],
+        output_path=output,
+    )
+
+    content = output.read_text(encoding="utf-8")
+    # Link should be rewritten to lowercase section anchor
+    assert 'href="#action"' in content