{"schemaVersion":1,"title":"Work with coding agents","url":"https://appgram.github.io/docsy/guides/tutorials/coding-agents","markdownUrl":"https://appgram.github.io/docsy/format-md/guides/tutorials/coding-agents","jsonUrl":"https://appgram.github.io/docsy/agent/pages/guides/tutorials/coding-agents.json","version":"current","locale":"en","markdown":"# Work with coding agents\n\nRead Markdown exports, guide your coding agent with project instructions, and validate documentation changes.\n\nWritten by: [nedimf](https://github.com/nedimf), [AppGram](https://appgram.dev)\n\nDocsy is documentation built for humans and coding agents. Your team gets a searchable portal with guides, API reference, and SDK documentation. Your coding agent can read the same content as Markdown and work directly with the files that build the site.\n\n## Give an agent documentation to read\n\nFor structured retrieval, use the JSON corpus, per-page JSON exports, and optional runtime query endpoint described in the [search and agent API guide](../search-and-agents). `/llms.txt` and `/llms-full.txt` provide discovery and combined Markdown. Static hosts support exports; live queries require the Node or Bun server.\n\nOpen an authored article, API section, or SDK page and use the header's **Markdown** menu to view its export. Adding `?format=md` to that page's URL opens a Markdown view in the browser.\n\nFor an agent that fetches URLs directly, use the `/format-md/...` endpoint. With a site mounted at `/docs`, an article at `/docs/guides/getting-started` has this export:\n\n```bash\ncurl https://docs.example.com/docs/format-md/guides/getting-started\n```\n\nThis Docsy portal uses `/docsy` as its mount path. For its configuration guide, the export path is `/docsy/format-md/guides/tutorials/yaml-configuration`.\n\nAuthored article exports include the title, description, and Markdown body. API exports include endpoint descriptions, parameters, request examples, and available response examples. SDK exports include symbols, signatures, and available examples.\n\nAn agent can use those exports as context when implementing an integration or answering a documentation question. In locked mode, exports follow the same access rules as their documentation pages; the agent needs access through your configured authentication setup.\n\n## Give an agent a project to maintain\n\nGenerate a project with the Docsy CLI, then open its repository with your coding agent. Generated projects include two instruction files:\n\n* `AGENTS.md` describes the configuration boundary, interface conventions, and validation commands.\n* `DOCSY_BRIEF.md` records the project name, mount path, ingestion source, and access mode, along with a customization brief.\n\nThe agent edits the same files that a developer would:\n\n| Task | Files to work with |\n| --- | --- |\n| Write guides and tutorials | Markdown under `content/`, registered in `docsy.config.yaml` |\n| Configure branding, navigation, or permissions | `docsy.config.yaml` |\n| Update API and SDK input | The configured source under `sources/` or its upstream metadata |\n| Change layout or interaction | Astro components and CSS under `src/` |\n\nCommit the changes and review them through your existing Git workflow. Your team chooses which coding agent to use and when to publish.\n\n## Ask for a concrete documentation change\n\nGive the agent a source, an outcome, and the behavior it should preserve. For example:\n\n```text\nRead AGENTS.md, DOCSY_BRIEF.md, and docsy.config.yaml.\nUse sources/openapi.json to write a first-request guide in content/.\nRegister it under content.articles and add it to the sidebar.\nUse the API source for endpoint names, parameters, and examples.\nFlag missing authentication or onboarding details for review.\nPreserve the existing interface and access rules.\nRun npm run validate and npm run build, then summarize the diff.\n```\n\nFor a visual change, describe the branding and layout you want. The agent can change theme tokens in YAML or edit the Astro interface when the request calls for it.\n\n## Maintain docs after an API change\n\nEnable `maintenance.enabled` in YAML to use the included GitHub workflow. When watched API or code sources change on the default branch, Docsy prepares an impact report and asks the agent to update affected articles, correct examples, and explain migrations. A fresh job validates the patch and production build before a separate job opens a draft PR.\n\nYou can also inspect or run the loop locally:\n\n```bash\nnpm run maintain -- plan --base HEAD~1\nnpm run maintain -- run --base HEAD~1\n```\n\nThe **Documentation maintenance** guide covers YAML settings, the GitHub API secret, allowed edit paths, draft PRs, and source comparison boundaries. Docsy regenerates the reference pages from the configured ingestion input during the build.\n\n## Validate and review\n\nThe agent can run the same commands as your team:\n\n```bash\nnpm run validate\nnpm run build\n```\n\nValidation checks the YAML schema and Astro types. The production build loads the configured sources and renders the routes, search data, and Markdown exports. Review factual accuracy, example behavior, and the final appearance alongside those checks.\n\nUse `npm run preview` to inspect the staged result. When it is ready, publish through your chosen deployment workflow.\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/tutorials/coding-agents.md"}