{"version":1,"pages":[{"id":"chapter-3","title":"Introduction","routePath":"/","sourcePath":"README.md","text":"Introduction Welcome to docia — a static documentation generator that prioritizes readability, search engines, and AI assistants. What is docia? docia turns your Markdown files into a fast, navigable documentation site. It uses a simple SUMMARY.md file to define your document structure, then generates static HTML with: Clean navigation sidebar Table of contents for each page Previous/next page links Full-text search index SEO metadata (sitemap, robots.txt, JSON-LD) LLM-friendly exports (llms.txt + per-page markdown) Who is it for? Product teams — User guides, API documentation, changelogs Engineering teams — Internal handbooks, runbooks, architecture docs Open source projects — README replacements, contribution guides Getting Started New to docia? Start here: Installation — Get docia running Quick Start — Build your first docs site Project Structure — Understand the file layout Build this guide From the repository root: Or generate static output:"},{"id":"chapter-5","title":"Installation","routePath":"/installation/","sourcePath":"installation.md","text":"Installation Option 1: Standalone Executable (Recommended) Download and install Docia without any dependencies. Works on macOS and Linux. One-line installer This script automatically detects your platform and architecture, downloads the latest release, and installs it to /usr/local/bin/. Manual installation If you prefer to install manually, download the appropriate binary from GitHub Releases: macOS (Apple Silicon) macOS (Intel) Linux (x64) Linux (ARM64) Windows (x64 and ARM64) Windows users should download the .exe for their architecture from GitHub Releases and add it to their PATH manually. Option 2: npm (requires Bun) If you prefer to use npm/Bun: Prerequisites: Bun 1.4+ Verify installation Create your first docs project Your documentation site will be available at http://localhost:3000."},{"id":"chapter-6","title":"Quick Start","routePath":"/quick-start/","sourcePath":"quick-start.md","text":"Quick Start This section walks through the default workflow. Minimal project example docia automatically applies syntax highlighting to fenced code blocks. docia.config.ts: book/SUMMARY.md: 1) Initialize This creates: docia.config.ts book/SUMMARY.md starter chapters public/favicon.svg .gitignore 2) Run local dev dev performs an initial build, serves static output, and refreshes the browser when source, configuration, or public asset files change. Draft pages are available in development previews. 3) Build production output By default output goes to dist/. 4) Validate before deploy This checks missing files, broken markdown links, duplicate output routes, and orphaned markdown files."},{"id":"chapter-7","title":"Project Structure","routePath":"/project-structure/","sourcePath":"project-structure.md","text":"Project Structure Default layout: Key files book/SUMMARY.md: chapter order + sidebar hierarchy book/**/*.md: chapter source files public/: assets copied to output; JPEG, PNG, and WebP images are optimized by default dist/: generated site (gitignored in most repos) Chapter routing With pretty URLs enabled (default): README.md -> / guides/setup.md -> /guides/setup/ Use these route paths for reliable in-doc links."},{"id":"chapter-9","title":"Configuration","routePath":"/configuration/","sourcePath":"configuration.md","text":"Configuration docia reads configuration from docia.config.ts by default. Example: Core options srcDir: source markdown root outDir: generated static output publicDir: static asset input directory basePath: URL prefix for subpath hosting (for example /docs) prettyUrls: /chapter/ style routes vs .html routes Site metadata site.title: global site title site.description: default page description site.language: HTML lang site.url: canonical base URL used by SEO artifacts site.socials.github: optional GitHub link shown in sidebar site.socials.x: optional X link shown in sidebar site.githubEditBaseUrl: optional full GitHub edit URL prefix for source files site.githubEditBranch: branch used when deriving edit links from site.socials.github site.githubEditPath: repo path to docs source (defaults to srcDir) site.ogImage: default social preview image Theme options theme.logo: optional logo shown beside the site title theme.favicon: favicon path, or an empty string to omit it theme.accentColor: optional CSS color used for links and controls theme.customCss: additional local or external stylesheets loaded after docia's styles theme.colorMode: initial system, light, or dark appearance; readers can override it Markdown options docia uses Bun's markdown parser and supports Bun parser options via markdown. Useful defaults are already enabled, including headings IDs and common GFM features. Image options Raster images in publicDir are optimized during production and development builds with Bun.Image. URLs and file formats stay unchanged, and docia keeps the original whenever re-encoding would make a file larger. SVG, GIF, AVIF, HEIC, and other files are copied without transformation. images.optimize: enable build-time optimization (default true) images.jpegQuality: JPEG quality from 1 to 100 (default 82) images.webpQuality: WebP quality from 1 to 100 (default 82) images.pngCompressionLevel: lossless PNG compression from 0 to 9 (default 9) images.maxPixels: maximum decoded pixel count per image (default 64_000_000) Unknown configuration keys fail with a descriptive error so misspelled options cannot be silently ignored."},{"id":"chapter-10","title":"Page Front Matter","routePath":"/page-frontmatter/","sourcePath":"page-frontmatter.md","text":"Page Front Matter Add optional YAML front matter at the beginning of a chapter to control its page metadata and URL. The title in SUMMARY.md remains the sidebar label. Fields title: browser, search, Open Graph, and page metadata title description: page-specific search and social description slug: stable URL path independent of the Markdown filename ogImage: page-specific social preview image draft: omit the page and its nested navigation from production builds noindex: keep the page available but omit it from sitemaps and llms.txt redirectFrom: old paths that should redirect to the page Draft pages are included by docia dev for previewing and marked noindex. A production docia build omits them. docia check reports links from published pages to drafts. Redirect paths and slugs must be URL paths without a protocol, query string, hash, or .html extension. Output formatting still follows prettyUrls."},{"id":"chapter-11","title":"CLI Reference","routePath":"/cli-reference/","sourcePath":"cli-reference.md","text":"CLI Reference init Create a new project scaffold. build Generate static site output. dev Build + serve with watch mode. serve Serve generated static output. check Validate docs graph and references. new Create a new chapter file."},{"id":"chapter-12","title":"Navigation","routePath":"/summary-syntax/","sourcePath":"summary-syntax.md","text":"The SUMMARY.md file controls the navigation structure of your documentation site. It uses a simple markdown list format to define pages and sections. Basic Structure Use a dash followed by [title](path) to define pages: Sections and Nesting Create sections by using plain text without links. Indent child pages with two spaces below the section title. Sections group related pages together in the sidebar navigation. The text becomes a section header that cannot be clicked. External Links Link to external resources using full URLs: External links open in a new tab and display a small indicator icon. Best Practices Use clear, descriptive section names that reflect the content Group related pages under common sections Keep the structure shallow, ideally 2-3 levels maximum Use title case for section headers Place the most important pages at the top level Complete Example This structure creates a clean navigation with Introduction and Contributing at the top level, plus two expandable sections for Getting Started and API Reference."},{"id":"chapter-14","title":"LLM Features","routePath":"/llm-features/","sourcePath":"llm-features.md","text":"LLM Features docia includes first-class LLM support in static output. /llms.txt On build, docia emits llms.txt at site root. It follows the llmstxt.org structure: H1 site title optional blockquote summary ## Docs section linking important markdown pages ## Optional section for extra context links Per-page markdown output For each page, docia emits a markdown mirror next to generated HTML: /index.html + /index.html.md /guides/setup/index.html + /guides/setup/index.html.md This makes it easy for assistants and IDE tools to fetch clean markdown context. Page actions menu Every page includes a markdown action control: Copy markdown View markdown Open in ChatGPT Open in Claude These are client-side helpers; static output remains usable without JavaScript. Discovery links Every generated HTML page includes the standard discovery relations recommended by llms.txt v2: rel=\"alternate\" type=\"text/markdown\" points to the page's Markdown mirror rel=\"describedby\" points to the site's llms.txt The existing docia-markdown-url and docia-llms-url metadata remains available for docia's client-side actions."},{"id":"chapter-15","title":"Deployment","routePath":"/deployment/","sourcePath":"deployment.md","text":"Deployment docia outputs static files, so you can deploy to any static host. Standard release flow Upload dist/ to your hosting provider. During the build, docia uses Bun.Image to optimize JPEG, PNG, and WebP files from publicDir while preserving their paths. The build summary reports how many images changed and the total bytes saved. Files to verify after build chapter pages (index.html files) robots.txt sitemap.xml llms.txt search-index-[hash].json 404.html Redirects declared with page front matter are emitted as small static HTML files. They use a canonical link, an HTML refresh fallback, and JavaScript navigation, so they work on generic static hosts without provider-specific configuration. Base path deployments If your site is hosted under a subpath (for example /docs), set: Then rebuild so generated links and metadata use the correct prefix. Release integrity Official release archives are published with SHA256SUMS. The one-line installer verifies the download before installing it."},{"id":"chapter-16","title":"1.0 Compatibility","routePath":"/compatibility/","sourcePath":"compatibility.md","text":"1.0 Compatibility Starting with 1.0.0, docia follows Semantic Versioning for its public configuration API, command names and flags, generated chapter URLs, and documented Markdown behavior. Runtime support Standalone executables: macOS, Linux, and Windows on x64 and ARM64 where release assets are listed Package installation: Bun 1.4 or newer Configuration: TypeScript, JavaScript, and ES module config files Public TypeScript API Use DociaConfig, DociaUserConfig, and defineConfig from docia. The former GoodDocsConfig and GoodDocsUserConfig names remain as deprecated aliases for migration. URL stability Use page slug front matter when a URL must remain independent from its source filename. When a published URL changes, add it to redirectFrom in the destination page before deploying. Release candidates Release candidates may contain final compatibility adjustments before 1.0.0. Test the candidate against a copy of an existing documentation project and report regressions through GitHub Issues."}]}