Get started
Your first site
What DeepDoc just created, how to read it, and which parts are yours to edit.
deepdoc generate writes three things into your repository. Knowing which is which tells you what is safe to edit and what gets overwritten.
your-project/
├── .deepdoc.yaml Your config. Yours to edit.
├── deepdoc-docs/ Generated Markdown, one file per page
│ ├── index.md
│ ├── getting-started.md
│ └── whats-changed.md Auto-written changelog
├── deepdoc-site/ The Next.js site. Build output, do not edit.
│ └── deepdoc.config.json Rewritten on every serve
└── .deepdoc/ Saved state. Commit this.
├── plan.json The page plan. Makes re-theming free.
├── ledger.json Which pages DeepDoc owns
└── generation_quality.json
What each one is for
deepdoc-docs/ is plain Markdown, one file per page. It is readable, diffable and reviewable in a pull request like any other file.
deepdoc-site/ is the site that renders it. Treat it as build output: DeepDoc owns every file in there and rewrites them on each run.
.deepdoc/ is the saved state, and it is the reason theming is free. plan.json holds the page structure, so changing colours or reordering the sidebar rebuilds the site from that file instead of re-reading your code.
Adding your own pages
Drop a Markdown file into deepdoc-docs/ and it is published. DeepDoc only deletes files it created, because it tracks its own output in ledger.json, so hand-written pages survive every regeneration.
echo "# Runbook" > deepdoc-docs/runbook.md
That page is now live at /runbook, but it will not appear in the sidebar. The sidebar comes from the plan, and the plan does not know about it. Add it:
site:
nav:
extra:
- { slug: runbook, title: "Runbook", section: "Guides" }
DeepDoc tells you when this applies to you:
2 page(s) are not in the sidebar: runbook, faq. Add them under site.nav.extra.
What gets overwritten
Safe to edit
.deepdoc.yaml, and any Markdown file you added to deepdoc-docs/ yourself. Neither is ever overwritten.
Overwritten every run
Everything in deepdoc-site/, and any page DeepDoc generated. Editing a generated page by hand is lost on the next run. Change the config or the source code instead.
Removed by deepdoc clean
Only files DeepDoc created, tracked against its own manifest. Your hand-written pages and chatbot_backend/ are preserved.