{"schemaVersion":1,"title":"Configure Docsy with YAML","url":"https://appgram.github.io/docsy/versions/current/es/guides/tutorials/yaml-configuration","markdownUrl":"https://appgram.github.io/docsy/format-md/versions/current/es/guides/tutorials/yaml-configuration","jsonUrl":"https://appgram.github.io/docsy/agent/pages/versions/current/es/guides/tutorials/yaml-configuration.json","version":"current","locale":"es","markdown":"# Configure Docsy with YAML\n\nUnderstand how docsy.config.yaml controls product copy, navigation, visual tokens, content, and access.\n\nWritten by: [nedimf](https://github.com/nedimf), [AppGram](https://appgram.dev)\n\nDocsy treats `docsy.config.yaml` as the durable source of truth for a documentation site. Change YAML when you are changing the product, content wiring, navigation, theme, ingestion sources, or access policy. Change Astro and CSS only when you are changing interface behavior or layout.\n\n## How configuration becomes a site\n\nEvery development server and production build follows the same path:\n\n1. Read `docsy.config.yaml`, or the file named by `DOCSY_CONFIG`.\n2. Expand environment placeholders such as `${DOCSY_ORIGIN:-http://localhost:4321}`.\n3. Validate the result against Docsy's schema.\n4. Load authored Markdown, OpenAPI, and SDK sources.\n5. Build routes, navigation, search, Markdown exports, and access rules.\n\nAn invalid value stops the build with its exact YAML path. Run this before committing a change:\n\n```bash\nnpm run validate\n```\n\n## The top-level sections\n\n| Section | Responsibility |\n| --- | --- |\n| `site` | Product identity, canonical origin, mount path, logo, and metadata |\n| `header` | Search copy, Markdown label, and an optional call to action |\n| `eyebrow` | Page marker: custom SVG/image, original triangle, or none, plus icon size |\n| `theme` | Light or dark mode, colors, and system font stacks |\n| `home` | Landing-page copy, actions, optional image, and `articleLayout` (`grid` or `list`) |\n| `content.articles` | Authored Markdown pages rendered under `/guides/` |\n| `authors` | Reusable human, organization and coding-agent profiles referenced by articles |\n| `reader` | Heading links, byline visibility, default/unknown author pictures, and optional edit/report links |\n| `content.components` / `content.snippets` | Enabled rich components and named reusable Markdown |\n| `content.media` | Enable the fullscreen image/video viewer, or switch images/videos off independently |\n| `versions` / `localization` | Documentation contexts, locale routing, fallbacks, and UI messages |\n| `search` | Full-text reader search and result limits |\n| `agent` | JSON/Markdown discovery and an optional runtime query API |\n| `validation` | API-contract/example checks and internal links/anchors |\n| `navigation` | Sidebar groups and links |\n| `ingestion` | OpenAPI and SDK metadata sources |\n| `access` | Open or locked mode, tiers, providers, and ordered rules |\n| `maintenance` | Watched source paths, editable Markdown, migration notes, and the coding agent's optional model |\n\nThe minimum useful configuration connects these responsibilities rather than duplicating them:\n\n```yaml\nsite:\n  name: Acme API\n  title: Acme API Documentation\n  description: Build against the Acme platform.\n  origin: ${DOCSY_ORIGIN:-http://localhost:4321}\n  basePath: /docs\n  logo: assets/acme-mark.svg\n\nhome:\n  title: Build with Acme.\n  description: Guides and reference documentation for the Acme API.\n  primaryAction:\n    label: Start building →\n    href: /guides/getting-started\n\ncontent:\n  articles:\n    - slug: getting-started\n      source: content/getting-started.md\n      title: Getting started\n      description: Make your first authenticated request.\n\nnavigation:\n  - title: Guides\n    items:\n      - title: Getting started\n        href: /guides/getting-started\n\naccess:\n  mode: open\n\ningestion:\n  sdks: []\n  openapi:\n    source: sources/openapi.yaml\n    apiBaseUrl: https://api.example.com\n    sections: []\n```\n\n## Paths and environment values\n\n`site.basePath` is the public mount point. With `/docs`, an article route such as `/guides/getting-started` is served at `/docs/guides/getting-started`. Keep navigation links relative to the documentation root; Docsy adds the mount path.\n\nUse environment interpolation for deployment-specific values:\n\n```yaml\nsite:\n  origin: ${DOCSY_ORIGIN:-http://localhost:4321}\n```\n\n`${NAME}` requires the variable. `${NAME:-fallback}` supplies a development default.\n\nTo maintain separate configurations without copying source code, select one at build time:\n\n```bash\nDOCSY_CONFIG=docsy.enterprise.yaml npm run build\n```\n\n## What YAML does not own\n\nYAML intentionally does not describe arbitrary layout. The generated Astro components and CSS remain in the repository for deeper changes. This split keeps routine configuration safe while preserving full source ownership.\n\nNext: [write authored documentation](../authored-articles).\n\n","contentLocale":"en","isFallback":true,"authorship":{"authors":[{"name":"nedimf","kind":"human","github":"nedimf","avatar":"/docsy/assets/authors/nedimf.png","role":"AppGram","id":"nedimf","url":"https://github.com/nedimf"},{"name":"AppGram","kind":"organization","github":"AppGram","url":"https://appgram.dev","avatar":"/docsy/assets/ag-logo.svg","id":"appgram"}],"contributors":[],"reviewedBy":[]},"editUrl":"https://github.com/AppGram/docsy/edit/main/content/tutorials/yaml-configuration.md"}