gardenlinux · ByteOtter · Mar 26, 2026 · Apr 1, 2026 · Apr 14, 2026 · Apr 14, 2026
diff --git a/docs/Makefile b/docs/Makefile
@@ -12,7 +12,11 @@ BUILDDIR      = _build
 help:
 	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
-.PHONY: help Makefile
+.PHONY: help markdown Makefile
+
+# Explicit markdown target: build Markdown output via sphinx-markdown-builder
+markdown:
+	@$(SPHINXBUILD) -M markdown "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).

diff --git a/docs/api.rst b/docs/api.rst
@@ -1,22 +1,34 @@
-API Reference
-=============
+Python Library - API Reference
+==============================
 
-This section provides detailed documentation for all Python modules and classes in python-gardenlinux-lib.
+Detailed documentation for all Python modules and classes in the Garden Linux Python Library
 
-.. automodule:: gardenlinux
-    :members:
+gardenlinux.apt
+~~~~~~~~~~~~~~~
 
 .. automodule:: gardenlinux.apt
     :members:
 
+gardenlinux.features
+~~~~~~~~~~~~~~~~~~~~
+
 .. automodule:: gardenlinux.features
     :members:
 
+gardenlinux.flavors
+~~~~~~~~~~~~~~~~~~~
+
 .. automodule:: gardenlinux.flavors
     :members:
 
+gardenlinux.git
+~~~~~~~~~~~~~~~
+
 .. automodule:: gardenlinux.git
     :members:
 
+gardenlinux.oci
+~~~~~~~~~~~~~~~
+
 .. automodule:: gardenlinux.oci
     :members:
diff --git a/docs/cli.rst b/docs/cli.rst
@@ -1,7 +1,7 @@
-Command-Line Interface
-======================
+Python Library - Command-Line Interface
+=======================================
 
-This page documents all available command-line tools provided by python-gardenlinux-lib.
+Available command-line tools provided by the Garden Linux Python Library
 
 Features Commands
 -----------------

diff --git a/docs/conf.py b/docs/conf.py
@@ -22,8 +22,15 @@
     "sphinx.ext.napoleon",
     "sphinx_click",
     "sphinxcontrib.autoprogram",
+    "sphinx_markdown_builder",
 ]
 
+# Markdown builder configuration (GitHub-Flavored Markdown for VitePress)
+# We can enable this after https://github.com/liran-funaro/sphinx-markdown-builder/pull/53 is merged
+# markdown_flavor = "github"
+markdown_anchor_sections = True
+markdown_anchor_signatures = True
+
 templates_path = ["_templates"]
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 autodoc_mock_imports = ["networkx"]

diff --git a/docs/contributing/.gitkeep b/docs/contributing/.gitkeep
diff --git a/docs/explanation/.gitkeep b/docs/explanation/.gitkeep
diff --git a/docs/how-to/release.md b/docs/how-to/release.md
@@ -0,0 +1,70 @@
+---
+title: Python Library - Release Process
+description: Release a new version of the Garden Linux Python Library
+related_topics:
+  - /reference/supporting_tools/python-gardenlinux-lib
+  - /reference/python-gardenlinux-lib-cli
+  - /how-to/python-gardenlinux-lib-release
+migration_status: "done"
+migration_stakeholder: "@tmangold, @yeoldegrove, @ByteOtter"
+migration_approved: false
+github_org: gardenlinux
+github_repo: python-gardenlinux-lib
+github_source_path: docs/how-to/release.md
+github_target_path: docs/how-to/python-gardenlinux-lib-release.md
+---
+
+# Release Documentation
+
+_python-gardenlinux-lib_ strictly follows the syntax and intention of
+[Semantic Versioning](https://www.semver.org). Each release reflects the
+intention and expected impact therefore.
+
+A new release is done by tagging a commit with a valid version. This will create
+a GitHub pre-release for proof-reading. Once done a new release can be published
+using GitHub CLI or UI.
+
+Newly added docstrings should contain the first version supporting the new API /
+command line.
+
+## Step by Step Guide
+
+1. **Set version files:**
+
+   _python-gardenlinux-lib_ versioning needs to be set in:
+   - `pyproject.toml`
+   - `.github/actions/setup/action.yml`
+
+   Additionally at the moment (removal pending):
+   - `.github/actions/features_parse/action.yml`
+   - `.github/actions/flavors_parse/action.yml`
+
+2. **Create git tag:**
+
+   ```bash
+   git tag <tag>
+   ```
+
+3. **Review and publish:**
+
+   Review the generated pre-release changelog by visiting the GitHub project
+   release page and publish it if applicable.
+
+4. **Consume the library:**
+
+   Projects consuming the _python-gardenlinux-lib_ may use the following git URL
+   for dependency definition:
+
+   ```bash
+   pip install git+https://github.com/gardenlinux/python-gardenlinux-lib.git@1.0.0
+   ```
+
+   Or in `requirements.txt`:
+
+   ```
+   gardenlinux @ git+https://github.com/gardenlinux/python-gardenlinux-lib.git@1.0.0
+   ```
+
+## Related Topics
+
+<RelatedTopics />
diff --git a/docs/index.rst b/docs/index.rst
@@ -1,7 +1,7 @@
-Garden Linux Python Library Documentation
+Garden Linux Python Library
 ==========================================
 
-Welcome to the Garden Linux Python Library documentation. This library provides
+The Garden linux Python Library provides
 Python tools and utilities for working with Garden Linux features, flavors,
 OCI artifacts, S3 buckets, and GitHub releases.
 

diff --git a/docs/overview/index.md b/docs/overview/index.md
@@ -0,0 +1,56 @@
+---
+title: "Python Library"
+description: An overview of the Garden Linux Python Library
+related_topics:
+  - /reference/supporting_tools/python-gardenlinux-lib
+  - /reference/python-gardenlinux-lib-cli
+  - /how-to/python-gardenlinux-lib-release
+migration_status: "done"
+migration_stakeholder: "@tmangold, @yeoldegrove, @ByteOtter"
+migration_approved: false
+github_org: gardenlinux
+github_repo: python-gardenlinux-lib
+github_source_path: docs/overview/index.md
+github_target_path: "docs/reference/supporting_tools/python-gardenlinux-lib.md"
+---
+
+# Garden Linux Python Library Documentation
+
+Welcome to the Garden Linux Python Library documentation. This library provides
+Python tools and utilities for working with Garden Linux features, flavors, OCI
+artifacts, S3 buckets, and GitHub releases.
+
+## Overview
+
+The Garden Linux Python Library is a comprehensive toolkit for managing and
+interacting with Garden Linux components. It includes:
+
+- **Feature Management**: Parse and work with Garden Linux features and generate
+  canonical names
+- **Flavor Processing**: Parse flavors.yaml and generate combinations
+- **OCI Operations**: Push OCI artifacts to registries and manage manifests
+- **S3 Integration**: Upload and download artifacts from S3 buckets
+- **GitHub Integration**: Create and manage GitHub releases with release notes
+
+## Quick Start
+
+### Command-Line Interface
+
+The library provides several command-line tools for common operations. See the
+[Command-Line Interface documentation](/reference/python-gardenlinux-lib-cli.md) for detailed
+information about all available commands.
+
+### Release Management
+
+For information about versioning and release procedures, see the
+[Release documentation](/how-to/python-gardenlinux-lib-release.md).
+
+### API Reference
+
+For detailed Python API documentation, including all modules, classes, and
+functions, see the
+[API Reference on ReadTheDocs](https://gardenlinux.github.io/python-gardenlinux-lib/api.html).
+
+## Related Topics
+
+<RelatedTopics />
diff --git a/docs/reference/.gitkeep b/docs/reference/.gitkeep
diff --git a/docs/tutorials/.gitkeep b/docs/tutorials/.gitkeep
diff --git a/pyproject.toml b/pyproject.toml
@@ -42,6 +42,7 @@ boto3-stubs = { extras = ["s3"], version = "^1.42.30" }
 sphinx-rtd-theme = "^3.0.2"
 sphinx-click = "^4.4.0"
 sphinxcontrib-autoprogram = "^0.1.8"
+sphinx-markdown-builder = "^0.6.10"
 
 [tool.poetry.scripts]
 gl-cname = "gardenlinux.features.cname_main:main"

diff --git a/test-data/gardenlinux b/test-data/gardenlinux