{"schemaVersion":1,"title":"Get started with Docsy","url":"https://appgram.github.io/docsy/guides/getting-started","markdownUrl":"https://appgram.github.io/docsy/format-md/guides/getting-started","jsonUrl":"https://appgram.github.io/docsy/agent/pages/guides/getting-started.json","version":"current","locale":"en","markdown":"# Get started with Docsy\n\nBuild documentation for humans and coding agents, generate a project, and understand its editable source.\n\nWritten by: [nedimf](https://github.com/nedimf), [AppGram](https://appgram.dev)\n\nDocsy by AppGram is documentation you own: YAML configuration, native SDK and OpenAPI imports, editable source, and self-hosting. People read searchable guides and reference pages; coding agents read Markdown/JSON and help maintain the same repository.\n\n> Your source and hosting\n>\n> Docsy is source-available under ELv2. Use the versioned CLI, a local tarball or the public source repository. No hosted control plane is required. Generation and local preview do not deploy anything.\n\n## Run this documentation portal\n\nClone the repository and start the development server:\n\n```bash\ngit clone https://github.com/AppGram/docsy.git\ncd docsy\nnpm ci\nnpm run dev\n```\n\nOpen `http://localhost:4321/docsy/`. Changes to `docsy.config.yaml`, Markdown articles, components, and styles are reflected locally.\n\n## Generate a new project\n\nCreate your own site with the versioned npm CLI:\n\n```bash\nnpm exec --package @appgram/docsy@0.4.2 -- create-docsy my-docs --yes --ci\ncd my-docs\nnpm run dev\n```\n\nFor local CLI development, run `npm run release:pack` in the source checkout and copy the tarball-based command it prints. Packing and testing never publish anything; registry publication has its own manual workflow and approval gates. Generated documentation projects remain `private: true` by default so they are not accidentally published as npm packages.\n\nThe source checkout also includes the generator directly:\n\n```bash\nnpm run create -- ../acme-docs \\\n  --name \"Acme API\" \\\n  --base /docs\n```\n\nThe CLI can start from authored Markdown alone. Add `--openapi` and `--api-base` when the project should also generate an API reference:\n\n```bash\nnpm run create -- ../acme-docs \\\n  --name \"Acme API\" \\\n  --openapi https://api.example.com/openapi.json \\\n  --api-base https://api.example.com \\\n  --base /docs\n```\n\nThe generated directory is an independent Astro project. It includes a starter guide, the default interface, validated YAML configuration, deployment files, and an AI customization brief.\n\nAdd `--ci` for validation and a downloadable static preview artifact. Add `--deploy github-pages --repo https://github.com/OWNER/REPOSITORY` for a gated Pages workflow and correctly derived origin/base path. Nothing goes live until you explicitly enable Pages and set the repository variable `DOCSY_ENABLE_PAGES=true`. Keep that switch off during private development. For runtime permissions or live queries, use Node/Bun self-hosting instead.\n\nAfter creation, run `npm run docsy -- doctor`, add your content, then `npm run build` and `npm run preview`. The CLI prints the local path and, when selected, the expected future Pages URL. The **GitHub Pages** guide explains the final opt-in steps; generation itself never pushes or publishes.\n\nEvery generated project includes `DEPLOYING.md`: content setup, local preview, source storage, explicit publication, and verification of the actual live URL. Use it as the handoff checklist, keeping the publishing step disabled while the project is private.\n\nKeep `.docsy/template.json` in Git. It records the template version and original file hashes so future fixes can be compared safely. See **Upgrade a customized site**; the comparison command does not overwrite your changes.\n\n## Bring your coding agent\n\nOpen the generated repository with your coding agent and give it `AGENTS.md`, `DOCSY_BRIEF.md`, and `docsy.config.yaml` as context. Describe the content or behavior you want to change, then review the resulting diff and build.\n\nFor agents consuming published documentation, the portal's Markdown menu links to the current page's export. Direct `/format-md/...` URLs let HTTP clients fetch authored articles and generated API or SDK reference as Markdown.\n\nThe **Coding agents** guide walks through reading published docs, writing articles, and maintaining documentation after an API change.\n\n## Understand the ownership boundary\n\nDocsy has three deliberately separate layers:\n\n| Layer | Owns |\n| --- | --- |\n| `docsy.config.yaml` | Product identity, article registration, navigation, visual tokens, ingestion, and access policy |\n| `content/` and `sources/` | Markdown articles and build-time API or SDK metadata |\n| `src/` | The editable Astro interface and CSS |\n\nUse YAML for repeatable site configuration. Use Markdown for documentation prose. Edit Astro and CSS when the interface itself needs to change.\n\n## Validate and build\n\nBefore deploying a project, run:\n\n```bash\nnpm run validate\nnpm run build\n```\n\nUse Node 22.22 or newer to develop and build. Open mode with `agent.query: false` produces a static Astro build. Locked mode or `agent.query: true` produces a standalone server so authorization or live queries can run for every request. Start the build with Node using `npm start`, or use the tested Bun production runtime with `npm run start:bun` (Bun 1.3.5 or newer).\n\n## Choose the next guide\n\n* Configure the portal through `docsy.config.yaml` in **YAML configuration**.\n* Read and maintain documentation with an agent in **Coding agents**.\n* Add first-class Markdown pages in **Authored articles**.\n* Generate reference pages in **OpenAPI ingestion** and **SDK adapters**.\n* Publish the static portal in **GitHub Pages** or run it yourself using **Self-hosting**.\n\n","contentLocale":"en","isFallback":false,"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/getting-started.md"}