# rootiest/zippy_guides architecture

> Architecture diagram of the GitHub repository rootiest/zippy_guides, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rootiest/zippy_guides
- Repository: https://github.com/rootiest/zippy_guides

## Overview

1. This repository is a static documentation project, not an application or service. Its “architecture” is primarily content organization: Markdown guides, reusable snippets, and supporting assets for Klipper users.

2. The top-level entry point is `README.md`, which acts as a catalog of the available guides. It routes readers into the individual topics under `guides/` and also surfaces external references.

3. The main subsystem is the `guides/` directory. Each file is a self-contained instructional document focused on a specific Klipper topic:
   - printer calibration and boundaries (`axis_limits.md`, `probe.md`, `mesh.md`)
   - macro authoring and advanced macro behavior (`macros.md`, `variables.md`)
   - config composition and reuse (`includes.md`)
   - hardware integration topics (`usb-pico.md`, `pico_can.md`)
   - link collection / reference material (`links.md`)

4. The content is organized as a knowledge graph rather than a code dependency graph. The guides cross-link to each other and to external documentation, with `README.md` serving as the central index and `guides/links.md` acting as a curated reference hub.

5. The `resources/` directory contains small reusable configuration artifacts for Klipper workflows. These `.cfg` files are not application code; they are practical snippets or templates intended to be copied into printer configuration or macro setups.

6. A notable architectural boundary is between “tutorial content” and “machine-specific config examples.” The guides explain concepts and workflows, while `resources/*.cfg` provides operational pieces that can be imported or adapted into a real Klipper configuration.

7. The repository relies heavily on Markdown and relative linking, so link correctness is part of the architecture. The GitHub Actions workflows include dedicated link and Markdown linting to keep the guide network coherent and prevent broken navigation.

8. The `.github/workflows/` directory shows the maintenance pipeline:
   - Markdown linting
   - link validation
   - a helper script for committing generated changes when files are updated
   This indicates the repo is maintained through automated documentation quality checks rather than build/test execution.

9. There is no backend, database, or runtime service boundary here. All functionality is delivered through static files, so the main “integration points” are GitHub, Markdown renderers, and external Klipper community resources.

10. External services matter mainly as reference dependencies: the official Klipper docs, Klipper Discord, Voron Discord, Ellis’s tuning guide, and CANbus resources. These are treated as authoritative upstream sources that complement the repository’s own guides.

11. From an architecture-diagram perspective, the cleanest model is:
   - one central documentation hub (`README.md`)
   - several topic-focused guides (`guides/`)
   - reusable config examples (`resources/`)
   - CI/quality gates in GitHub Actions
   - external knowledge sources linked from the docs

12. Overall, this repo is a curated documentation system for Klipper-related printer setup and tuning, with automation focused on content hygiene and link integrity rather than software execution.

Main entry points: [`README.md`](https://github.com/rootiest/zippy_guides/blob/main/README.md) (README), [`guides/links.md`](https://github.com/rootiest/zippy_guides/blob/main/guides/links.md) (Links), [`guides/macros.md`](https://github.com/rootiest/zippy_guides/blob/main/guides/macros.md) (Macros), [`guides/includes.md`](https://github.com/rootiest/zippy_guides/blob/main/guides/includes.md) (Includes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_docs["Documentation"]
  node_readme["README<br/>doc index<br/>[README.md]"]
  node_guides_corpus["Guides<br/>topic corpus"]
  node_axis_limits["Axis Limits<br/>guide<br/>[axis_limits.md]"]
  node_probe["Probe Setup<br/>guide<br/>[probe.md]"]
  node_mesh["Bed Mesh<br/>guide<br/>[mesh.md]"]
  node_macros["Macros<br/>guide<br/>[macros.md]"]
  node_variables["Variables<br/>guide<br/>[variables.md]"]
  node_includes["Includes<br/>guide<br/>[includes.md]"]
  node_usb_pico["USB Pico<br/>guide<br/>[usb-pico.md]"]
  node_pico_can["Pico CAN<br/>guide<br/>[pico_can.md]"]
  node_links["Links<br/>reference hub<br/>[links.md]"]
end

subgraph group_assets["Reusable Snippets"]
  node_probe_limits_cfg["Probe Limits<br/>cfg snippet"]
  node_material_cfg["Material Preset<br/>cfg snippet<br/>[SET_MATERIAL.cfg]"]
end

subgraph group_ci["Automation"]
  node_md_lint["MD Lint<br/>workflow<br/>[md_lint.yml]"]
  node_md_links["Link Check<br/>workflow<br/>[md_links.yml]"]
  node_linter["Meta Lint<br/>workflow<br/>[linter.yml]"]
  node_commit_changed["Commit Helper<br/>script"]
end

subgraph group_external["External References"]
  node_klipper_docs["Klipper Docs<br/>external docs"]
  node_discords["Discord Communities<br/>external community"]
  node_ellis["Ellis Guide<br/>external tuning guide"]
  node_canbus_refs["CANbus Resources<br/>external reference"]
end

node_readme -->|"indexes"| node_guides_corpus
node_readme -->|"indexes"| node_axis_limits
node_readme -->|"indexes"| node_probe
node_readme -->|"indexes"| node_mesh
node_readme -->|"indexes"| node_macros
node_readme -->|"indexes"| node_variables
node_readme -->|"indexes"| node_includes
node_readme -->|"indexes"| node_usb_pico
node_readme -->|"indexes"| node_pico_can
node_readme -->|"routes to"| node_links
node_axis_limits -.->|"cross-links"| node_probe
node_probe -.->|"feeds"| node_mesh
node_macros -.->|"depends on"| node_variables
node_includes -.->|"supports"| node_macros
node_includes -.->|"reuses"| node_probe_limits_cfg
node_macros -.->|"reuses"| node_material_cfg
node_links -->|"references"| node_klipper_docs
node_links -->|"references"| node_discords
node_links -->|"references"| node_ellis
node_pico_can -.->|"references"| node_canbus_refs
node_md_links -->|"validates"| node_readme
node_md_links -->|"validates"| node_links
node_md_lint -->|"checks"| node_readme
node_md_lint -->|"checks"| node_guides_corpus
node_linter -->|"orchestrates"| node_md_lint
node_linter -->|"orchestrates"| node_md_links
node_commit_changed -.->|"supports"| node_linter

click node_readme "https://github.com/rootiest/zippy_guides/blob/main/README.md"
click node_axis_limits "https://github.com/rootiest/zippy_guides/blob/main/guides/axis_limits.md"
click node_probe "https://github.com/rootiest/zippy_guides/blob/main/guides/probe.md"
click node_mesh "https://github.com/rootiest/zippy_guides/blob/main/guides/mesh.md"
click node_macros "https://github.com/rootiest/zippy_guides/blob/main/guides/macros.md"
click node_variables "https://github.com/rootiest/zippy_guides/blob/main/guides/variables.md"
click node_includes "https://github.com/rootiest/zippy_guides/blob/main/guides/includes.md"
click node_usb_pico "https://github.com/rootiest/zippy_guides/blob/main/guides/usb-pico.md"
click node_pico_can "https://github.com/rootiest/zippy_guides/blob/main/guides/pico_can.md"
click node_links "https://github.com/rootiest/zippy_guides/blob/main/guides/links.md"
click node_probe_limits_cfg "https://github.com/rootiest/zippy_guides/blob/main/resources/GET_PROBE_LIMITS.cfg"
click node_material_cfg "https://github.com/rootiest/zippy_guides/blob/main/resources/SET_MATERIAL.cfg"
click node_md_lint "https://github.com/rootiest/zippy_guides/blob/main/.github/workflows/md_lint.yml"
click node_md_links "https://github.com/rootiest/zippy_guides/blob/main/.github/workflows/md_links.yml"
click node_linter "https://github.com/rootiest/zippy_guides/blob/main/.github/workflows/linter.yml"
click node_commit_changed "https://github.com/rootiest/zippy_guides/blob/main/.github/workflows/commit_if_changed.sh"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_readme,node_guides_corpus,node_axis_limits,node_probe,node_mesh,node_macros,node_variables,node_includes,node_usb_pico,node_pico_can,node_links toneBlue
class node_probe_limits_cfg,node_material_cfg toneAmber
class node_md_lint,node_md_links,node_linter,node_commit_changed toneMint
class node_klipper_docs,node_discords,node_ellis,node_canbus_refs toneRose
```

## Components

### Documentation

Markdown index, topic guides, and reference hub.

- [README](https://github.com/rootiest/zippy_guides/blob/main/README.md): doc index · Central catalog that routes readers into the guide set and key references. · `README.md`
- **Guides**: topic corpus · Collection of self-contained Klipper how-to guides.
- [Axis Limits](https://github.com/rootiest/zippy_guides/blob/main/guides/axis_limits.md): guide · Printer movement boundaries and safe axis range handling. · `guides/axis_limits.md`
- [Probe Setup](https://github.com/rootiest/zippy_guides/blob/main/guides/probe.md): guide · Probe configuration and calibration workflow. · `guides/probe.md`
- [Bed Mesh](https://github.com/rootiest/zippy_guides/blob/main/guides/mesh.md): guide · Mesh leveling and bed compensation topics. · `guides/mesh.md`
- [Macros](https://github.com/rootiest/zippy_guides/blob/main/guides/macros.md): guide · Macro authoring patterns and advanced behavior. · `guides/macros.md`
- [Variables](https://github.com/rootiest/zippy_guides/blob/main/guides/variables.md): guide · Variable usage and state handling for macros. · `guides/variables.md`
- [Includes](https://github.com/rootiest/zippy_guides/blob/main/guides/includes.md): guide · Configuration composition and reuse via include patterns. · `guides/includes.md`
- [USB Pico](https://github.com/rootiest/zippy_guides/blob/main/guides/usb-pico.md): guide · USB-connected Raspberry Pi Pico integration. · `guides/usb-pico.md`
- [Pico CAN](https://github.com/rootiest/zippy_guides/blob/main/guides/pico_can.md): guide · CAN bus integration and Pico-based hardware connectivity. · `guides/pico_can.md`
- [Links](https://github.com/rootiest/zippy_guides/blob/main/guides/links.md): reference hub · Curated external references and related community resources. · `guides/links.md`

### Reusable Snippets

Copyable Klipper config fragments and templates.

- [Probe Limits](https://github.com/rootiest/zippy_guides/blob/main/resources/GET_PROBE_LIMITS.cfg): cfg snippet · Reusable configuration snippet for probe limit handling. · `resources/GET_PROBE_LIMITS.cfg`
- [Material Preset](https://github.com/rootiest/zippy_guides/blob/main/resources/SET_MATERIAL.cfg): cfg snippet · Reusable material-setting configuration template. · `resources/SET_MATERIAL.cfg`

### Automation

Workflow checks that keep links and Markdown healthy.

- [MD Lint](https://github.com/rootiest/zippy_guides/blob/main/.github/workflows/md_lint.yml): workflow · Markdown linting gate for documentation quality. · `.github/workflows/md_lint.yml`
- [Link Check](https://github.com/rootiest/zippy_guides/blob/main/.github/workflows/md_links.yml): workflow · Validates relative and external links across the docs. · `.github/workflows/md_links.yml`
- [Meta Lint](https://github.com/rootiest/zippy_guides/blob/main/.github/workflows/linter.yml): workflow · General repository linting automation. · `.github/workflows/linter.yml`
- [Commit Helper](https://github.com/rootiest/zippy_guides/blob/main/.github/workflows/commit_if_changed.sh): script · Workflow helper for committing generated changes when files update. · `.github/workflows/commit_if_changed.sh`

### External References

Upstream and community resources linked from the docs.

- **Klipper Docs**: external docs · Official upstream Klipper documentation referenced by the guides.
- **Discord Communities**: external community · Klipper and Voron community discussion resources.
- **Ellis Guide**: external tuning guide · External tuning and calibration reference used by the repository.
- **CANbus Resources**: external reference · External CANbus setup and troubleshooting references.

## Connections

- README → Guides: indexes · Central catalog points into the guide collection.
- README → Axis Limits: indexes · Catalog entry to topic guide.
- README → Probe Setup: indexes · Catalog entry to topic guide.
- README → Bed Mesh: indexes · Catalog entry to topic guide.
- README → Macros: indexes · Catalog entry to topic guide.
- README → Variables: indexes · Catalog entry to topic guide.
- README → Includes: indexes · Catalog entry to topic guide.
- README → USB Pico: indexes · Catalog entry to topic guide.
- README → Pico CAN: indexes · Catalog entry to topic guide.
- README → Links: routes to · Central index points readers to the reference hub.
- Axis Limits → Probe Setup: cross-links · Related calibration workflow.
- Probe Setup → Bed Mesh: feeds · Probe setup supports mesh generation.
- Macros → Variables: depends on · Macro behavior relies on variable handling.
- Includes → Macros: supports · Config composition underpins reusable macros.
- Includes → Probe Limits: reuses · Guide content is complemented by a reusable snippet.
- Macros → Material Preset: reuses · Macro workflows may use material presets.
- Links → Klipper Docs: references · Curated upstream documentation.
- Links → Discord Communities: references · Community support resources.
- Links → Ellis Guide: references · Tuning and calibration guidance.
- Pico CAN → CANbus Resources: references · Hardware integration guide points to CANbus resources.
- Link Check → README: validates · Link checker protects the documentation hub.
- Link Check → Links: validates · Ensures curated references remain reachable.
- MD Lint → README: checks · Markdown linting covers the index document.
- MD Lint → Guides: checks · Markdown linting covers the guide corpus.
- Meta Lint → MD Lint: orchestrates · General automation layer coordinates linting.
- Meta Lint → Link Check: orchestrates · General automation layer coordinates link checks.
- Commit Helper → Meta Lint: supports · Helper script assists generated-change commits in automation.