From 06ca9d5cfae0193bc9a8e1ad30a06b2c71811f79 Mon Sep 17 00:00:00 2001 From: Tiara Lena Hock Date: Mon, 30 Mar 2026 15:51:29 +0200 Subject: [PATCH 1/3] Fix: Tweak link transformation to deal with absolute paths in source directory for media --- scripts/transform_content.py | 27 +++++++++++++++++++++++++-- 1 file changed, 25 insertions(+), 2 deletions(-) diff --git a/scripts/transform_content.py b/scripts/transform_content.py index 24eec1f..102318c 100755 --- a/scripts/transform_content.py +++ b/scripts/transform_content.py @@ -511,7 +511,11 @@ def check_and_fix_link(match): if ( potential_file.exists() or potential_index.exists() - or (potential_dir.exists() and potential_dir.is_dir() and (potential_dir / "index.md").exists()) + or ( + potential_dir.exists() + and potential_dir.is_dir() + and (potential_dir / "index.md").exists() + ) ): return match.group(0) @@ -660,7 +664,12 @@ def copy_targeted_docs(source_dir, docs_dir, repo_name): # Check for 'github_target_path' in frontmatter if frontmatter and ("github_target_path" in frontmatter): - target_path = frontmatter.get("github_target_path") or frontmatter.get("target") + target_path = frontmatter.get("github_target_path") or frontmatter.get( + "target" + ) + + if target_path is None: + continue # Strip leading 'docs/' if present if target_path.startswith("docs/"): @@ -674,9 +683,23 @@ def copy_targeted_docs(source_dir, docs_dir, repo_name): # Copy the file shutil.copy2(md_file, target_file) + # Copy associated assets directory if it exists next to the source file + source_assets_dir = md_file.parent / "assets" + if source_assets_dir.exists() and source_assets_dir.is_dir(): + target_assets_dir = target_file.parent / "assets" + if target_assets_dir.exists(): + shutil.rmtree(target_assets_dir) + shutil.copytree(source_assets_dir, target_assets_dir) + print(f" → Copied assets directory") + # Apply markdown processing (but not project-specific link rewriting) # These files live in main docs tree, not under /projects/ # content = escape_angle_brackets(content) + + # Strip /docs/ prefix from absolute paths + content = re.sub(r"(\[([^\]]*)\]\()/docs/", r"\1/", content) + content = re.sub(r'(src=")/docs/', r"\1/", content) + content = ensure_frontmatter(content) with open(target_file, "w", encoding="utf-8") as f: From 1f73ce19b201b650a69357b186aee2461b47298f Mon Sep 17 00:00:00 2001 From: Tiara Lena Hock Date: Mon, 30 Mar 2026 16:01:16 +0200 Subject: [PATCH 2/3] Include .media and assets directories in media dir search pattern --- scripts/repos-config.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/scripts/repos-config.json b/scripts/repos-config.json index e30f8ff..f37656b 100644 --- a/scripts/repos-config.json +++ b/scripts/repos-config.json @@ -17,7 +17,7 @@ "contributing": "contributing" }, "special_files": {}, - "media_directories": [".media"] + "media_directories": [".media", "assets"] }, { "name": "builder", From 4f95e5316372a237b667c5734f21ba2a2e57b766 Mon Sep 17 00:00:00 2001 From: Tiara Lena Hock Date: Mon, 30 Mar 2026 16:29:39 +0200 Subject: [PATCH 3/3] Fix: Parse relative links to absolute ones so they don't break --- docs/reference/glossary.md | 22 +++++++++++----------- docs/tutorials/index.md | 20 ++++++++++---------- scripts/transform_content.py | 31 +++++++++++++++++++++++++++++++ 3 files changed, 52 insertions(+), 21 deletions(-) diff --git a/docs/reference/glossary.md b/docs/reference/glossary.md index e540e29..2777053 100644 --- a/docs/reference/glossary.md +++ b/docs/reference/glossary.md @@ -5,7 +5,7 @@ order: 1 # Glossary -This glossary provides definitions for Garden Linux-specific terminology. If you would like to contribute additional terms or improve existing definitions, please visit our [contributing guide](../contributing/index.md). +This glossary provides definitions for Garden Linux-specific terminology. If you would like to contribute additional terms or improve existing definitions, please visit our [contributing guide](/contributing/index.md). **Jump to:** [A](#a) · [B](#b) · [C](#c) · [D](#d) · [E](#e) · [F](#f) · [G](#g) · [I](#i) · [K](#k) · [L](#l) · [M](#m) · [N](#n) · [O](#o) · [P](#p) · [R](#r) · [S](#s) · [T](#t) · [U](#u) · [V](#v) @@ -15,19 +15,19 @@ This glossary provides definitions for Garden Linux-specific terminology. If you ### ADR (Architecture Decision Record) -A document that captures an important architectural decision made about the Garden Linux system. ADRs provide context, rationale, and consequences of decisions. Garden Linux stores ADRs in the [reference/adr](./adr/index.md) section. See [ADR-0001](./adr/0001-record-architecture-decisions.md) for more background on why Garden Linux uses ADRs, and [Documenting Architecture Decisions](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions) by Michael Nygard for the original concept. +A document that captures an important architectural decision made about the Garden Linux system. ADRs provide context, rationale, and consequences of decisions. Garden Linux stores ADRs in the [reference/adr](/reference/adr/index.md) section. See [ADR-0001](/reference/adr/0001-record-architecture-decisions.md) for more background on why Garden Linux uses ADRs, and [Documenting Architecture Decisions](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions) by Michael Nygard for the original concept. ### Architecture -The processor architecture for which a Garden Linux image is built. Supported architectures include `amd64` (x86-64) and `arm64` (ARM 64-bit). The architecture can be specified as the last component of a build flavor string, e.g., `kvm-python-amd64`. See [Architecture documentation](../explanation/architecture.md) for details on Garden Linux system design. +The processor architecture for which a Garden Linux image is built. Supported architectures include `amd64` (x86-64) and `arm64` (ARM 64-bit). The architecture can be specified as the last component of a build flavor string, e.g., `kvm-python-amd64`. See [Architecture documentation](/explanation/architecture.md) for details on Garden Linux system design. ### AWS -Amazon Web Services. One of the major cloud platforms supported by Garden Linux. Garden Linux provides AWS-specific images through the [`aws`](https://github.com/gardenlinux/gardenlinux/blob/main/features/aws/README.md) platform feature with cloud-init integration and AWS-specific kernel modules. See [AWS platform guide](../how-to/platform-specific/aws.md) and [AWS first boot tutorial](../tutorials/first-boot-aws.md) for usage details. +Amazon Web Services. One of the major cloud platforms supported by Garden Linux. Garden Linux provides AWS-specific images through the [`aws`](https://github.com/gardenlinux/gardenlinux/blob/main/features/aws/README.md) platform feature with cloud-init integration and AWS-specific kernel modules. See [AWS platform guide](/how-to/platform-specific/aws.md) and [AWS first boot tutorial](/tutorials/first-boot-aws.md) for usage details. ### Azure -Microsoft Azure. A major cloud platform supported by Garden Linux through the [`azure`](https://github.com/gardenlinux/gardenlinux/blob/main/features/azure/README.md) platform feature with platform-specific image configurations and optimizations. See [Azure platform guide](../how-to/platform-specific/azure.md) and [Azure first boot tutorial](../tutorials/first-boot-azure.md) for usage details. +Microsoft Azure. A major cloud platform supported by Garden Linux through the [`azure`](https://github.com/gardenlinux/gardenlinux/blob/main/features/azure/README.md) platform feature with platform-specific image configurations and optimizations. See [Azure platform guide](/how-to/platform-specific/azure.md) and [Azure first boot tutorial](/tutorials/first-boot-azure.md) for usage details. --- @@ -35,15 +35,15 @@ Microsoft Azure. A major cloud platform supported by Garden Linux through the [` ### Bare Metal -A platform target for Garden Linux images designed to run directly on physical hardware without a hypervisor through the [`baremetal`](https://github.com/gardenlinux/gardenlinux/blob/main/features/baremetal/README.md) platform feature. Also referred to as [`metal`](https://github.com/gardenlinux/gardenlinux/blob/main/features/metal/README.md) in build configurations. See [Bare Metal platform guide](../how-to/platform-specific/bare-metal.md) and [Bare Metal first boot tutorial](../tutorials/first-boot-bare-metal.md) for usage details. +A platform target for Garden Linux images designed to run directly on physical hardware without a hypervisor through the [`baremetal`](https://github.com/gardenlinux/gardenlinux/blob/main/features/baremetal/README.md) platform feature. Also referred to as [`metal`](https://github.com/gardenlinux/gardenlinux/blob/main/features/metal/README.md) in build configurations. See [Bare Metal platform guide](/how-to/platform-specific/bare-metal.md) and [Bare Metal first boot tutorial](/tutorials/first-boot-bare-metal.md) for usage details. ### Builder -The [gardenlinux/builder](https://github.com/gardenlinux/builder) component that creates customized Linux distributions. The builder is a separate project maintained by the Garden Linux team and is used to build Garden Linux images with specific flavors and features. See [Building Images documentation](../how-to/building-images.md) for practical guidance, [ADR-0020](./adr/0020-enforce-single-platform-by-default-in-builder.md) for details on platform enforcement in the builder, and [ADR-0031](./adr/0031-builder-glci-interface.md) for the builder-GLCI interface design. +The [gardenlinux/builder](https://github.com/gardenlinux/builder) component that creates customized Linux distributions. The builder is a separate project maintained by the Garden Linux team and is used to build Garden Linux images with specific flavors and features. See [Building Images documentation](/how-to/building-images.md) for practical guidance, [ADR-0020](/reference/adr/0020-enforce-single-platform-by-default-in-builder.md) for details on platform enforcement in the builder, and [ADR-0031](/reference/adr/0031-builder-glci-interface.md) for the builder-GLCI interface design. ### Build Flavor String -The hyphenated string used with the `./build` command that specifies the platform, features, and optionally the architecture for a Garden Linux image. Format: `${platform}-${feature1}-${feature2}-${arch}`. Examples: `kvm-python_dev`, `aws-gardener_prod-amd64`. See [Building Flavors guide](../how-to/customization/building-flavors.md) for detailed instructions. +The hyphenated string used with the `./build` command that specifies the platform, features, and optionally the architecture for a Garden Linux image. Format: `${platform}-${feature1}-${feature2}-${arch}`. Examples: `kvm-python_dev`, `aws-gardener_prod-amd64`. See [Building Flavors guide](/how-to/customization/building-flavors.md) for detailed instructions. --- @@ -51,15 +51,15 @@ The hyphenated string used with the `./build` command that specifies the platfor ### CIS (Center for Internet Security) -A framework providing security configuration benchmarks. Garden Linux offers optional CIS compliance through the [`cis`](https://github.com/gardenlinux/gardenlinux/blob/main/features/cis/README.md) feature and related sub-features ([`cisAudit`](https://github.com/gardenlinux/gardenlinux/blob/main/features/cisAudit/README.md), [`cisModprobe`](https://github.com/gardenlinux/gardenlinux/blob/main/features/cisModprobe/README.md), [`cisOS`](https://github.com/gardenlinux/gardenlinux/blob/main/features/cisOS/README.md), [`cisPackages`](https://github.com/gardenlinux/gardenlinux/blob/main/features/cisPackages/README.md), [`cisPartition`](https://github.com/gardenlinux/gardenlinux/blob/main/features/cisPartition/README.md), [`cisSshd`](https://github.com/gardenlinux/gardenlinux/blob/main/features/cisSshd/README.md), [`cisSysctl`](https://github.com/gardenlinux/gardenlinux/blob/main/features/cisSysctl/README.md)). See [ADR-0017](./adr/0017-feature-cis-to-retain-shell-scripts.md) for details on the CIS feature implementation and [ADR-0029](./adr/0029-cis-selinux-permissive.md) regarding SELinux in permissive mode for CIS compliance. +A framework providing security configuration benchmarks. Garden Linux offers optional CIS compliance through the [`cis`](https://github.com/gardenlinux/gardenlinux/blob/main/features/cis/README.md) feature and related sub-features ([`cisAudit`](https://github.com/gardenlinux/gardenlinux/blob/main/features/cisAudit/README.md), [`cisModprobe`](https://github.com/gardenlinux/gardenlinux/blob/main/features/cisModprobe/README.md), [`cisOS`](https://github.com/gardenlinux/gardenlinux/blob/main/features/cisOS/README.md), [`cisPackages`](https://github.com/gardenlinux/gardenlinux/blob/main/features/cisPackages/README.md), [`cisPartition`](https://github.com/gardenlinux/gardenlinux/blob/main/features/cisPartition/README.md), [`cisSshd`](https://github.com/gardenlinux/gardenlinux/blob/main/features/cisSshd/README.md), [`cisSysctl`](https://github.com/gardenlinux/gardenlinux/blob/main/features/cisSysctl/README.md)). See [ADR-0017](/reference/adr/0017-feature-cis-to-retain-shell-scripts.md) for details on the CIS feature implementation and [ADR-0029](/reference/adr/0029-cis-selinux-permissive.md) regarding SELinux in permissive mode for CIS compliance. ### Cloud Image -A Garden Linux image optimized for cloud platforms (AWS, Azure, GCP, etc.) with cloud-init support and platform-specific configurations. See [Image Types documentation](../explanation/image-types.md) and [Image Formats reference](./image-formats.md) for more details. +A Garden Linux image optimized for cloud platforms (AWS, Azure, GCP, etc.) with cloud-init support and platform-specific configurations. See [Image Types documentation](/explanation/image-types.md) and [Image Formats reference](/reference/image-formats.md) for more details. ### Container Image -A Garden Linux image packaged for use with container runtimes. Available through GitHub Packages at `ghcr.io/gardenlinux/gardenlinux`. See [Image Types documentation](../explanation/image-types.md) for more details. +A Garden Linux image packaged for use with container runtimes. Available through GitHub Packages at `ghcr.io/gardenlinux/gardenlinux`. See [Image Types documentation](/explanation/image-types.md) for more details. --- diff --git a/docs/tutorials/index.md b/docs/tutorials/index.md index 8ebf8c5..a1dd690 100644 --- a/docs/tutorials/index.md +++ b/docs/tutorials/index.md @@ -21,8 +21,8 @@ Tutorials are **learning-oriented** lessons that take you through a series of st :::tip Recommended First Tutorial Want to try Garden Linux right now with zero setup cost? -- **macOS or Linux**: [First Boot on Lima](./local/first-boot-lima.md) -- **Any OS with Docker**: [First Boot as OCI Container](./container/first-boot-oci.md) +- **macOS or Linux**: [First Boot on Lima](/tutorials/local/first-boot-lima) +- **Any OS with Docker**: [First Boot as OCI Container](/tutorials/container/first-boot-oci) Both tutorials run entirely on your workstation in under 5 minutes. ::: @@ -33,10 +33,10 @@ Both tutorials run entirely on your workstation in under 5 minutes. Browse tutorials by deployment target: -- [**Local**](./local/index.md) — Run Garden Linux on your workstation (Lima, KVM) -- [**Container**](./container/index.md) — Run as an OCI container (Docker/Podman) -- [**Cloud**](./cloud/index.md) — Deploy to cloud providers (AWS, Azure, GCP, OpenStack) -- [**On-Premises**](./on-premises/index.md) — Install on physical hardware +- [**Local**](/tutorials/local/index) — Run Garden Linux on your workstation (Lima, KVM) +- [**Container**](/tutorials/container/index) — Run as an OCI container (Docker/Podman) +- [**Cloud**](/tutorials/cloud/index) — Deploy to cloud providers (AWS, Azure, GCP, OpenStack) +- [**On-Premises**](/tutorials/on-premises/index) — Install on physical hardware --- @@ -48,7 +48,7 @@ Following the [Diátaxis framework](https://diataxis.fr/), tutorials focus on pr Once you've completed your first tutorial, you can: -- Explore [how-to guides](../how-to/index.md) for task-oriented instructions -- Read [explanations](../explanation/index.md) to understand Garden Linux concepts and architecture -- Review [reference documentation](../reference/index.md) for technical specifications -- Learn about [contributing](../contributing/index.md) to Garden Linux +- Explore [how-to guides](/how-to/index) for task-oriented instructions +- Read [explanations](/explanation/index) to understand Garden Linux concepts and architecture +- Review [reference documentation](/reference/index) for technical specifications +- Learn about [contributing](/contributing/index) to Garden Linux diff --git a/scripts/transform_content.py b/scripts/transform_content.py index 102318c..263382b 100755 --- a/scripts/transform_content.py +++ b/scripts/transform_content.py @@ -700,6 +700,37 @@ def copy_targeted_docs(source_dir, docs_dir, repo_name): content = re.sub(r"(\[([^\]]*)\]\()/docs/", r"\1/", content) content = re.sub(r'(src=")/docs/', r"\1/", content) + # Rewrite relative markdown links to absolute paths + # When files are moved, relative links break, so convert them to absolute + def solve_relative_link(match): + text = match.group(1) + link = match.group(2) + # Skip anchors, absolute paths, and external links + if ( + link.startswith("#") + or link.startswith("/") + or link.startswith("http") + or link.startswith("mailto") + ): + return match.group(0) + # Relative link - convert to absolute based on original location + # Get the original file's directory + original_dir = md_file.relative_to(source_path).parent + # Resolve the relative link from the original location and normalize + resolved = os.path.normpath( + os.path.join(str(original_dir), link) + ).replace("\\", "/") + # Strip leading ../ for paths that try to go above root + while resolved.startswith("../"): + resolved = resolved[3:] + # Clean up the path (remove .md) + resolved = resolved.replace(".md", "") + return f"[{text}](/{resolved})" + + content = re.sub( + r"\[([^\]]+)\]\(([^)]+)\)", solve_relative_link, content + ) + content = ensure_frontmatter(content) with open(target_file, "w", encoding="utf-8") as f: