{"schemaVersion":1,"title":"Customize the default UI","url":"https://appgram.github.io/docsy/versions/current/es/guides/customization/default-ui","markdownUrl":"https://appgram.github.io/docsy/format-md/versions/current/es/guides/customization/default-ui","jsonUrl":"https://appgram.github.io/docsy/agent/pages/versions/current/es/guides/customization/default-ui.json","version":"current","locale":"es","markdown":"# Customize the default UI\n\nChange branding and theme tokens in YAML, then edit the source-owned Astro interface when needed.\n\nWritten by: [nedimf](https://github.com/nedimf), [AppGram](https://appgram.dev)\n\nEvery generated project starts with Docsy's default interface: responsive sidebar navigation with remembered scroll position, search, Markdown export controls, content cards, API and SDK layouts, and an on-page heading rail. The interface is normal Astro source in the generated repository.\n\n## Configure branding in YAML\n\nRoutine brand changes belong in `docsy.config.yaml`:\n\n```yaml\nsite:\n  name: Acme\n  docsLabel: docs\n  title: Acme Documentation\n  description: Build with the Acme platform.\n  origin: https://docs.example.com\n  basePath: /\n  logo: assets/acme-mark.svg\n  favicon: assets/acme-mark.svg\n  githubUrl: https://github.com/acme/platform\n\nheader:\n  searchLabel: Search documentation\n  searchPlaceholder: Search guides and API reference\n  llmLabel: Markdown\n  cta:\n    label: Open dashboard\n    href: https://app.example.com\n\nfooter:\n  prefix: Docsy provided by\n  label: Acme\n  href: https://example.com\n```\n\nPaths under `public/` are referenced without the `public` segment. Docsy adds `site.basePath` to local asset and documentation links.\n\nThe footer is optional. Remove the entire `footer` block to render no attribution footer. ELv2 does not require visible Docsy or AppGram branding on your published documentation; its notice requirement applies to the license and copyright notices distributed with the software.\n\n## Choose the eyebrow icon\n\nThe small marker beside each page's eyebrow uses the Docsy SVG by default. Choose your own SVG or transparent image in YAML:\n\n```yaml\neyebrow:\n  icon: assets/acme-mark.svg\n  size: 14\n```\n\nPut local icons under `public/`; Docsy adds `site.basePath` automatically. Icons render as monochrome masks in the eyebrow's text color, so they follow both light and dark palettes. `size` is in pixels, from 8 to 32.\n\nSet `icon: triangle` for the original triangle, or `icon: none` to hide the marker. This global setting applies to every page; `home.eyebrow` and each article's `eyebrow` still control the text.\n\n## Choose grid or list for articles\n\nSet the overview's authored-article layout in `docsy.config.yaml`:\n\n```yaml\nhome:\n  articleLayout: list # grid or list; defaults to grid\n```\n\n`grid` shows two columns of article cards on wide screens and one on narrow screens. `list` shows compact full-width rows, with category labels alongside the title and description on wide screens and above them on narrow screens. Both layouts use each article's YAML title, description, and eyebrow, and follow the active theme colors. This setting does not change the article reading page or API reference cards. Invalid layout values stop the build.\n\n## Add an optional overview image\n\nThe overview has no image by default. To display your own, put it under `public/` and add `home.image` in YAML:\n\n```yaml\nhome:\n  # Keep your existing title, description, and actions.\n  image:\n    src: assets/overview.png\n    alt: A preview of the Acme platform\n    width: 1200\n    height: 800\n```\n\n`width` and `height` are optional. Remove the `image` block to return to the full-width text layout. Images retain their original colors in light and dark themes.\n\n## Use the default visual tokens\n\nSet only the mode to use Docsy's defaults:\n\n```yaml\ntheme:\n  mode: light\n```\n\nThe header includes a light/dark toggle. `theme.mode` is the first-visit default, and the visitor's selection is saved locally for later pages and sessions.\n\nSearch uses the same palette: its surface, text, result badges, selection highlight, borders, and keyboard hints follow the active theme and your YAML overrides.\n\n## Syntax highlighting and language logos\n\nSDK declarations and examples, OpenAPI requests and responses, and Markdown fences all use the same build-time syntax renderer. Code groups, tabs, callouts, and included snippets use it too. Highlighting is included in the generated HTML: no highlighter script, CDN, icon font, or external font request is needed in the browser.\n\nChoose the two bundled Shiki palettes in YAML. Switching the portal theme also switches token colors without reloading:\n\n```yaml\ntheme:\n  code:\n    lightTheme: github-light\n    darkTheme: github-dark-high-contrast\n```\n\nUse any bundled [Shiki theme](https://shiki.style/themes). An unknown theme name fails configuration validation. The code-card surface follows Docsy's light/dark styling; these settings control syntax token colors.\n\nPut the language after a Markdown fence, such as `typescript`, `scala`, `python`, `yaml`, or `json`. Common aliases such as `ts`, `js`, `sh`, `objc`, and `vbnet` work. A missing/unknown language stays safely escaped plain text instead of guessing a grammar. Blocks over 100,000 characters also use plain text to bound highlighting work. Inline code labels remain inline code, not standalone syntax-highlighted cards.\n\nEach code header uses its language logo rather than an uppercase name. The language name remains available as an accessible label and tooltip. Native SDK badges respect the SDK's YAML `icon` and optional `iconDark` overrides; other supported logos are served locally. Languages/formats without a logo use a neutral code or terminal symbol. F# examples retain the F# mark even where DocFX emits a C# declaration with a C# mark.\n\nThe shared renderer is `src/lib/code-renderer.ts`, language aliases and default logo mappings are in `src/lib/code-languages.ts`, and card/token styling is in `src/styles/code-blocks.css`. Copy buttons copy plain code, never syntax markup.\n\nOverride individual tokens when the product needs them:\n\n```yaml\ntheme:\n  mode: dark\n  colors:\n    ink: \"#f5f5f5\"\n    muted: \"#a3a3a3\"\n    line: \"#262626\"\n    paper: \"#000000\"\n    accent: \"#ffffff\"\n    panel: \"#050505\"\n  fonts:\n    display: '\"Aptos Display\", \"SF Pro Display\", \"Helvetica Neue\", sans-serif'\n    body: '\"Aptos\", \"SF Pro Text\", \"Helvetica Neue\", sans-serif'\n    mono: 'ui-monospace, \"SF Mono\", Menlo, monospace'\n```\n\n`theme.colors` customizes the configured default mode. Use `darkColors` when the default is light, or `lightColors` when the default is dark, to customize the alternate palette:\n\n```yaml\ntheme:\n  mode: light\n  colors:\n    paper: \"#ffffff\"\n    ink: \"#111116\"\n    accent: \"#5188ff\"\n  darkColors:\n    paper: \"#000000\"\n    ink: \"#f5f5f5\"\n    accent: \"#ffffff\"\n```\n\nDocsy uses system font stacks by default. It does not require a hosted font service or typographic tracking.\n\n## Copy links to sections\n\nSection headings reveal a small `#` button on hover or keyboard focus. Click it to copy the current page's full URL with that section's existing fragment, including the documentation version and language path. A checkmark confirms the copy without moving the reader or changing browser history. Touch devices keep the buttons visible.\n\nThis works for anchored Markdown/MDX headings, API endpoint titles, SDK categories and SDK symbols. It does not rename existing anchors or add button labels to exported Markdown/search content. Disable the controls in YAML if you prefer:\n\n```yaml\nreader:\n  headingLinks: false\n```\n\nThe default is `true`. Clipboard restrictions fall back to the browser's copy command; if both are denied, the control reports failure instead of claiming success.\n\n## Edit the source-owned interface\n\nYAML is not a page-builder language. When the layout or interaction should change, edit the source directly:\n\n| Responsibility | Location |\n| --- | --- |\n| Global documentation shell | `src/layouts/DocsLayout.astro` |\n| Guide cards on the overview | `src/components/docs/ArticleCard.astro` |\n| Authored article presentation | `src/components/docs/ArticlePage.astro` |\n| API and SDK presentation | `src/components/docs/` |\n| Landing page | `src/pages/index.astro` |\n| Base design primitives | `src/styles/docsy.css` |\n| Dark-mode adjustments | `src/styles/docsy-dark.css` |\n\nThose files are intentionally copied into generated projects. There is no upstream renderer that replaces local changes during deployment.\n\n## Give an AI a safe customization brief\n\nGenerated projects include `AGENTS.md` and `DOCSY_BRIEF.md`. Use them to describe the desired visual result while preserving the configuration boundary:\n\n```text\nRead AGENTS.md, DOCSY_BRIEF.md, and docsy.config.yaml.\nKeep product copy, article registration, navigation, colors, fonts,\ningestion, and access rules in YAML. Change Astro and CSS only when\nthe interface itself must change. Preserve responsive behavior,\nsearch, Markdown export, and the permission gate.\n```\n\nValidate the result at narrow and wide viewport sizes, then run `npm run validate` and `npm run build`.\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/customization/default-ui.md"}