From 8f85857ec245c9e37af47f8ac0f9fa85e8b83318 Mon Sep 17 00:00:00 2001 From: Eike Waldt Date: Thu, 16 Apr 2026 12:59:53 +0200 Subject: [PATCH 1/2] feat: add RelatedTopics component Signed-off-by: Eike Waldt On-behalf-of: SAP --- docs/.vitepress/config.mts | 107 ++++++++++++++++++ .../theme/components/RelatedTopics.vue | 67 +++++++++++ docs/.vitepress/theme/index.ts | 2 + .../documentation/adding-repos.md | 17 +-- .../documentation/aggregation-architecture.md | 17 +-- .../documentation/configuration.md | 19 ++-- .../documentation/documentation_workflow.md | 21 ++-- docs/contributing/documentation/technical.md | 19 ++-- docs/contributing/documentation/testing.md | 19 ++-- .../documentation/working-locally.md | 25 ++-- .../documentation/writing_good_docs.md | 20 ++-- repos-config.json | 8 +- 12 files changed, 257 insertions(+), 84 deletions(-) create mode 100644 docs/.vitepress/theme/components/RelatedTopics.vue diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts index 496e3cf..091c72d 100644 --- a/docs/.vitepress/config.mts +++ b/docs/.vitepress/config.mts @@ -1,5 +1,8 @@ import { defineConfig } from "vitepress"; import { generateDocumentationSidebar } from "./sidebar.js"; +import { readdir, readFile } from "fs/promises"; +import { join } from "path"; +import matter from "gray-matter"; // Get base URL from environment variable (for GitHub Pages deployment) const base = process.env.BASE_URL || "/"; @@ -7,6 +10,68 @@ const base = process.env.BASE_URL || "/"; // Generate sidebar dynamically at build time const documentationSidebar = generateDocumentationSidebar(); +// Build a map of URL -> { title, description, url } for all markdown pages +async function buildPageMap(pagesDir: string): Promise> { + const map: Record = {}; + const skipDirs = ['.vitepress', 'node_modules', 'dist', '_build', '.venv']; + + async function scanDir(dir: string, basePath: string = "") { + const dirName = dir.split('/').pop() || ''; + if (skipDirs.includes(dirName)) { + return; + } + + try { + const entries = await readdir(dir, { withFileTypes: true }); + for (const entry of entries) { + const fullPath = join(dir, entry.name); + if (entry.isDirectory()) { + await scanDir(fullPath, basePath + entry.name + "/"); + } else if (entry.name.endsWith(".md")) { + try { + const content = await readFile(fullPath, "utf-8"); + const { data } = matter(content); + let url = basePath + entry.name.replace(/\.md$/, ".html"); + url = url.replace(/\/index\.html$/, "/"); + if (!url.startsWith("/")) { + url = "/" + url; + } + map[url] = { + title: data.title || entry.name.replace(/\.md$/, ""), + description: data.description || "", + url, + }; + } catch (e) { + // Skip files that can't be read + } + } + } + } catch (e) { + // Skip directories that can't be read + } + } + + await scanDir(pagesDir); + return map; +} + +// Normalize a related_topics path to a URL +function normalizeUrl(ref: string): string { + // Remove .md extension if present + let url = ref.replace(/\.md$/, ""); + // If no extension and no trailing slash, add .html + if (!url.endsWith("/") && !url.includes(".")) { + url = url + ".html"; + } + // Handle /index paths + url = url.replace(/\/index\.html$/, "/"); + // Ensure leading slash + if (!url.startsWith("/")) { + url = "/" + url; + } + return url; +} + // https://vitepress.dev/reference/site-config export default defineConfig({ base, @@ -147,4 +212,46 @@ export default defineConfig({ provider: "local", }, }, + async transformPageData(pageData, { siteConfig }) { + // Build page map - NOT cached globally due to VitePress config execution issues + const pagesDir = siteConfig.root; + const pageMap = await buildPageMap(pagesDir); + + // Resolve related_topics if present + const relatedTopics = pageData.frontmatter?.related_topics; + if (relatedTopics && Array.isArray(relatedTopics)) { + // Get current page URL + let currentPageUrl = "/" + pageData.relativePath.replace(/\.md$/, ".html"); + currentPageUrl = currentPageUrl.replace(/\/index\.html$/, "/"); + + pageData.frontmatter.resolvedRelated = relatedTopics + .map((ref: string) => { + // Normalize the file path to URL + const url = normalizeUrl(ref); + const page = pageMap[url]; + + // ERROR: File not found + if (!page) { + throw new Error( + `RelatedTopics: File not found "${ref}" (resolved to "${url}") in ${pageData.relativePath}` + ); + } + + // ERROR: Title missing in frontmatter + if (!page.title) { + throw new Error( + `RelatedTopics: File "${ref}" has no title in frontmatter (in ${pageData.relativePath})` + ); + } + + // OK: Description is optional + return { + url, + title: page.title, + description: page.description || "", + }; + }) + .filter((page) => page.url !== currentPageUrl); // Remove self-references + } + }, }); diff --git a/docs/.vitepress/theme/components/RelatedTopics.vue b/docs/.vitepress/theme/components/RelatedTopics.vue new file mode 100644 index 0000000..7ef4384 --- /dev/null +++ b/docs/.vitepress/theme/components/RelatedTopics.vue @@ -0,0 +1,67 @@ + + + + + diff --git a/docs/.vitepress/theme/index.ts b/docs/.vitepress/theme/index.ts index d34c3cb..332a0e0 100644 --- a/docs/.vitepress/theme/index.ts +++ b/docs/.vitepress/theme/index.ts @@ -5,6 +5,7 @@ import { useData } from 'vitepress' import { createMermaidRenderer } from 'vitepress-mermaid-renderer' import './style.css' import SectionIndex from './components/SectionIndex.vue' +import RelatedTopics from './components/RelatedTopics.vue' export default { extends: DefaultTheme, @@ -31,5 +32,6 @@ export default { }, enhanceApp({ app }) { app.component('SectionIndex', SectionIndex) + app.component('RelatedTopics', RelatedTopics) }, } satisfies Theme diff --git a/docs/contributing/documentation/adding-repos.md b/docs/contributing/documentation/adding-repos.md index adc3664..e1ea036 100644 --- a/docs/contributing/documentation/adding-repos.md +++ b/docs/contributing/documentation/adding-repos.md @@ -1,6 +1,14 @@ --- title: "Adding Repositories to Documentation Aggregation" description: "Guide for adding new repositories to the documentation aggregation system" +related_topics: + - /contributing/documentation/documentation_workflow.md + - /contributing/documentation/writing_good_docs.md + - /contributing/documentation/aggregation-architecture.md + - /contributing/documentation/adding-repos.md + - /contributing/documentation/working-locally.md + - /contributing/documentation/technical.md + - /contributing/documentation/testing.md --- # Adding Repositories to Documentation Aggregation @@ -256,11 +264,4 @@ Here's a complete configuration: ## Related Topics -- [Documentation Workflow](./documentation_workflow.md) -- [Documentation Quality Markers](./writing_good_docs.md) -- [Documentation Aggregator Architecture](./aggregation-architecture.md) -- [How to Documentation - Adding Repos to Aggregate](./adding-repos.md) -- [How to Documentation - Working With the Aggregator Locally](./working-locally.md) -- [Documentation Aggregator Technical Reference](./technical.md) -- [Documentation Aggregator Local Testing Guide](./testing.md) -- [Working with the Documentation Hub on Your Machine](./working-locally.md) + diff --git a/docs/contributing/documentation/aggregation-architecture.md b/docs/contributing/documentation/aggregation-architecture.md index 50c5264..5bb4c19 100644 --- a/docs/contributing/documentation/aggregation-architecture.md +++ b/docs/contributing/documentation/aggregation-architecture.md @@ -1,6 +1,14 @@ --- title: "Documentation Aggregation Architecture" description: "Deep dive into how the documentation aggregation system works" +related_topics: + - /contributing/documentation/documentation_workflow.md + - /contributing/documentation/writing_good_docs.md + - /contributing/documentation/aggregation-architecture.md + - /contributing/documentation/adding-repos.md + - /contributing/documentation/working-locally.md + - /contributing/documentation/technical.md + - /contributing/documentation/testing.md --- # Documentation Aggregation Architecture @@ -289,11 +297,4 @@ Temp Directory Docs Output ## Related Topics -- [Documentation Workflow](./documentation_workflow.md) -- [Documentation Quality Markers](./writing_good_docs.md) -- [Documentation Aggregator Architecture](./aggregation-architecture.md) -- [How to Documentation - Adding Repos to Aggregate](./adding-repos.md) -- [How to Documentation - Working With the Aggregator Locally](./working-locally.md) -- [Documentation Aggregator Technical Reference](./technical.md) -- [Documentation Aggregator Local Testing Guide](./testing.md) -- [Working with the Documentation Hub on Your Machine](./working-locally.md) + diff --git a/docs/contributing/documentation/configuration.md b/docs/contributing/documentation/configuration.md index b66a60b..27e20af 100644 --- a/docs/contributing/documentation/configuration.md +++ b/docs/contributing/documentation/configuration.md @@ -1,6 +1,14 @@ --- title: "Documentation Aggregation Configuration Reference" description: "Complete reference for repos-config.json and repos-config.local.json configuration options" +related_topics: + - /contributing/documentation/documentation_workflow.md + - /contributing/documentation/writing_good_docs.md + - /contributing/documentation/aggregation-architecture.md + - /contributing/documentation/adding-repos.md + - /contributing/documentation/working-locally.md + - /contributing/documentation/technical.md + - /contributing/documentation/testing.md --- # Documentation Aggregation Configuration Reference @@ -310,13 +318,6 @@ These help create source links in the documentation. - **`migration_status`**: Status for content migration (e.g., `"new"`, `"adapt"`, `"aggregate"`). -## See Also +## Related Topics -- [Documentation Workflow](./documentation_workflow.md) -- [Documentation Quality Markers](./writing_good_docs.md) -- [Documentation Aggregator Architecture](./aggregation-architecture.md) -- [How to Documentation - Adding Repos to Aggregate](./adding-repos.md) -- [How to Documentation - Working With the Aggregator Locally](./working-locally.md) -- [Documentation Aggregator Technical Reference](./technical.md) -- [Documentation Aggregator Local Testing Guide](./testing.md) -- [Working with the Documentation Hub on Your Machine](./working-locally.md) + diff --git a/docs/contributing/documentation/documentation_workflow.md b/docs/contributing/documentation/documentation_workflow.md index 4a6e245..ba767f2 100644 --- a/docs/contributing/documentation/documentation_workflow.md +++ b/docs/contributing/documentation/documentation_workflow.md @@ -2,6 +2,14 @@ title: Documentation Workflow description: How to Contribute Documentation to Garden Linux order: 1 +related_topics: + - /contributing/documentation/documentation_workflow.md + - /contributing/documentation/writing_good_docs.md + - /contributing/documentation/aggregation-architecture.md + - /contributing/documentation/adding-repos.md + - /contributing/documentation/working-locally.md + - /contributing/documentation/technical.md + - /contributing/documentation/testing.md --- # Documenting Garden Linux @@ -138,15 +146,4 @@ The review validates: ## Related Topics -Before you get started, you might want to check out the following docs: - -- [Documentation Quality Markers](./writing_good_docs.md) -- [Documentation Aggregator Architecture](./aggregation-architecture.md) -- [How to Documentation - Adding Repos to Aggregate](./adding-repos.md) -- [How to Documentation - Working With the Aggregator Locally](./working-locally.md) -- [Documentation Aggregator Technical Reference](./technical.md) -- [Documentation Aggregator Local Testing Guide](./testing.md) -- [Working with the Documentation Hub on Your Machine](./working-locally.md) - -> **Source Repository:** -> [gardenlinux/docs-ng](https://github.com/gardenlinux/docs-ng) + diff --git a/docs/contributing/documentation/technical.md b/docs/contributing/documentation/technical.md index ac830a3..143efc5 100644 --- a/docs/contributing/documentation/technical.md +++ b/docs/contributing/documentation/technical.md @@ -1,6 +1,14 @@ --- title: "Documentation Aggregation Technical Reference" description: "Source code documentation for the documentation aggregation system - modules, APIs, and implementation details" +related_topics: + - /contributing/documentation/documentation_workflow.md + - /contributing/documentation/writing_good_docs.md + - /contributing/documentation/aggregation-architecture.md + - /contributing/documentation/adding-repos.md + - /contributing/documentation/working-locally.md + - /contributing/documentation/technical.md + - /contributing/documentation/testing.md --- # Documentation Aggregation Technical Reference @@ -185,13 +193,6 @@ Key architectural decisions are documented in the source repository: - Front-matter-based targeting for flexibility - Separate fetch/transform/structure stages for modularity -## See Also +## Related Topics -- [Documentation Workflow](./documentation_workflow.md) -- [Documentation Quality Markers](./writing_good_docs.md) -- [Documentation Aggregator Architecture](./aggregation-architecture.md) -- [How to Documentation - Adding Repos to Aggregate](./adding-repos.md) -- [How to Documentation - Working With the Aggregator Locally](./working-locally.md) -- [Documentation Aggregator Technical Reference](./technical.md) -- [Documentation Aggregator Local Testing Guide](./testing.md) -- [Working with the Documentation Hub on Your Machine](./working-locally.md) + diff --git a/docs/contributing/documentation/testing.md b/docs/contributing/documentation/testing.md index c04d5ec..faab76f 100644 --- a/docs/contributing/documentation/testing.md +++ b/docs/contributing/documentation/testing.md @@ -1,6 +1,14 @@ --- title: "Documentation Aggregation Testing Guide" description: "Test suite for documentation - unit tests, integration tests, and testing best practices" +related_topics: + - /contributing/documentation/documentation_workflow.md + - /contributing/documentation/writing_good_docs.md + - /contributing/documentation/aggregation-architecture.md + - /contributing/documentation/adding-repos.md + - /contributing/documentation/working-locally.md + - /contributing/documentation/technical.md + - /contributing/documentation/testing.md --- # Documentation Aggregation Testing Guide @@ -227,13 +235,6 @@ Integration tests may fail if: - Permission issues with temp directories - Git not available in PATH -## See Also +## Related Topics -- [Documentation Workflow](./documentation_workflow.md) -- [Documentation Quality Markers](./writing_good_docs.md) -- [Documentation Aggregator Architecture](./aggregation-architecture.md) -- [How to Documentation - Adding Repos to Aggregate](./adding-repos.md) -- [How to Documentation - Working With the Aggregator Locally](./working-locally.md) -- [Documentation Aggregator Technical Reference](./technical.md) -- [Documentation Aggregator Local Testing Guide](./testing.md) -- [Working with the Documentation Hub on Your Machine](./working-locally.md) + diff --git a/docs/contributing/documentation/working-locally.md b/docs/contributing/documentation/working-locally.md index 6045e52..3f86d31 100644 --- a/docs/contributing/documentation/working-locally.md +++ b/docs/contributing/documentation/working-locally.md @@ -1,6 +1,14 @@ --- title: "Contributing to the Garden Linux Documentation" description: "Learn how to contribute to Garden Linux documentation — working with the aggregation system locally" +related_topics: + - /contributing/documentation/documentation_workflow.md + - /contributing/documentation/writing_good_docs.md + - /contributing/documentation/aggregation-architecture.md + - /contributing/documentation/adding-repos.md + - /contributing/documentation/working-locally.md + - /contributing/documentation/technical.md + - /contributing/documentation/testing.md --- # Contributing to the Garden Linux Documentation @@ -128,12 +136,6 @@ docs/ └── contributing/ # Aggregated contributing docs ``` -## Next Steps - -- Learn how to [add new repositories](adding-repos.md) -- Understand the [architecture](./aggregation-architecture.md) -- Review the [configuration reference](./configuration.md) - ## Troubleshooting ### Clean Build @@ -160,13 +162,6 @@ python3 --version # Should be 3.x Check that `repos-config.json` or `repos-config.local.json` is properly configured. See the [configuration reference](./configuration.md) for details. -## See Also +## Related Topics -- [Documentation Workflow](./documentation_workflow.md) -- [Documentation Quality Markers](./writing_good_docs.md) -- [Documentation Aggregator Architecture](./aggregation-architecture.md) -- [How to Documentation - Adding Repos to Aggregate](./adding-repos.md) -- [How to Documentation - Working With the Aggregator Locally](./working-locally.md) -- [Documentation Aggregator Technical Reference](./technical.md) -- [Documentation Aggregator Local Testing Guide](./testing.md) -- [Working with the Documentation Hub on Your Machine](./working-locally.md) + diff --git a/docs/contributing/documentation/writing_good_docs.md b/docs/contributing/documentation/writing_good_docs.md index a5cc03a..1ae6448 100644 --- a/docs/contributing/documentation/writing_good_docs.md +++ b/docs/contributing/documentation/writing_good_docs.md @@ -2,6 +2,14 @@ title: Documentation Quality Markers description: Writing Good Documentation order: 2 +related_topics: + - /contributing/documentation/documentation_workflow.md + - /contributing/documentation/writing_good_docs.md + - /contributing/documentation/aggregation-architecture.md + - /contributing/documentation/adding-repos.md + - /contributing/documentation/working-locally.md + - /contributing/documentation/technical.md + - /contributing/documentation/testing.md --- # Documentation Quality Markers @@ -184,14 +192,6 @@ Use this checklist when reviewing or submitting documentation: - ✅ Known issues section included (if applicable) - ✅ External dependencies documented (if applicable) -## Next Steps +## Related Topics -Before you get started, you might want to check out the following docs: - -- [Documentation Workflow](./documentation_workflow.md) -- [Documentation Aggregator Architecture](./aggregation-architecture.md) -- [How to Documentation - Adding Repos to Aggregate](./adding-repos.md) -- [How to Documentation - Working With the Aggregator Locally](./working-locally.md) -- [Documentation Aggregator Technical Reference](./technical.md) -- [Documentation Aggregator Local Testing Guide](./testing.md) -- [Working with the Documentation Hub on Your Machine](./working-locally.md) + diff --git a/repos-config.json b/repos-config.json index d1e62f2..a59ca19 100644 --- a/repos-config.json +++ b/repos-config.json @@ -6,7 +6,7 @@ "docs_path": "docs", "target_path": "projects/gardenlinux", "ref": "docs-ng", - "commit": "7615fe00399f8bb8a6d5b7c36d6a8023747420fa", + "commit": "900bdf88b9e29d97e3a100338fe43be46d333610", "root_files": [ "CONTRIBUTING.md", "SECURITY.md", @@ -33,7 +33,7 @@ "docs_path": "docs", "target_path": "projects/builder", "ref": "docs-ng", - "commit": "ff29b1c4a5abddf855e6b4b7e14bf985a790779e", + "commit": "7a7c3430ba21794d7f30876df8850e1424768149", "media_directories": [ ".media", "assets", @@ -46,7 +46,7 @@ "docs_path": "docs", "target_path": "projects/python-gardenlinux-lib", "ref": "docs-ng", - "commit": "be7fd063d1b440f490d9a1e3054179b35a7abc23", + "commit": "73a16adcc674e43ad9b811c399fa5af1b698d62f", "structure": "sphinx", "media_directories": [ ".media", @@ -73,7 +73,7 @@ "docs_path": "docs", "target_path": "projects/glrd", "ref": "docs-ng", - "commit": "b855783938aad5cf3238fef9b5dc12190e0b7207", + "commit": "b5262e0bf409065ee1b9d62f4d0270695d9081a2", "media_directories": [ ".media", "assets", From 7607664929fe9a05cc5587472272c904cab5454a Mon Sep 17 00:00:00 2001 From: Eike Waldt Date: Thu, 16 Apr 2026 15:58:21 +0200 Subject: [PATCH 2/2] docs: document vitepress features Signed-off-by: Eike Waldt On-behalf-of: SAP --- .../documentation/adding-repos.md | 1 + .../documentation/aggregation-architecture.md | 9 +- .../documentation/configuration.md | 21 +- .../documentation/documentation_workflow.md | 1 + docs/contributing/documentation/technical.md | 1 + docs/contributing/documentation/testing.md | 1 + .../documentation/vitepress-features.md | 321 ++++++++++++++++++ .../documentation/working-locally.md | 1 + .../documentation/writing_good_docs.md | 15 + 9 files changed, 354 insertions(+), 17 deletions(-) create mode 100644 docs/contributing/documentation/vitepress-features.md diff --git a/docs/contributing/documentation/adding-repos.md b/docs/contributing/documentation/adding-repos.md index e1ea036..1c17cb4 100644 --- a/docs/contributing/documentation/adding-repos.md +++ b/docs/contributing/documentation/adding-repos.md @@ -9,6 +9,7 @@ related_topics: - /contributing/documentation/working-locally.md - /contributing/documentation/technical.md - /contributing/documentation/testing.md + - /contributing/documentation/vitepress-features.md --- # Adding Repositories to Documentation Aggregation diff --git a/docs/contributing/documentation/aggregation-architecture.md b/docs/contributing/documentation/aggregation-architecture.md index 5bb4c19..54ae542 100644 --- a/docs/contributing/documentation/aggregation-architecture.md +++ b/docs/contributing/documentation/aggregation-architecture.md @@ -9,6 +9,7 @@ related_topics: - /contributing/documentation/working-locally.md - /contributing/documentation/technical.md - /contributing/documentation/testing.md + - /contributing/documentation/vitepress-features.md --- # Documentation Aggregation Architecture @@ -89,13 +90,11 @@ source repositories into a unified VitePress documentation site. 1. **Link Rewriting:** Transform relative links to work across repository boundaries - - Intra-repo links: Maintained relative to project mirror - Cross-repo links: Rewritten to absolute paths - External links: Preserved as-is 2. **Front-matter Handling:** Ensure all documents have proper front-matter - - Add missing front-matter blocks - Quote YAML values safely - Preserve existing metadata @@ -176,9 +175,9 @@ For reproducible builds, commits can be locked: ```json { - "name": "repo", - "ref": "main", - "commit": "abc123..." + "name": "repo", + "ref": "main", + "commit": "abc123..." } ``` diff --git a/docs/contributing/documentation/configuration.md b/docs/contributing/documentation/configuration.md index 27e20af..16196d2 100644 --- a/docs/contributing/documentation/configuration.md +++ b/docs/contributing/documentation/configuration.md @@ -9,6 +9,7 @@ related_topics: - /contributing/documentation/working-locally.md - /contributing/documentation/technical.md - /contributing/documentation/testing.md + - /contributing/documentation/vitepress-features.md --- # Documentation Aggregation Configuration Reference @@ -296,27 +297,23 @@ github_target_path: "docs/tutorials/my-tutorial.md" ## Front-Matter Fields -When using `github_target_path`, you can include additional metadata: +### Aggregation-Specific Fields + +When using `github_target_path` for aggregated content, you can include additional metadata: - **`github_org`**: Organization name (e.g., `"gardenlinux"`) - **`github_repo`**: Repository name (e.g., `"docs-ng"`) - **`github_source_path`**: Original file path in source repo (e.g., `"docs/tutorial.md"`) +- **`github_branch`**: Branch name for edit links (default: `"main"`) -These help create source links in the documentation. +These fields enable "Edit this page on GitHub" links for aggregated content. ### Page Display Fields -- **`description`**: A short summary of the page. Used as the `` - description by VitePress and shown in section index listings when - `overviewDescriptions` is enabled on the parent page. -- **`overviewDescriptions`**: Boolean controlling whether the `` - component displays child page descriptions. Defaults to `true`. Set to `false` - on an index page to hide descriptions for its listing. -- **`order`**: Numeric value for controlling sort order in the sidebar and - section listings. Lower values appear first. -- **`migration_status`**: Status for content migration (e.g., `"new"`, - `"adapt"`, `"aggregate"`). +For general page display and component configuration fields (such as `title`, +`description`, `order`, `overviewDescriptions`, and `related_topics`), see +[VitePress Features](vitepress-features.md). ## Related Topics diff --git a/docs/contributing/documentation/documentation_workflow.md b/docs/contributing/documentation/documentation_workflow.md index ba767f2..b46f37e 100644 --- a/docs/contributing/documentation/documentation_workflow.md +++ b/docs/contributing/documentation/documentation_workflow.md @@ -10,6 +10,7 @@ related_topics: - /contributing/documentation/working-locally.md - /contributing/documentation/technical.md - /contributing/documentation/testing.md + - /contributing/documentation/vitepress-features.md --- # Documenting Garden Linux diff --git a/docs/contributing/documentation/technical.md b/docs/contributing/documentation/technical.md index 143efc5..91a933e 100644 --- a/docs/contributing/documentation/technical.md +++ b/docs/contributing/documentation/technical.md @@ -9,6 +9,7 @@ related_topics: - /contributing/documentation/working-locally.md - /contributing/documentation/technical.md - /contributing/documentation/testing.md + - /contributing/documentation/vitepress-features.md --- # Documentation Aggregation Technical Reference diff --git a/docs/contributing/documentation/testing.md b/docs/contributing/documentation/testing.md index faab76f..4cb5cd3 100644 --- a/docs/contributing/documentation/testing.md +++ b/docs/contributing/documentation/testing.md @@ -9,6 +9,7 @@ related_topics: - /contributing/documentation/working-locally.md - /contributing/documentation/technical.md - /contributing/documentation/testing.md + - /contributing/documentation/vitepress-features.md --- # Documentation Aggregation Testing Guide diff --git a/docs/contributing/documentation/vitepress-features.md b/docs/contributing/documentation/vitepress-features.md new file mode 100644 index 0000000..279f3e1 --- /dev/null +++ b/docs/contributing/documentation/vitepress-features.md @@ -0,0 +1,321 @@ +--- +title: "VitePress Features and Customizations" +description: "Guide to custom components, Mermaid diagrams, and VitePress features for documentation writers" +order: 5 +related_topics: + - /contributing/documentation/documentation_workflow.md + - /contributing/documentation/writing_good_docs.md + - /contributing/documentation/aggregation-architecture.md + - /contributing/documentation/adding-repos.md + - /contributing/documentation/working-locally.md + - /contributing/documentation/technical.md + - /contributing/documentation/testing.md + - /contributing/documentation/vitepress-features.md +--- + +# VitePress Features and Customizations + +This guide documents the VitePress features and customizations available for writing Garden Linux documentation. It covers custom components, diagram support, and front-matter extensions. + +## Custom Components + +Garden Linux documentation includes two custom Vue components that are registered globally in the VitePress theme. + +### SectionIndex Component + +The `` component automatically generates a table of contents for the current documentation section. It reads the sidebar configuration, finds the section matching the current page, and displays its child pages as a grid. + +**When to use:** + +- On section index pages (e.g., `tutorials/index.md`, `how-to/index.md`) +- Any page that should display links to its child pages + +**How it works:** + +1. Reads the sidebar configuration from the VitePress theme +2. Finds the sidebar group matching the current directory +3. Extracts child items and their descriptions from front-matter +4. Displays them in a responsive grid layout + +**Configuration:** + +Use the `overviewDescriptions` front-matter field to control whether child page descriptions are shown: + +```yaml +--- +title: How-To Guides +overviewDescriptions: true # Show descriptions (default) +--- +``` + +Set to `false` to hide descriptions: + +```yaml +--- +title: Quick Reference +overviewDescriptions: false # Hide descriptions +--- +``` + +**Example usage:** + +```markdown +--- +title: How-To Guides +description: Step-by-step guides for common Garden Linux tasks +--- + +# How-To Guides + +How-to guides are **task-oriented** directions that guide you through solving a specific problem or achieving a particular goal. They assume you have some familiarity with Garden Linux and focus on practical solutions. + + +``` + +### RelatedTopics Component + +The `` component displays a curated list of related documentation pages at the bottom of content. It validates that all linked pages exist during the build process. + +**When to use:** + +- At the end of content pages +- To guide readers to next steps or related documentation + +**How it works:** + +1. Reads the `related_topics` array from the page's front-matter +2. Resolves file paths to URLs +3. Extracts titles and descriptions from linked pages +4. Displays them as a formatted list with links + +**Configuration:** + +Define related topics in the page's front-matter using absolute paths: + +```yaml +--- +title: Building Images +related_topics: + - /how-to/choosing-flavors.md + - /how-to/getting-images.md + - /reference/features.md +--- +``` + +**Example usage:** + +```markdown +--- +title: Building Images +description: How to build Garden Linux images +related_topics: + - /how-to/choosing-flavors.md + - /how-to/getting-images.md +--- + +# Building Images + + + + +``` + +## Mermaid Diagrams + +Garden Linux documentation supports [Mermaid](https://mermaid.js.org/) diagrams through the `vitepress-mermaid-renderer` plugin. This enables flowcharts, Gantt charts, sequence diagrams, and more. + +**When to use:** + +- Visualizing timelines and release schedules +- Showing process flows and architectures +- Displaying complex relationships + +**How it works:** +The plugin automatically renders code blocks marked with `mermaid` as diagrams. It includes custom theming that matches the Garden Linux brand colors (green scheme) and supports dark mode. + +**Syntax:** + +````markdown +```mermaid +graph TD + A[Start] --> B{Decision} + B -->|Yes| C[Continue] + B -->|No| D[Stop] +``` +```` + +**Gantt chart example:** + +````markdown +```mermaid +gantt + title Release Schedule + dateFormat YYYY-MM-DD + section Development + Feature A :2024-01-01, 30d + Feature B :2024-01-15, 30d + section Testing + Integration Tests :after Feature A, 14d +``` +```` + +**Custom theming:** +The documentation uses a green color scheme matching Garden Linux branding: + +```mermaid +%%{init: {'theme':'base', 'themeVariables': { + 'primaryColor':'#30a46c', + 'primaryTextColor':'#fff', + 'primaryBorderColor':'#18794e', + 'lineColor':'#30a46c', + 'textColor':'#009f76' +}}}%% +gantt + title Theme Preview + dateFormat YYYY-MM-DD + section Example + Task 1 :2024-01-01, 10d +``` + +**Real-world example:** +See the [Maintained Releases](../../reference/releases/maintained-releases.md) page for a complete Gantt chart showing release maintenance phases. + +## Container Syntax (Callouts) + +VitePress supports special container blocks for callouts and highlighted content. Garden Linux documentation uses these throughout. + +**When to use:** + +- `:::tip` - Recommendations and helpful hints +- `:::warning` - Important caveats or potential issues +- `:::danger` - Critical warnings about data loss, security, etc. +- `:::info` - Informational notes +- `:::details` - Collapsible content for optional information + +**Examples:** + +```markdown +:::tip +Use rootless Podman for building images. It provides better security +and doesn't require special privileges. +::: + +:::warning +Provide at least 8 GiB of memory to the container runtime. Insufficient +memory may cause builds to fail silently. +::: + +:::danger +Do not use the production keyring for testing. Always use test keys +to avoid accidentally publishing unverified packages. +::: + +:::details Click to expand for technical details +The build process uses the following steps: + +1. Initialize container with base image +2. Apply feature layers +3. Apply customization +4. Create final image + +Each step creates an intermediate container. +::: + +:::info +This feature requires Garden Linux version 2150.0.0 or later. +::: +``` + +**Best practices:** + +- Use `:::tip` for recommendations and best practices +- Use `:::warning` for important caveats +- Use `:::danger` sparingly and only for critical warnings +- Use `:::details` for optional advanced content that most readers don't need + +## Front-matter Fields + +Garden Linux documentation uses several front-matter fields for configuration. + +### Component Configuration + +**`overviewDescriptions`** (boolean, default: true) + +Controls whether the `` component displays descriptions for child pages. Set to `false` on an index page to hide descriptions in its section listing. + +**`related_topics`** (array of strings) + +Defines related pages for the `` component. Each entry is an absolute file path (starting with `/`) to another markdown file. All paths must exist or the build will fail with an error. + +### Display Configuration + +**`title`** (string, required) + +The page title. Used in navigation, search results, and as the default heading. + +**`description`** (string) + +A short summary of the page content. Used as the meta description for SEO and displayed by `` for child page listings. + +**`order`** (number, default: 999) + +Controls sort order in the sidebar and section listings. Lower numbers appear first. Use this to create logical groupings (e.g., `0` for intro, `10` for basics, `100` for advanced). + +### Aggregated Content Fields + +For content aggregated from external repositories, these fields enable proper placement and "Edit on GitHub" links. For complete details on aggregation configuration, see [Documentation Aggregation Configuration Reference](configuration.md). + +**`github_target_path`** (string) + +Target location in the docs directory for aggregated content. + +**`github_org`** (string) + +GitHub organization name. + +**`github_repo`** (string) + +Repository name. + +**`github_source_path`** (string) + +Original file path in the source repository. + +**`github_branch`** (string, default: "main") + +Branch name for edit links. + +## Best Practices + +### Component Usage + +- Always use `` on section index pages (tutorials/, how-to/, explanation/, reference/) +- Place `` at the end of content pages, before any closing sections +- Keep `related_topics` lists focused (3-5 items is ideal) +- Write clear, concise `description` fields for better section overviews + +### Mermaid Diagrams + +- Use for timelines, processes, and complex relationships +- Keep diagrams simple and focused +- Test in both light and dark mode (use the preview) +- Don't overuse - diagrams should add clarity, not replace text + +### Containers/Callouts + +- Use `:::tip` for recommendations and best practices +- Use `:::warning` for important caveats that readers should know +- Use `:::danger` only for critical warnings about data loss, security, or system damage +- Use `:::info` sparingly for contextual information +- Use `:::details` for optional advanced content that most readers can skip + +### Front-matter + +- Always include `title` and `description` on every page +- Use `order` to control logical flow in sections +- Validate that `related_topics` links exist before committing +- Keep descriptions under 160 characters for optimal SEO + +## Related Topics + + diff --git a/docs/contributing/documentation/working-locally.md b/docs/contributing/documentation/working-locally.md index 3f86d31..356f2ce 100644 --- a/docs/contributing/documentation/working-locally.md +++ b/docs/contributing/documentation/working-locally.md @@ -9,6 +9,7 @@ related_topics: - /contributing/documentation/working-locally.md - /contributing/documentation/technical.md - /contributing/documentation/testing.md + - /contributing/documentation/vitepress-features.md --- # Contributing to the Garden Linux Documentation diff --git a/docs/contributing/documentation/writing_good_docs.md b/docs/contributing/documentation/writing_good_docs.md index 1ae6448..6016717 100644 --- a/docs/contributing/documentation/writing_good_docs.md +++ b/docs/contributing/documentation/writing_good_docs.md @@ -10,6 +10,7 @@ related_topics: - /contributing/documentation/working-locally.md - /contributing/documentation/technical.md - /contributing/documentation/testing.md + - /contributing/documentation/vitepress-features.md --- # Documentation Quality Markers @@ -142,6 +143,20 @@ Documentation should be structured to minimize maintenance burden: owns maintenance if that role exists - Use includes or references for content that appears in multiple places +### Using Custom Components + +Garden Linux documentation includes custom VitePress components that should +be used appropriately: + +- **``**: Always use on section index pages (tutorials/index.md, + how-to/index.md, etc.) to display child pages automatically +- **``**: Add at the end of content pages to link to related + documentation +- **Front-matter**: Always include `title` and `description` fields; use + `order` to control sort order in listings +- See [VitePress Features](vitepress-features.md) for complete documentation + of available components and front-matter fields + ## Conditional Markers ### Version Compatibility