Fix: Tweak link transformation for absolute paths in source repo

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,51 +15,51 @@ 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.
 
 ---
 
 ## B
 
 ### 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.
 
 ---
 
 ## C
 
 ### 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.
 
 ---
 

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

scripts/repos-config.json

@@ -17,7 +17,7 @@
         "contributing": "contributing"
       },
       "special_files": {},
-      "media_directories": [".media"]
+      "media_directories": [".media", "assets"]
     },
     {
       "name": "builder",

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,54 @@ 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)
+
+                # 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: