[Feat] Automatically link glossary entries

.editorconfig

@@ -0,0 +1,8 @@
+root = true
+
+[*.py]
+profile = black
+indent_style = space
+indent_size = 4
+src_paths = src,tests
+

.isort.cfg

@@ -0,0 +1,3 @@
+[settings]
+profile=black
+src_paths=src,tests

Makefile

@@ -1,12 +1,14 @@
-.PHONY: help run build preview aggregate aggregate-repo aggregate-update-repo aggregate-repo-single aggregate-update-repo-single test-aggregate-local clean clean-projects clean-aggregated-git test test-unit test-integration check spelling linkcheck woke
+.PHONY: help run build preview publish transform aggregate aggregate-repo aggregate-update-repo aggregate-repo-single aggregate-update-repo-single test-aggregate-local clean clean-projects clean-aggregated-git test test-unit test-integration check spelling linkcheck woke glossary glossary-check format
 
 help:
 	@echo "Garden Linux Documentation Hub - Available targets:"
 	@echo ""
 	@echo "  Development:"
 	@echo "    run                    - Run docs development server"
-	@echo "    build                  - Build documentation for production"
+	@echo "    build                  - Build documentation for test purposes"
+	@echo "    transform              - Run transformation on aggregated docs (may leave work tree 'dirty')"
 	@echo "    preview                - Preview production build locally"
+	@echo "    publish                - Build documentation with transformation for publishing"
 	@echo ""
 	@echo "  Testing:"
 	@echo "    test                   - Run full test suite (unit + integration)"
@@ -18,6 +20,8 @@ help:
 	@echo "    spelling               - Check spelling with codespell"
 	@echo "    linkcheck              - Check links with lychee"
 	@echo "    woke                   - Check inclusive language with woke"
+	@echo "    glossary               - Process glossary links in documentation"
+	@echo "    glossary-check         - Validate glossary structure"
 	@echo ""
 	@echo "  Documentation Aggregation:"
 	@echo "    aggregate-local        - Aggregate from local repos (file:// URLs in repos-config.local.json)"
@@ -45,43 +49,6 @@ install:
 	pip install git+https://github.com/gardenlinux/python-gardenlinux-lib.git@2a27700198bc91e0f9b8321960ebc4709d65c41a
 	pip install -r requirements.txt
 
-run:
-	pnpm run docs:dev
-
-build: install clean aggregate
-	pnpm run docs:build
-
-preview:
-	pnpm run docs:preview
-
-# Testing
-test: test-unit test-integration
-	@echo "All tests passed!"
-
-test-unit:
-	@echo "Running unit tests..."
-	python3 -m pytest tests/unit/ -v
-
-test-integration:
-	@echo "Running integration tests..."
-	python3 -m pytest tests/integration/ -v
-
-# Quality Checks
-check: spelling linkcheck woke
-	@echo "All quality checks passed!"
-
-spelling:
-	@echo "Running spelling checks..."
-	@pnpm run docs:spelling
-
-linkcheck:
-	@echo "Running link checks..."
-	@pnpm run docs:linkcheck
-
-woke:
-	@echo "Running inclusive language checks..."
-	@pnpm run docs:woke
-
 # Documentation Aggregation
 aggregate-local:
 	@echo "Aggregating from local repositories (relative paths)..."
@@ -139,6 +106,61 @@ aggregate-update-repo-single:
 		$(if $(REF),--override-ref $(REF)) \
 		$(if $(COMMIT),--override-commit $(COMMIT))
 
+run:
+	pnpm run docs:dev
+
+build: install clean aggregate
+	pnpm run docs:build
+
+transform: aggregate glossary
+	@echo "Transforming content. This may have lead to an unclean worktree and is completely normal."
+
+publish: install clean aggregate glossary
+	pnpm run docs:build
+
+preview:
+	pnpm run docs:preview
+
+format:
+	black src/ tests/
+	isort src/ tests/
+
+# Testing
+test: test-unit test-integration
+	@echo "All tests passed!"
+
+test-unit:
+	@echo "Running unit tests..."
+	python3 -m pytest tests/unit/ -v
+
+test-integration:
+	@echo "Running integration tests..."
+	python3 -m pytest tests/integration/ -v
+
+# Quality Checks
+check: spelling linkcheck woke
+	@echo "All quality checks passed!"
+
+spelling:
+	@echo "Running spelling checks..."
+	@pnpm run docs:spelling
+
+linkcheck:
+	@echo "Running link checks..."
+	@pnpm run docs:linkcheck
+
+woke:
+	@echo "Running inclusive language checks..."
+	@pnpm run docs:woke
+
+glossary:
+	@echo "Processing glossary links..."
+	@python3 src/aggregation/auto_glossary.py docs/
+
+glossary-check:
+	@echo "Validating glossary structure..."
+	@python3 src/aggregation/auto_glossary.py docs/ --check
+
 # Utilities
 clean:
 	@echo "Cleaning build artifacts and aggregated docs..."

docs/contributing/documentation/auto-glossary.md

@@ -0,0 +1,211 @@
+---
+title: "Documentation Auto Glossary"
+description: "Automatically link common idioms to their glossary entry"
+order: 13 
+related_topics:
+  - /contributing/documentation/documentation_workflow.md
+  - /contributing/documentation/writing_good_docs.md
+  - /contributing/documentation/adding-repos.md
+  - /contributing/documentation/working-locally.md
+  - /contributing/documentation/ci-architecture.md
+  - /contributing/documentation/ci-workflows-reference.md
+  - /contributing/documentation/configuration.md
+  - /contributing/documentation/technical.md
+  - /contributing/documentation/testing.md
+  - /contributing/documentation/vitepress-features.md
+---
+
+# Auto Glossary
+
+The documentation system includes an automatic glossary linker that converts marked terms into links pointing to the glossary page.
+
+## Quick Start
+
+Mark terms in your documentation using the marker format:
+
+```markdown
+Deploy {glossary:Gardenlinux} on {glossary:AWS} using {glossary:KVM}.
+```
+
+After aggregation, this becomes:
+
+```markdown
+Deploy [Gardenlinux](/reference/glossary#gardenlinux) on [AWS](/reference/glossary#aws) using [KVM](/reference/glossary#kvm).
+```
+
+## Function
+
+During aggregation (`make aggregate`), the system:
+
+1. Parses `docs/reference/glossary.md` to extract all level-3 headers as terms
+2. Extracts aliases from terms with parenthesized expansions (e.g., `ADR (Architecture Decision Record)`)
+3. Scans all markdown files for glossary markers
+4. Replaces markers with markdown links to glossary anchors
+5. Preserves code blocks, inline code, and existing links
+
+## Marking Terms
+
+Use the format where the term name matches a glossary entry:
+
+```markdown
+{glossary:AWS}
+{glossary:Garden Linux}
+{glossary:ADR (Architecture Decision Record)}
+```
+
+Term matching is case-insensitive but preserves your original formatting:
+
+- Input: `{glossary:aws}` produces `[aws](/reference/glossary#aws)`
+- Input: `{glossary:AWS}` produces `[AWS](/reference/glossary#aws)`
+
+::: details Developer Information
+The auto glossary system is designed to accept a new custom `entry_format` through which
+the shortcode `{glossary:*}` can be replaced with a new custom pattern.
+
+Check the source code for more information.
+:::
+
+## Protected Regions
+
+The system leaves certain content unchanged:
+
+- Fenced code blocks (triple backticks)
+- Inline code (single backticks)
+- Existing markdown links
+
+Glossary markers inside these regions are not processed.
+
+## Adding Glossary Terms
+
+To add a new term:
+
+1. Edit `docs/reference/glossary.md`
+2. Add a level-3 header:
+
+```markdown
+### New Term Name
+
+Definition of the term.
+```
+
+The anchor is generated automatically (lowercase, hyphens replace spaces). Reference it with the marker format in your documentation.
+
+## Alias Support
+
+Terms with parenthesized expansions create aliases automatically.
+
+Given this glossary entry:
+
+```markdown
+### ADR (Architecture Decision Record)
+```
+
+The system creates:
+- Main term: `ADR (Architecture Decision Record)`
+- Alias: `Architecture Decision Record`
+- Alias: `ADR`
+
+All three can be used in markers and link to the same glossary entry.
+
+## Auto-Linking
+
+
+
+Auto-linking creates links for glossary terms without requiring explicit markers. This feature is disabled by default.
+
+With auto-linking enabled, input text:
+
+```
+Deploy Gardenlinux on AWS using KVM virtualization.
+```
+
+Becomes:
+
+```markdown
+Deploy [Garden Linux](/reference/glossary#garden-linux) on [AWS](/reference/glossary#aws) using [KVM](/reference/glossary#kvm) virtualization.
+```
+
+Auto-linking rules:
+- Links only the first occurrence of each term
+- Matches longer terms first (`Garden Linux` before `Linux`)
+- Case-insensitive matching
+- Respects word boundaries
+- Preserves code blocks and inline code
+- Does not modify existing links
+
+::: warning
+This feature is disabled by default as it is highly experimental and intended for research work only.
+
+**Contributors must not rely on this feature when contributing documentation.**
+:::
+
+## Makefile Targets
+
+Process glossary links manually:
+
+```bash
+make glossary
+```
+
+Validate glossary structure:
+
+```bash
+make glossary-check
+```
+
+## Warnings
+
+**Term not found:**
+
+```
+[Warning][auto-glossary] Term 'xyz' not found in glossary (referenced in file.md)
+```
+
+The marker remains unchanged. Add the term to the glossary, fix the spelling, or remove the marker.
+
+**Anchor collision:**
+
+```
+[Warning][auto-glossary] Anchor collision detected:
+  'Term 1' and 'Term 2' both generate anchor 'term-1-2'
+```
+
+Rename one of the terms in the glossary.
+
+## Anchor Generation
+
+Terms are converted to VitePress-compatible anchors:
+
+- Convert to lowercase
+- Replace spaces and special characters with hyphens
+- Collapse consecutive hyphens
+- Strip leading and trailing hyphens
+- Normalize Unicode to ASCII
+
+Examples:
+- `AWS` becomes `aws`
+- `Garden Linux` becomes `garden-linux`
+- `ADR (Architecture Decision Record)` becomes `adr-architecture-decision-record`
+
+## Technical Reference
+
+Module location: `src/aggregation/auto_glossary.py`
+
+Main components:
+- `AutoGlossary` class for glossary processing
+- `process_glossary_links()` function for batch processing
+- `GLOSSARY_ENTRY_FORMAT` constant defining the default marker format
+
+Integration points:
+- Runs as part of `src/aggregate.py` after release notes generation
+- Makefile provides `glossary` and `glossary-check` targets
+
+## Testing
+
+Run the test suite:
+
+```bash
+python3 -m pytest tests/unit/test_auto_glossary*.py tests/unit/test_generate_anchor.py -v
+```
+
+Test coverage includes format validation, anchor generation, alias extraction, auto-linking, and integration tests.

docs/contributing/documentation/working-locally.md

@@ -100,15 +100,28 @@ As you work on documentation in source repositories:
 2. Run `make aggregate-local` to update the aggregated docs
 3. The dev server will hot-reload automatically
 
-### Step 6: Build for Production
+### Step 6: Build for Testing 
 
-When ready to deploy:
+```bash
+make build 
+```
+
+This creates a build in `docs/.vitepress/dist/` for testing purposes.
+
+### Step 7: Build for Production
+
+Once ready to deploy:
 
 ```bash
-make build
+make publish
 ```
 
-This creates a production build in `docs/.vitepress/dist/`.
+This runs certain transformation steps such as the automatic glossary and creates a production build in `docs/.vitepress/dist/`.
+
+::: tip Note
+Transformation will leave your local work tree "dirty" (with unstaged changes) as the automatic glossary will
+replace all terms designates with shortcodes (e.g. `{glossary:*}`) with links to the respective glossary entry.
+:::
 
 ## Common Workflows