mkdocs.yml

Rama main · réplica de lectura del repositorio original.

# The zoomies.sh site.
#
# It publishes the docs that already live in docs/ rather than a second copy of
# them, so the website cannot drift from the repository. install.sh and
# install.ps1 are copied to the site root by the deploy workflow, again from the
# ones in the repository root, so `curl -fsSL https://zoomies.sh/install.sh | sh`
# and the file a contributor edits are the same file.

site_name: Zoomies
site_url: https://zoomies.sh/
site_description: >-
  Free, open-source self-hosted GitHub Actions runners with ephemeral jobs, a
  live web UI, autoscaling across your own hosts and a path off static runners.
site_author: Zoomies contributors
copyright: Zoomies is AGPL-3.0 licensed.

repo_url: https://github.com/eyupio/zoomies
repo_name: eyupio/zoomies
edit_uri: edit/main/docs/

docs_dir: docs
site_dir: site

theme:
  name: material
  # Sharing and structured metadata that Material does not emit by itself.
  # overrides/main.html extends the theme rather than replacing anything. It is
  # outside docs/ so the template is not also published as a page.
  custom_dir: overrides
  language: en
  favicon: brand/favicon.ico
  # The header renders at favicon scale, where v2.1 reserves the paw/swish.
  # overrides/partials/logo.html draws this one on the dark scheme and the
  # black one on the light scheme, since the header sits on the page's ground.
  logo: brand/paw-swish-white.png
  icon:
    repo: fontawesome/brands/github
  # No `font:` key: the faces are self-hosted rather than fetched from Google
  # Fonts. overrides/main.html replaces the theme's font block, and
  # docs/stylesheets/ carries the @font-face rules and the woff2 files beside
  # it. A third-party font stylesheet is render-blocking, and when the host is
  # slow or unreachable the tab spins with nothing to show.
  features:
    - navigation.tracking
    - navigation.sections
    - navigation.top
    - navigation.footer
    - toc.follow
    - search.suggest
    - search.highlight
    - search.share
    - content.code.copy
    - content.code.annotate
  palette:
    # The brand is a near-black identity, so dark is the default and light is
    # the alternative rather than the other way round.
    - media: "(prefers-color-scheme: dark)"
      scheme: slate
      primary: custom
      accent: custom
      toggle:
        icon: material/weather-sunny
        name: Switch to light
    - media: "(prefers-color-scheme: light)"
      scheme: default
      primary: custom
      accent: custom
      toggle:
        icon: material/weather-night
        name: Switch to dark

extra_css:
  - stylesheets/zoomies.css
  - stylesheets/animated-logo.css
  - stylesheets/showcase.css
  - stylesheets/showcase-material.css
  - stylesheets/cloud.css

extra_javascript:
  - javascripts/animated-logo.js
  - javascripts/showcase.js

markdown_extensions:
  - abbr
  - admonition
  - attr_list
  - def_list
  - footnotes
  - md_in_html
  - tables
  - toc:
      permalink: true
      permalink_title: Link to this section
  - pymdownx.details
  # Material's icon sets, as `:material-webhook:` shortcodes. The home page's
  # feature cards and comparison table use them; they render as inline SVG that
  # inherits the text colour, so there is no icon image to theme or to go stale.
  - pymdownx.emoji:
      emoji_index: !!python/name:material.extensions.emoji.twemoji
      emoji_generator: !!python/name:material.extensions.emoji.to_svg
  - pymdownx.highlight:
      anchor_linenums: true
      line_spans: __span
      pygments_lang_class: true
  - pymdownx.inlinehilite
  - pymdownx.snippets
  # Diagrams are Mermaid, rendered in the browser and themed by Material to
  # follow whichever palette the reader is in. A diagram is a fenced block in
  # the same file as the prose it explains, so GitHub renders it too and there
  # is no exported image to go stale.
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format
  - pymdownx.tabbed:
      alternate_style: true
  - pymdownx.tasklist:
      custom_checkbox: true

plugins:
  # The built-in search index, told where a Zoomies identifier stops being one
  # word: the default separator does not split on a dot or a hyphen, so
  # `scheduler.scale_up_delay` and `zoomies-linux-x64` were each a single term
  # nobody would type in full.
  - search:
      separator: '[\s\-,:!=\[\]()"/]+|(?!\b)(?=[A-Z][a-z])|\.(?!\d)|&[lg]t;'

# Build-time SEO metadata: a real last-edited date per page for the sitemap and
# the sharing tags, and llms.txt generated from the navigation. It is a hook
# rather than a plugin so the docs build keeps to its pinned dependencies.
hooks:
  - hooks/seo.py
  # The header's latest release, stars and forks, resolved once per build and
  # rendered by overrides/partials/source.html. Material would otherwise fetch
  # them in the browser and cache them in the tab for as long as it lives.
  - hooks/source.py
  # Lazy, sized images: the colour scheme a reader is not using is never
  # downloaded, and a page does not reflow as its screenshots arrive.
  - hooks/images.py
  - hooks/showcase.py

extra:
  field_guides:
    - source: what-are-self-hosted-runners.md
      category: Getting started
      card_title: Start with a runner. Build up to a fleet.
    - source: runners-without-kubernetes.md
      category: Architecture
      card_title: All the runners. None of the Kubernetes.
    - source: home-lab.md
      category: Home lab
      card_title: Good hardware deserves another lap.
    - source: queued-job.md
      category: Operations
      card_title: A job is waiting. Find out why.
    - source: persistent-caches.md
      category: Operations
      card_title: Disposable runners. Useful memories.
    - source: migration.md
      category: Getting started
      card_title: A smaller leap than you think.
    - source: ephemeral-runners.md
      category: Architecture
      card_title: A fresh start for every job.
    - source: runner-autoscaling.md
      category: Architecture
      card_title: A little more room to run.
    - source: should-i-self-host.md
      category: Getting started
      card_title: Your hardware. Your call.
    - source: docker.md
      category: Architecture
      card_title: Put a runner in its place.
    - source: many-repositories.md
      category: Operations
      card_title: More repositories. One happy pack.
    - source: costs.md
      category: Getting started
      card_title: Count more than the minutes.
  # Who builds Zoomies. overrides/partials/copyright.html prints this in the
  # footer of every page, beside the licence; the product's own footer says the
  # same thing from web/src/lib/links.ts, so a fork renames it in two places
  # rather than everywhere.
  developer:
    name: EyUp.io
    url: https://eyup.io
  social:
    - icon: fontawesome/brands/github
      link: https://github.com/eyupio/zoomies
      name: Zoomies on GitHub
  generator: false

# Keep the learning path separate from operating tasks and exact reference.
# A reader can find a first job without knowing a feature name, while an
# operator can go directly to a setting, command or API route.
nav:
  - Home: index.md
  - Documentation:
      - Overview: start-here.md
      - Get started:
          - Understand the basics: fundamentals.md
          - Run your first job: quickstart.md
          - Docker Compose: compose.md
          - Deploying on a PaaS: paas.md
          - Deploying on InstaPods: instapods.md
          - One-click deployment: marketplace.md
      - Run your fleet:
          - Web UI tour: ui.md
          - Hosts and pools: hosts-and-pools.md
          - Migrating repositories: migration.md
          - Backup and restore: backup-and-restore.md
          - Upgrading: upgrading.md
          - Two-step verification: two-step.md
          - Public view: public-view.md
          - Host health and tuning: host-health.md
          - Troubleshooting: troubleshooting.md
          - A job stuck in the queue: queued-job.md
      - Scale and tune:
          - Advanced operations: advanced.md
          - Size classes and automatic pools: auto-pools.md
          - Persistent caches: persistent-caches.md
          - Elastic CPU zoomies: elastic-cpu.md
          - Elastic memory: elastic-memory.md
          - Private hosts with Tailcat: private-hosts.md
          - Proxmox VE: proxmox.md
      - Assistants and repository checks:
          - MCP for your AI assistant: mcp.md
          - Eli conversations and PR repairs: eli.md
          - Kennel Club: kennel-club.md
          - Connect Claude: connect-claude.md
          - AI Context for assistants: ai-context.md
      - Reference:
          - Configuration: configuration.md
          - Command line: cli.md
          - API: api-surface.md
          - Architecture: architecture.md
          - Naming and platforms: naming.md
          - Security: security.md
          - Problem codes: problem-codes.md
          - Metrics: metrics.md
          - Runner startup stability: runner-startup-stability.md
          - Runtime compatibility: runtime-compatibility.md
          - Recovering a published image: development/image-recovery.md
          - Provider contract: providers.md
          - Automation contract: automation.md
          - Capacity-demand receiver: capacity-demand-receiver.md
          - Dependencies: dependencies.md
          - UI guidelines: ui-guidelines.md
  - Field guide: guides/index.md
  - Choosing Zoomies:
      - What are self-hosted runners?: what-are-self-hosted-runners.md
      - Should you self-host?: should-i-self-host.md
      - What it costs: costs.md
      - FAQ: faq.md
      - Many repositories: many-repositories.md
      - Runners in your home lab: home-lab.md
      - Runners in Docker: docker.md
      - Runners without Kubernetes: runners-without-kubernetes.md
      - Ephemeral runners: ephemeral-runners.md
      - Autoscaling runners: runner-autoscaling.md
  - Compare:
      - Choose your setup: alternatives/index.md
      - Compared with ARC: actions-runner-controller.md
      - Compared with GARM: alternatives/garm.md
      - Compared with the AWS Terraform module: alternatives/terraform-aws-github-runner.md
      - Compared with TestFlows Hetzner runners: alternatives/testflows-hetzner-runners.md
      - Compared with Cirun: alternatives/cirun.md
      - Compared with runscaler: alternatives/runscaler.md
      - Compared with gharp: alternatives/gharp.md
      - Compared with runner services: hosted-runner-services.md
      - GitHub Actions alternatives: github-actions-alternatives.md
  - About:
      - Brand: brand.md
      - Privacy: privacy.md
      - Terms: terms.md
# The brand pack's own guide is published because docs/brand.md links to it, but
# it is not a section of the site's navigation.
not_in_nav: |
  brand/BRANDING_GUIDE.md

# docs/agents/ is guidance for coding agents working in the repository, not a
# page for the people reading the site.
exclude_docs: |
  agents/

# A link in the docs that points nowhere is a broken promise, so a broken one
# fails the build rather than shipping.
strict: true
validation:
  links:
    absolute_links: ignore
    unrecognized_links: warn
    # A heading that gets reworded silently breaks every deep link into it, and
    # a link that lands at the top of a long page looks like it worked.
    anchors: warn