kapitan 0.36.2.dev3__tar.gz → 0.36.2.dev5__tar.gz

{kapitan-0.36.2.dev3 → kapitan-0.36.2.dev5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kapitan
-Version: 0.36.2.dev3
+Version: 0.36.2.dev5
 Summary: Generic templated configuration management for Kubernetes, Terraform and other things
 Project-URL: Homepage, https://kapitan.dev
 Project-URL: Repository, https://github.com/kapicorp/kapitan

{kapitan-0.36.2.dev3 → kapitan-0.36.2.dev5}/docs/pages/argocd.md

@@ -1,3 +1,8 @@
+---
+title: "Kapitan ArgoCD Integration: GitOps Config Plugin"
+description: "Integrate Kapitan with ArgoCD as a Config Management Plugin to render Kubernetes manifests for GitOps delivery."
+---
+
 # :kapitan-logo: ArgoCD Integration
 
 Kapitan can be used as an [ArgoCD Config Management Plugin (CMP)](https://argo-cd.readthedocs.io/en/stable/operator-manual/config-management-plugins/).

kapitan-0.36.2.dev5/docs/pages/blog/index.md

@@ -0,0 +1,6 @@
+---
+title: "Kapitan Blog: Release Notes, Tutorials & Updates"
+description: "Explore the Kapitan blog for release notes, tutorials, and updates on configuration management for Kubernetes, Terraform, and more."
+---
+
+# Blog

{kapitan-0.36.2.dev3 → kapitan-0.36.2.dev5}/docs/pages/blog/posts/2022-12-04.md

@@ -3,6 +3,8 @@ author: Alessandro De Maria
 author_gh_user: ademariag
 read_time: 10m
 date: 2022-12-04
+title: "Celebrating 5 Years of Kapitan Configuration Management"
+description: "Reflecting on five years of Kapitan and why it remains a unique tool for managing configuration data across Kubernetes, Terraform, and Helm."
 ---
 
 # :kapitan-logo: **5 Years** of **Kapitan**

{kapitan-0.36.2.dev3 → kapitan-0.36.2.dev5}/docs/pages/blog/posts/2023-01-16.md

@@ -3,6 +3,8 @@ author: Alessandro De Maria
 author_gh_user: ademariag
 read_time: 10m
 date: 2022-12-04
+title: "Kapitan v0.31.0 Release: New Features & Improvements"
+description: "Read the Kapitan v0.31.0 release notes covering new features, improvements, and community contributions from the past year."
 ---
 
 # :kapitan-logo: New **Kapitan** release  v0.31.0

{kapitan-0.36.2.dev3 → kapitan-0.36.2.dev5}/docs/pages/blog/posts/2023-06-01.md

@@ -3,6 +3,8 @@ author: Alessandro De Maria
 author_gh_user: ademariag
 read_time: 10m
 date: 2022-12-04
+title: "Kapitan v0.32.0 Release: New Features & Improvements"
+description: "Read the Kapitan v0.32.0 release notes covering six months of improvements and community contributions to the project."
 ---
 # :kapitan-logo: New **Kapitan** release  v0.32.0
 

{kapitan-0.36.2.dev3 → kapitan-0.36.2.dev5}/docs/pages/blog/posts/2023-08-27.md

@@ -3,6 +3,8 @@ author: Alessandro De Maria
 author_gh_user: ademariag
 read_time: 10m
 date: 2023-08-27
+title: "Deploying Keda with Kapitan Helm Chart Generators"
+description: "Learn how to deploy Keda with Kapitan using the charts generator to download, compile, and mutate Helm charts for Kubernetes."
 ---
 
 # :kapitan-logo: **Deploying Keda with Kapitan**

{kapitan-0.36.2.dev3 → kapitan-0.36.2.dev5}/docs/pages/blog/posts/2024-02-12.md

@@ -3,6 +3,8 @@ author: Luis Buriola
 author_gh_user: gburiola
 read_time: 2m
 date: 2024-02-12
+title: "Kapitan v0.33.1 Release: New Features & Improvements"
+description: "Read the Kapitan v0.33.1 release notes covering eight months of improvements and community contributions to the project."
 ---
 
 # :kapitan-logo: New **Kapitan** release  v0.33.1

{kapitan-0.36.2.dev3 → kapitan-0.36.2.dev5}/docs/pages/commands/kapitan_compile.md

@@ -1,3 +1,8 @@
+---
+title: "Kapitan compile: Render Targets to Output Files"
+description: "Learn how the kapitan compile command merges inventory and inputs to generate your output files."
+---
+
 # :kapitan-logo: **CLI Reference** | `kapitan compile`
 
 ## `kapitan compile`

{kapitan-0.36.2.dev3 → kapitan-0.36.2.dev5}/docs/pages/commands/kapitan_dotfile.md

@@ -1,3 +1,8 @@
+---
+title: "Kapitan .kapitan Dotfile: Override CLI Defaults"
+description: "Configure the .kapitan dotfile to pin versions and set persistent command flags across all Kapitan runs."
+---
+
 # :kapitan-logo: **CLI Reference** | `.kapitan` config file
 
 ## `.kapitan`

{kapitan-0.36.2.dev3 → kapitan-0.36.2.dev5}/docs/pages/commands/kapitan_inventory.md

@@ -1,3 +1,8 @@
+---
+title: "Kapitan inventory: Render Target Inventory Values"
+description: "Run the kapitan inventory command to render the merged inventory values for a specific target."
+---
+
 # :kapitan-logo: **CLI Reference** | `kapitan inventory`
 
 ## `kapitan inventory`

{kapitan-0.36.2.dev3 → kapitan-0.36.2.dev5}/docs/pages/commands/kapitan_lint.md

@@ -1,3 +1,8 @@
+---
+title: "Kapitan lint: Check Your Inventory and Refs"
+description: "Run the kapitan lint command to check your inventory and refs for YAML issues and orphan classes."
+---
+
 # :kapitan-logo: **CLI Reference** | `kapitan lint`
 
 ## `kapitan lint`

{kapitan-0.36.2.dev3 → kapitan-0.36.2.dev5}/docs/pages/commands/kapitan_searchvar.md

@@ -1,3 +1,8 @@
+---
+title: "Kapitan searchvar: Find Where Variables Are Set"
+description: "Search your inventory with the kapitan searchvar command to find every file where a variable is declared."
+---
+
 # :kapitan-logo: **CLI Reference** | `kapitan searchvar`
 
 ## `kapitan searchvar`

{kapitan-0.36.2.dev3 → kapitan-0.36.2.dev5}/docs/pages/commands/kapitan_validate.md

@@ -1,3 +1,8 @@
+---
+title: "Kapitan validate: Check Compiled Output Schemas"
+description: "Validate compiled output against schemas with the kapitan validate command, including Kubernetes kinds."
+---
+
 # :kapitan-logo: **CLI Reference** | `kapitan validate`
 
 ## `kapitan validate`

{kapitan-0.36.2.dev3 → kapitan-0.36.2.dev5}/docs/pages/contribute/code.md

@@ -2,7 +2,7 @@
 comments: true
 tags:
   - community
-title: "Contribute to Kapitan"
+title: "Contribute Code to Kapitan: Issues, PRs & Setup"
 description: "Guidelines for contributing code to Kapitan, from opening issues and pull requests to development setup and testing."
 ---
 # :kapitan-logo: **Kapitan** code

{kapitan-0.36.2.dev3 → kapitan-0.36.2.dev5}/docs/pages/contribute/documentation.md

@@ -1,4 +1,6 @@
 ---
+title: "Contribute Documentation to the Kapitan Project"
+description: "Learn how to contribute documentation to Kapitan, from local setup with MkDocs to submitting and deploying changes."
 comments: true
 tags:
   - community

{kapitan-0.36.2.dev3 → kapitan-0.36.2.dev5}/docs/pages/contribute/sponsor.md

@@ -1,4 +1,6 @@
 ---
+title: "Sponsor the Kapitan Project and Support Its Future"
+description: "Support Kapitan through GitHub Sponsors or other contributions and get recognised as a project sponsor on our website."
 comments: true
 tags:
   - community

{kapitan-0.36.2.dev3 → kapitan-0.36.2.dev5}/docs/pages/contribute/talk.md

@@ -1,3 +1,8 @@
+---
+title: "Talk About Kapitan and Spread the Word"
+description: "Help promote Kapitan by starring it, sharing the website, writing blog posts, and spreading the word across your network."
+---
+
 # :kapitan-logo: **Talk about Kapitan**
 
 Our project needs your support to get noticed! Please let everyone know that you are using **Kapitan**

kapitan-0.36.2.dev5/docs/pages/environment_variables.md

@@ -0,0 +1,51 @@
+---
+title: Kapitan environment variables (KAPITAN_*) reference
+description: "Reference for every KAPITAN_* environment variable Kapitan reads: what it does, its default, where to set it, and which run phase it applies to."
+---
+
+# :kapitan-logo: Environment variables
+
+**Kapitan** reads a small set of `KAPITAN_*` environment variables to tune behaviour
+that has no dedicated CLI flag or inventory key. They are all **optional** and fall
+back to the defaults listed below.
+
+A few rules apply to every variable on this page:
+
+- They are read from the **process environment only** — there is no inventory
+  equivalent for any `KAPITAN_*` variable.
+- Each is read during a specific **phase** of a run (fetch, compile, or reveal);
+  setting it has no effect outside that phase.
+- Export them before invoking `kapitan` (e.g. `KAPITAN_HELM_TIMEOUT=60 kapitan compile`).
+
+## Dependency fetching
+
+Read while fetching external dependencies — `kapitan compile --fetch` or
+`--force-fetch`. See [External dependencies](external_dependencies.md).
+
+| Variable | Default | When it applies | Description |
+| --- | --- | --- | --- |
+| `KAPITAN_FETCH_RETRIES` | `3` | git & http[s] fetch | Maximum attempts per fetch, including the first. Set to `1` to disable retries. |
+| `KAPITAN_FETCH_WAIT_MIN` | `0.5` | git & http[s] fetch | Minimum backoff between attempts, in seconds. |
+| `KAPITAN_FETCH_WAIT_MAX` | `10` | git & http[s] fetch | Maximum backoff between attempts, in seconds. |
+| `KAPITAN_FETCH_TIMEOUT` | `30` | http[s] fetch | Per-request HTTP timeout, in seconds. |
+
+## Helm input
+
+Read when compiling [Helm inputs](input_types/helm.md).
+
+| Variable | Default | When it applies | Description |
+| --- | --- | --- | --- |
+| `KAPITAN_HELM_PATH` | `helm` | compile (helm input) | Path to the `helm` binary used by the Helm input type. |
+| `KAPITAN_HELM_TIMEOUT` | `30` | compile (helm input) | Timeout for helm operations, in seconds. |
+
+## Environment references
+
+The `env` reference backend resolves `?{env:...}` references from the environment at
+**reveal** time. See [References](../references.md).
+
+| Variable | Default | When it applies | Description |
+| --- | --- | --- | --- |
+| `KAPITAN_VAR_<NAME>` | reference default | reveal | Value substituted for the `env` reference `<NAME>`. The lower-case key is tried first, then the upper-cased key; if neither is set, the reference's stored default value is used. |
+
+For example, the reference `?{env:mysql_port}` is revealed from `KAPITAN_VAR_mysql_port`
+(or `KAPITAN_VAR_MYSQL_PORT`).

{kapitan-0.36.2.dev3 → kapitan-0.36.2.dev5}/docs/pages/external_dependencies.md

@@ -1,3 +1,8 @@
+---
+title: "Kapitan External Dependencies: Git, HTTP, Helm, OCI"
+description: "Learn how to fetch external dependencies in Kapitan from Git, HTTP, Helm, and OCI remote sources."
+---
+
 # :kapitan-logo: External dependencies
 
 **Kapitan** has the functionality to fetch external dependencies from remote locations.

{kapitan-0.36.2.dev3 → kapitan-0.36.2.dev5}/docs/pages/fluxcd.md

@@ -1,3 +1,8 @@
+---
+title: "Kapitan FluxCD Integration: GitOps with OCI Artifacts"
+description: "Integrate Kapitan with FluxCD to publish compiled manifests as OCI artifacts for GitOps delivery."
+---
+
 # :kapitan-logo: FluxCD Integration
 
 Kapitan works with [FluxCD](https://fluxcd.io) by compiling manifests in CI and publishing them as [OCI artifacts](https://fluxcd.io/flux/cheatsheets/oci-artifacts/). FluxCD pulls the artifact and applies it to the cluster.

{kapitan-0.36.2.dev3 → kapitan-0.36.2.dev5}/docs/pages/glossary.md

@@ -1,5 +1,5 @@
 ---
-title: "Kapitan Glossary"
+title: "Kapitan Glossary: Key Terms & Concepts Explained"
 description: "Definitions of key terms and concepts used throughout Kapitan documentation and the configuration management workflow."
 ---
 

{kapitan-0.36.2.dev3 → kapitan-0.36.2.dev5}/docs/pages/input_types/copy.md

@@ -1,3 +1,8 @@
+---
+title: "Kapitan Copy Input Type: Copy Files Without Rendering"
+description: "Learn how to use the Kapitan copy input type to copy files and directories to the output without any rendering or processing."
+---
+
 # :kapitan-logo: Copy
 
 This input type simply copies the input templates to the output directory without any rendering/processing.

{kapitan-0.36.2.dev3 → kapitan-0.36.2.dev5}/docs/pages/input_types/cuelang.md

@@ -1,3 +1,8 @@
+---
+title: "Kapitan CUE Input Type: Generate Config with CUE"
+description: "Learn how to use the Kapitan CUE input type to manage, validate, and generate manifests with the CUE language."
+---
+
 # CUE Lang Input Type
 
 The CUE Lang input type allows you to use [CUE](https://cuelang.org/) to manage, validate, and generate manifests within Kapitan.

{kapitan-0.36.2.dev3 → kapitan-0.36.2.dev5}/docs/pages/input_types/external.md

@@ -1,3 +1,8 @@
+---
+title: "Kapitan External Input Type: Run Scripts and Binaries"
+description: "Learn how to use the Kapitan external input type to execute scripts or binaries that generate or manipulate compiled files."
+---
+
 # :kapitan-logo: External
 
 This input type executes an external script or binary. This can be used to manipulate already compiled files or

{kapitan-0.36.2.dev3 → kapitan-0.36.2.dev5}/docs/pages/input_types/introduction.md

@@ -1,6 +1,6 @@
 ---
-title: "Kapitan Input Types"
-description: "Explore Kapitan input types including Jsonnet, Jinja2, Kadet, Helm, Kustomize, CUE, copy, remove, and external. Choose the right templating engine for your infrastructure."
+title: "Kapitan Input Types: Templating Engines Overview"
+description: "Explore Kapitan input types — Jsonnet, Jinja2, Kadet, Helm, Kustomize, CUE, and more — and pick the right templating engine for your infrastructure."
 ---
 
 # :kapitan-logo: **Kapitan Input Types**

{kapitan-0.36.2.dev3 → kapitan-0.36.2.dev5}/docs/pages/input_types/jinja.md

@@ -1,5 +1,5 @@
 ---
-title: "Kapitan Jinja2 Input Type"
+title: "Kapitan Jinja2 Input Type: Template Config Files"
 description: "Learn how to use Jinja2 templates in Kapitan to generate scripts, documentation, and configuration files with access to the full Kapitan inventory."
 ---
 

{kapitan-0.36.2.dev3 → kapitan-0.36.2.dev5}/docs/pages/input_types/jsonnet.md

@@ -1,6 +1,6 @@
 ---
-title: "Kapitan with Jsonnet"
-description: "Use Jsonnet with Kapitan to generate Kubernetes manifests and infrastructure configuration. Access inventory data, validate with JSON Schema, and output YAML or JSON."
+title: "Kapitan Jsonnet Input Type: Generate Manifests"
+description: "Use Jsonnet with Kapitan to generate Kubernetes manifests and infrastructure config. Access inventory data, validate with JSON Schema, and output YAML."
 ---
 
 # :kapitan-logo: **Kapitan with Jsonnet**

{kapitan-0.36.2.dev3 → kapitan-0.36.2.dev5}/docs/pages/input_types/kadet.md

@@ -1,5 +1,5 @@
 ---
-title: "Kapitan Kadet Input Type"
+title: "Kapitan Kadet Input Type: Python Config Generation"
 description: "Use Python and Kadet with Kapitan to generate infrastructure configuration. Define resources as classes and access the Kapitan inventory from Python code."
 ---
 

{kapitan-0.36.2.dev3 → kapitan-0.36.2.dev5}/docs/pages/input_types/kustomize.md

@@ -1,5 +1,5 @@
 ---
-title: "Kapitan Kustomize Input Type"
+title: "Kapitan Kustomize Input Type: Patch K8s Manifests"
 description: "Use Kustomize within Kapitan to patch and customize Kubernetes manifests across environments."
 ---
 

{kapitan-0.36.2.dev3 → kapitan-0.36.2.dev5}/docs/pages/input_types/remove.md

@@ -1,3 +1,8 @@
+---
+title: "Kapitan Remove Input Type: Delete Files and Directories"
+description: "Learn how to use the Kapitan remove input type to delete files or directories created during other compile inputs."
+---
+
 # :kapitan-logo:  Remove
 
 This input type simply removes files or directories. This can be helpful if you can't control particular files

{kapitan-0.36.2.dev3 → kapitan-0.36.2.dev5}/docs/pages/inventory/advanced.md

@@ -1,3 +1,8 @@
+---
+title: "Kapitan Advanced Inventory: Labels and Backends"
+description: "Discover advanced Kapitan inventory features such as target labels and selectors to group, filter, and organize your targets."
+---
+
 # Advanced Inventory Features
 
 ## Target labels

{kapitan-0.36.2.dev3 → kapitan-0.36.2.dev5}/docs/pages/inventory/omegaconf.md

@@ -1,3 +1,8 @@
+---
+title: "Kapitan OmegaConf Inventory Backend with Resolvers"
+description: "Configure the OmegaConf inventory backend in Kapitan for advanced interpolation, custom resolvers, and deferred evaluation."
+---
+
 # The OmegaConf Inventory Backend
 
 ## Overview

{kapitan-0.36.2.dev3 → kapitan-0.36.2.dev5}/docs/pages/inventory/reclass-rs.md

@@ -1,3 +1,8 @@
+---
+title: "Kapitan reclass-rs: Fast Rust Inventory Backend"
+description: "Speed up Kapitan inventory rendering with reclass-rs, a faster Rust reimplementation of the reclass backend for parameter references."
+---
+
 # The reclass-rs inventory backend
 
 ## Overview

{kapitan-0.36.2.dev3 → kapitan-0.36.2.dev5}/docs/pages/inventory/targets.md

@@ -1,4 +1,3 @@
-
 ---
 title: "Kapitan Inventory Targets: Defining Environments and Deployments"
 description: "Learn how to define Kapitan targets for production, staging, and development. Organize targets hierarchically and compile environment-specific configuration."

{kapitan-0.36.2.dev3 → kapitan-0.36.2.dev5}/docs/pages/kapitan_examples.md

@@ -1,6 +1,6 @@
 ---
 title: "Kapitan Examples: Kubernetes, Terraform, and Infrastructure"
-description: "Explore curated Kapitan examples for Kubernetes, Terraform, and multi-environment infrastructure. Clone the reference repository and compile working targets in minutes."
+description: "Explore curated Kapitan examples for Kubernetes, Terraform, and multi-environment infrastructure. Clone the reference repo and compile targets fast."
 ---
 
 # :kapitan-logo: **Kapitan Examples**

{kapitan-0.36.2.dev3 → kapitan-0.36.2.dev5}/docs/pages/kubernetes_configuration_management.md

@@ -1,6 +1,6 @@
 ---
 title: "Kubernetes Configuration Management with Kapitan"
-description: "Learn how Kapitan helps you manage Kubernetes manifests across environments. Compare plain YAML, Helm, Kustomize, and Kapitan workflows with a practical example."
+description: "Learn how Kapitan helps you manage Kubernetes manifests across environments. Compare plain YAML, Helm, Kustomize, and Kapitan workflows with an example."
 ---
 
 # :kapitan-logo: **Kubernetes Configuration Management with Kapitan**

{kapitan-0.36.2.dev3 → kapitan-0.36.2.dev5}/docs/pages/profiling.md

@@ -1,3 +1,8 @@
+---
+title: "Profiling Kapitan Runs: CPU and Memory Reports"
+description: "Learn how to profile Kapitan CPU and memory usage with pyinstrument and tracemalloc reports."
+---
+
 # Profiling Kapitan runs
 
 Kapitan ships with optional CPU and memory profiling that you can enable from

{kapitan-0.36.2.dev3 → kapitan-0.36.2.dev5}/docs/pages/publishing_generators.md

@@ -1,3 +1,8 @@
+---
+title: "Publishing Kapitan Generators as OCI Artifacts"
+description: "Learn how to package and publish Kapitan generators as OCI artifacts with oras for teams to consume."
+---
+
 # :kapitan-logo: Publishing generators as OCI artifacts
 
 Kapitan's [OCI dependency type](external_dependencies.md#defining-dependencies) lets you pull generator

{kapitan-0.36.2.dev3 → kapitan-0.36.2.dev5}/docs/pages/remote_repositories.md

@@ -1,3 +1,8 @@
+---
+title: "Kapitan Remote Inventories: Fetch Git and HTTP Classes"
+description: "Configure Kapitan to recursively fetch remote inventory classes and targets from Git and HTTP sources."
+---
+
 # :kapitan-logo: Remote Inventories
 
 Kapitan is capable of recursively fetching inventory items stored in remote locations and copy it to the specified output path. This feature can be used by specifying those inventory items in classes or targets under `parameters.kapitan.inventory`. Supported types are:

{kapitan-0.36.2.dev3 → kapitan-0.36.2.dev5}/docs/pages/troubleshooting.md

@@ -1,5 +1,5 @@
 ---
-title: "Kapitan Troubleshooting"
+title: "Kapitan Troubleshooting: Fix Common Errors & Issues"
 description: "Common Kapitan errors and how to resolve them. Covers inventory, compilation, input types, references, and installation issues."
 ---
 

{kapitan-0.36.2.dev3 → kapitan-0.36.2.dev5}/mkdocs.yml

@@ -126,6 +126,7 @@ nav:
           - Copy: pages/input_types/copy.md
           - Remove: pages/input_types/remove.md
       - References: references.md
+      - Environment variables: pages/environment_variables.md
       - Advanced Kapitan:
           - Remote repositories: pages/remote_repositories.md
           - External dependencies: pages/external_dependencies.md

kapitan-0.36.2.dev5/tests/test_docs_rendering.py

@@ -0,0 +1,131 @@
+#!/usr/bin/env python3
+"""Verify MkDocs Markdown extensions render fenced code blocks correctly.
+
+When pymdownx.superfences fails to interact properly with the markdown package,
+fenced code blocks (e.g.  ```yaml, ```tree) silently render as inline text in <p>
+tags instead of <pre><code> elements. This test catches that regression.
+
+Also enforces a baseline of SEO frontmatter (title + description, within the
+length bounds search engines actually use) on every docs page.
+"""
+
+import pathlib
+import re
+
+import markdown
+import pytest
+import yaml
+
+
+# Extensions loaded in mkdocs.yml (simplified set; superfences is the critical one)
+MKDOCS_MARKDOWN_EXTENSIONS = [
+    "md_in_html",
+    "admonition",
+    "pymdownx.tabbed",
+    "pymdownx.superfences",
+    "pymdownx.arithmatex",
+    "pymdownx.betterem",
+    "pymdownx.caret",
+    "pymdownx.critic",
+    "pymdownx.details",
+    "pymdownx.snippets",
+    "pymdownx.emoji",
+    "pymdownx.inlinehilite",
+    "pymdownx.magiclink",
+    "pymdownx.mark",
+    "pymdownx.smartsymbols",
+    "pymdownx.tasklist",
+    "pymdownx.tilde",
+    "markdown_include.include",
+    "attr_list",
+    "abbr",
+]
+
+FENCED_BLOCK_CASES = [
+    # yaml and plain are handled by pymdownx.superfences; mermaid uses a custom fence.
+    # tree blocks are handled by the markdown-exec mkdocs plugin and are not tested here.
+    (
+        "yaml_block",
+        "```yaml\n# inventory/targets/production.yaml\nclasses:\n  - common\n```",
+    ),
+    (
+        "mermaid_block",
+        "```mermaid\ngraph LR\n    A --> B\n```",
+    ),
+    (
+        "plain_code_block",
+        "```\n$ kapitan compile\nCompiled 200 targets\n```",
+    ),
+]
+
+
+@pytest.fixture(scope="module")
+def md():
+    return markdown.Markdown(extensions=MKDOCS_MARKDOWN_EXTENSIONS)
+
+
+@pytest.mark.parametrize(("name", "source"), FENCED_BLOCK_CASES)
+def test_fenced_block_renders(md, name, source):
+    md.reset()
+    html = md.convert(source)
+    assert "<pre" in html, f"Expected <pre> in rendered HTML, got: {html[:200]}"
+    assert "```" not in html, f"Literal backticks leaked into HTML: {html[:200]}"
+
+
+# --- SEO frontmatter enforcement -------------------------------------------
+#
+# Every docs page must carry a title and description in its YAML frontmatter,
+# sized to the limits search engines respect: titles get truncated in results
+# around ~60 chars, meta descriptions around ~160. Too-short values waste the
+# slot. New pages that skip frontmatter fail here instead of shipping invisible
+# to search.
+
+DOCS_PAGES_DIR = pathlib.Path(__file__).resolve().parent.parent / "docs" / "pages"
+
+TITLE_MIN, TITLE_MAX = 30, 65
+DESCRIPTION_MIN, DESCRIPTION_MAX = 50, 160
+
+# Matches a leading YAML frontmatter block. MkDocs only recognises frontmatter
+# when it is the very first thing in the file, so anchor at the start.
+_FRONTMATTER_RE = re.compile(r"\A---\r?\n(.*?)\r?\n---\r?\n", re.DOTALL)
+
+
+def _docs_pages():
+    return sorted(DOCS_PAGES_DIR.rglob("*.md"))
+
+
+def _page_id(path):
+    return str(path.relative_to(DOCS_PAGES_DIR))
+
+
+def _parse_frontmatter(text):
+    match = _FRONTMATTER_RE.match(text)
+    if not match:
+        return None
+    data = yaml.safe_load(match.group(1))
+    return data if isinstance(data, dict) else {}
+
+
+@pytest.mark.parametrize("page", _docs_pages(), ids=_page_id)
+def test_docs_page_has_seo_frontmatter(page):
+    frontmatter = _parse_frontmatter(page.read_text(encoding="utf-8"))
+    rel = _page_id(page)
+
+    assert (
+        frontmatter is not None
+    ), f"{rel}: missing a YAML frontmatter block (---) at the very top of the file"
+
+    title = frontmatter.get("title")
+    assert isinstance(title, str), f"{rel}: missing 'title' in frontmatter"
+    assert title.strip(), f"{rel}: empty 'title' in frontmatter"
+    assert (
+        TITLE_MIN <= len(title) <= TITLE_MAX
+    ), f"{rel}: title is {len(title)} chars, must be {TITLE_MIN}-{TITLE_MAX}: {title!r}"
+
+    description = frontmatter.get("description")
+    assert isinstance(description, str), f"{rel}: missing 'description' in frontmatter"
+    assert description.strip(), f"{rel}: empty 'description' in frontmatter"
+    assert DESCRIPTION_MIN <= len(description) <= DESCRIPTION_MAX, (
+        f"{rel}: description is {len(description)} chars, "
+        f"must be {DESCRIPTION_MIN}-{DESCRIPTION_MAX}: {description!r}"
+    )

kapitan-0.36.2.dev3/docs/pages/blog/index.md

@@ -1 +0,0 @@
-# Blog

kapitan-0.36.2.dev3/tests/test_docs_rendering.py

@@ -1,65 +0,0 @@
-#!/usr/bin/env python3
-"""Verify MkDocs Markdown extensions render fenced code blocks correctly.
-
-When pymdownx.superfences fails to interact properly with the markdown package,
-fenced code blocks (e.g.  ```yaml, ```tree) silently render as inline text in <p>
-tags instead of <pre><code> elements. This test catches that regression.
-"""
-
-import markdown
-import pytest
-
-
-# Extensions loaded in mkdocs.yml (simplified set; superfences is the critical one)
-MKDOCS_MARKDOWN_EXTENSIONS = [
-    "md_in_html",
-    "admonition",
-    "pymdownx.tabbed",
-    "pymdownx.superfences",
-    "pymdownx.arithmatex",
-    "pymdownx.betterem",
-    "pymdownx.caret",
-    "pymdownx.critic",
-    "pymdownx.details",
-    "pymdownx.snippets",
-    "pymdownx.emoji",
-    "pymdownx.inlinehilite",
-    "pymdownx.magiclink",
-    "pymdownx.mark",
-    "pymdownx.smartsymbols",
-    "pymdownx.tasklist",
-    "pymdownx.tilde",
-    "markdown_include.include",
-    "attr_list",
-    "abbr",
-]
-
-FENCED_BLOCK_CASES = [
-    # yaml and plain are handled by pymdownx.superfences; mermaid uses a custom fence.
-    # tree blocks are handled by the markdown-exec mkdocs plugin and are not tested here.
-    (
-        "yaml_block",
-        "```yaml\n# inventory/targets/production.yaml\nclasses:\n  - common\n```",
-    ),
-    (
-        "mermaid_block",
-        "```mermaid\ngraph LR\n    A --> B\n```",
-    ),
-    (
-        "plain_code_block",
-        "```\n$ kapitan compile\nCompiled 200 targets\n```",
-    ),
-]
-
-
-@pytest.fixture(scope="module")
-def md():
-    return markdown.Markdown(extensions=MKDOCS_MARKDOWN_EXTENSIONS)
-
-
-@pytest.mark.parametrize(("name", "source"), FENCED_BLOCK_CASES)
-def test_fenced_block_renders(md, name, source):
-    md.reset()
-    html = md.convert(source)
-    assert "<pre" in html, f"Expected <pre> in rendered HTML, got: {html[:200]}"
-    assert "```" not in html, f"Literal backticks leaked into HTML: {html[:200]}"