deepdoc 2.3.6__tar.gz → 3.1.0__tar.gz

{deepdoc-2.3.6 → deepdoc-3.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: deepdoc
-Version: 2.3.6
+Version: 3.1.0
 Summary: Auto-generate beautiful docs from any codebase
 Author: Pranav Kumar
 License: MIT
@@ -35,6 +35,11 @@ Requires-Dist: fastapi>=0.115; extra == "chatbot"
 Requires-Dist: uvicorn>=0.30; extra == "chatbot"
 Requires-Dist: httpx>=0.27; extra == "chatbot"
 Requires-Dist: fastembed>=0.3.0; extra == "chatbot"
+Provides-Extra: site
+Requires-Dist: mkdocs>=1.6; extra == "site"
+Requires-Dist: mkdocs-material>=9.5; extra == "site"
+Requires-Dist: pymdown-extensions>=10.0; extra == "site"
+Requires-Dist: mkdocs-swagger-ui-tag>=0.6; extra == "site"
 Dynamic: license-file
 
 # DeepDoc
@@ -57,7 +62,7 @@ Dynamic: license-file
 
 Auto-generate deep engineering documentation from real codebases using AI.
 
-DeepDoc scans your repo, builds a bucket-based documentation plan, generates rich MDX pages with Mermaid diagrams, and builds a local-first Fumadocs site with Orama search.
+DeepDoc scans your repo, builds a bucket-based documentation plan, generates rich Markdown pages with Mermaid diagrams, and builds a local-first MkDocs Material site with built-in search.
 
 ## Contents
 
@@ -82,11 +87,11 @@ DeepDoc scans your repo, builds a bucket-based documentation plan, generates ric
 - **Bucket-based documentation architecture** — system, feature, endpoint, integration, and database buckets instead of one-file-per-page noise.
 - **Multi-step AI planner** — classifies the repo, proposes buckets, then assigns files, symbols, artifacts, and dependencies into a final reader-first plan.
 - **Giant-file handling** — large files are decomposed into feature-aligned clusters so a single controller can feed multiple doc pages.
-- **MDX-safe generation** — generated pages are repaired and validated in Python before being written; deploy-time quality gates block failed, invalid, or stub pages before the Fumadocs build.
+- **Stable plain-Markdown generation** — generated pages are plain CommonMark (no MDX/JSX compile step, so a page can never fail to build); they are repaired and validated in Python before being written, and deploy-time quality gates block failed, invalid, or stub pages before the build.
 - **Evidence-first chatbot answers** — final code proof is hydrated from archived source snippets with exact file paths and line ranges, not just retrieval guesses.
 - **Incremental updates** — `deepdoc update` regenerates only stale or structurally affected docs against the last synced commit.
-- **OpenAPI-aware API docs** — auto-detects OpenAPI/Swagger specs and stages interactive `/api/*` pages in the generated site.
-- **Local-first Fumadocs site** — generates a `site/` Next.js app with Fumadocs UI, Mermaid rendering, and built-in search; `deepdoc deploy` exports a static site to any host.
+- **OpenAPI-aware API docs** — auto-detects OpenAPI/Swagger specs and renders an interactive Swagger UI page (`mkdocs-swagger-ui-tag`) in the generated site.
+- **Local-first MkDocs Material site** — generates a `site/mkdocs.yml` (Material theme, Mermaid, built-in search); `deepdoc deploy` runs `mkdocs build` and exports a static site to any host. Pure Python — no Node.js required.
 
 Works with Anthropic, OpenAI, Azure OpenAI, Google Gemini, Ollama, and any other LiteLLM-compatible provider. Parses Python, JavaScript/TypeScript, Go, PHP, and Vue.
 
@@ -129,7 +134,13 @@ pip install click litellm gitpython rich pyyaml jinja2
 pip install -e . --no-deps
 ```
 
-You will also need **Node 18+** on `PATH` when you run `deepdoc serve` or `deepdoc deploy`. DeepDoc generation itself uses Python-side repair and validation; Node is only needed for the generated Fumadocs site.
+To preview or deploy the generated site you also need **MkDocs Material** (pure Python — no Node.js). Install the `site` extra:
+
+```bash
+pip install 'deepdoc[site]'   # mkdocs-material + pymdown-extensions + mkdocs-swagger-ui-tag
+```
+
+`deepdoc serve` / `deepdoc deploy` will tell you to run `pip install 'deepdoc[site]'` if MkDocs is missing.
 
 ### Verify installation
 
@@ -137,7 +148,7 @@ You will also need **Node 18+** on `PATH` when you run `deepdoc serve` or `deepd
 deepdoc --version
 deepdoc --help
 python -m deepdoc --help
-node --version    # must report 18 or higher
+pip show mkdocs-material   # verify MkDocs Material is installed
 ```
 
 If you installed the chatbot extra, you can verify those dependencies with:
@@ -346,9 +357,9 @@ deepdoc generate --exclude "tests/**"
 
 1. **Phase 1: Scan** — Walk the repo, parse supported languages, detect endpoints, config/setup artifacts, runtime surfaces, integration signals, and OpenAPI specs.
 2. **Phase 2: Plan** — Run the multi-step bucket planner. It classifies the repo, proposes bucket candidates, and assigns files/symbols/artifacts to the final doc structure.
-3. **Phase 3: Generate** — Generate bucket pages in batches with parallel workers. High-level buckets are AI-planned; scanned endpoints enrich grouped API-reference pages instead of creating one page per route. Each page passes through Python-side MDX repair, grounding validation, and bounded quality retries before being written to disk.
-4. **Phase 4: API Ref** — Stage OpenAPI assets for the generated Fumadocs `/api/*` pages when a spec exists.
-5. **Phase 5: Build** — Write the generated `site/` Fumadocs scaffold, page tree, search route, and static assets from the generated plan.
+3. **Phase 3: Generate** — Generate bucket pages in batches with parallel workers. High-level buckets are AI-planned; scanned endpoints enrich grouped API-reference pages instead of creating one page per route. Each page passes through Python-side Markdown repair, grounding validation, and bounded quality retries before being written to disk.
+4. **Phase 4: API Ref** — Stage OpenAPI specs and render them on a single interactive Swagger UI page (`mkdocs-swagger-ui-tag`) when a spec exists.
+5. **Phase 5: Build** — Write the generated `site/mkdocs.yml` scaffold (Material theme), nav, and brand stylesheet from the generated plan.
 
 **Options:**
 
@@ -383,8 +394,8 @@ deepdoc update --deploy           # Update + deploy
    - **incremental** — regenerate only the stale bucket pages
    - **targeted replan** — new/deleted files or endpoint structure changes; re-plans affected buckets then regenerates them. Full replan is never triggered automatically for normal code changes.
 4. Compares the saved scan cache with the current scan so semantic endpoint changes can refresh impacted docs even when ownership files do not line up directly.
-5. Regenerates only the affected bucket pages. Deleted files are cleaned up in-place: orphaned buckets and their MDX pages are removed, partially-emptied buckets are marked stale and regenerated.
-6. Appends an entry to `.deepdoc/changelog.json` and regenerates `docs/whats-changed.mdx` so the docs site always shows a current commit-by-commit change log.
+5. Regenerates only the affected bucket pages. Deleted files are cleaned up in-place: orphaned buckets and their Markdown pages are removed, partially-emptied buckets are marked stale and regenerated.
+6. Appends an entry to `.deepdoc/changelog.json` and regenerates `docs/whats-changed.md` so the docs site always shows a current commit-by-commit change log.
 7. Incrementally refreshes the chatbot corpora from the same update run.
 8. Rebuilds site config and nav afterward.
 
@@ -396,7 +407,7 @@ Generation writes quality artifacts under `.deepdoc/`:
 - `.deepdoc/generation_quality.json` records invalid/degraded pages, coverage metrics, local setup warnings, and consistency summary data.
 - `.deepdoc/consistency_warnings.json` records warning-only cross-page identifier consistency findings.
 
-Generated MDX pages include provenance frontmatter such as `deepdoc_generated_commit`, `deepdoc_generated_at`, `deepdoc_generated_version`, `deepdoc_status`, `deepdoc_evidence_files`, and `deepdoc_prereqs` (prerequisite page slugs). The generated Fumadocs site renders a subtle "Last generated from commit ..." badge and wires prev/next navigation arrows automatically. Pages with prerequisites show a "Read first:" callout at the top.
+Generated Markdown pages include provenance frontmatter such as `deepdoc_generated_commit`, `deepdoc_generated_at`, `deepdoc_generated_version`, `deepdoc_status`, `deepdoc_evidence_files`, and `deepdoc_prereqs` (prerequisite page slugs). The MkDocs Material theme renders these pages with built-in navigation, search, and table of contents.
 
 **Options:**
 
@@ -418,26 +429,26 @@ This is useful after `generate` or `update` when you want a quick health check w
 
 ### `deepdoc serve`
 
-Preview the generated docs locally with live reload using the generated Fumadocs app in `site/`.
+Preview the generated docs locally with live reload using the generated MkDocs Material site in `site/`.
 
 ```bash
 deepdoc serve
 deepdoc serve --port 8001
 ```
 
-Requires Node.js >= 18 to be installed. Site dependencies are auto-installed into `site/node_modules/` on first run.
+Runs `mkdocs serve` against `site/mkdocs.yml`. Requires `pip install mkdocs-material` (pure Python — no Node.js).
 
 ### `deepdoc deploy`
 
-Build and export the generated Fumadocs site.
+Build and export the generated MkDocs Material site.
 
 ```bash
 deepdoc deploy
 ```
 
-This runs `next build` inside `site/` and writes the static export to `site/out/`. You can deploy that directory to Vercel, Netlify, GitHub Pages, Cloudflare Pages, or any static host.
+This runs `mkdocs build` against `site/mkdocs.yml` and writes the static HTML to `site/out/`. You can deploy that directory to Vercel, Netlify, GitHub Pages, Cloudflare Pages, or any static host.
 
-Before building, `deepdoc deploy` checks `.deepdoc/generation_quality.json` and generated MDX frontmatter. It refuses to deploy when the last generation has failed/invalid pages or when `docs/` still contains pages marked `deepdoc_status: "invalid"` or `stub: true`; rerun `deepdoc generate` after fixing those issues.
+Before building, `deepdoc deploy` checks `.deepdoc/generation_quality.json` and generated page frontmatter. It refuses to deploy when the last generation has failed/invalid pages or when `docs/` still contains pages marked `deepdoc_status: "invalid"` or `stub: true`; rerun `deepdoc generate` after fixing those issues.
 
 If you want GitHub Pages specifically, this repo includes a workflow at `.github/workflows/github-pages.yml` that publishes the checked-in `site/out/` export through the official Pages Actions flow. That means you do not need to move the export into a branch `docs/` folder.
 
@@ -684,7 +695,7 @@ site:
 | `project_name` | directory name | Project name used in site title |
 | `description` | `""` | Short project description |
 | `output_dir` | `docs` | Where generated markdown pages are written |
-| `site_dir` | `site` | Where the generated Fumadocs site lives |
+| `site_dir` | `site` | Where the generated MkDocs site config (`mkdocs.yml`) lives |
 | **LLM** | | |
 | `llm.provider` | `anthropic` | `anthropic`, `openai`, `azure`, `ollama`, or any LiteLLM alias |
 | `llm.model` | `claude-3-5-sonnet-20241022` | Model name (use provider prefix for non-Anthropic, e.g. `azure/gpt-4.1`) |
@@ -711,7 +722,7 @@ site:
 | `github_pages.branch` | `gh-pages` | Branch for GitHub Pages deploy |
 | `github_pages.remote` | `origin` | Git remote for deploy |
 | **Site** | | |
-| `site.repo_url` | `""` | Repo URL shown in the generated Fumadocs navigation |
+| `site.repo_url` | `""` | Repo URL shown in the generated MkDocs Material navigation |
 | `site.favicon` | `""` | Path to favicon |
 | `site.logo` | `""` | Path to logo |
 | **Compatibility** | | |
@@ -739,7 +750,7 @@ The chatbot has three independent model surfaces that you can mix across provide
 | `chatbot.answer.*` | Chatbot answer generation | GPT-4o-mini, Claude, Gemini Flash |
 | `chatbot.embeddings.*` | Vector embeddings for retrieval | text-embedding-3-large, Gemini text-embedding-004 |
 
-`deepdoc serve` auto-starts the chatbot backend alongside the Fumadocs site. The backend port is deterministically assigned from your repo path (range 8100–8799) unless you set an explicit `base_url`.
+`deepdoc serve` auto-starts the chatbot backend alongside the MkDocs site. The backend port is deterministically assigned from your repo path (range 8100–8799) unless you set an explicit `base_url`.
 
 ### Evidence-First Responses
 
@@ -1138,8 +1149,8 @@ During `deepdoc generate`, six corpora are built and stored in `.deepdoc/chatbot
 |--------|--------|-------------|
 | **Code chunks** | All parsed source files | Code split by line count with overlap, tagged with symbols and file paths |
 | **Artifact chunks** | Config files (Dockerfile, package.json, OpenAPI specs, etc.) | Non-code project files split similarly |
-| **Doc summary chunks** | Generated documentation pages | First sections extracted from each generated MDX page |
-| **Doc full chunks** | Generated documentation pages | Section-level chunks from the full generated MDX pages |
+| **Doc summary chunks** | Generated documentation pages | First sections extracted from each generated Markdown page |
+| **Doc full chunks** | Generated documentation pages | Section-level chunks from the full generated Markdown pages |
 | **Repo doc chunks** | Repo-authored docs such as `README.md`, `docs/`, design notes, and notebooks | Raw repo documentation kept separate from generated pages |
 | **Relationship chunks** | Imports, symbols, call graph, and graph-neighbor summaries | Lightweight graph-style retrieval context |
 
@@ -1228,7 +1239,7 @@ POST /query-context
 
 For local development, `deepdoc serve` handles everything automatically. For production:
 
-1. Deploy the Fumadocs static site (`site/out/`) to any static host.
+1. Deploy the MkDocs static site (`site/out/`) to any static host.
 2. Deploy `chatbot_backend/` separately to a Python-capable host.
 3. Set `chatbot.backend.base_url` in `.deepdoc.yaml` to point at the deployed backend URL.
 4. Rebuild the site so the frontend picks up the new backend URL: `deepdoc deploy`.
@@ -1344,20 +1355,17 @@ your-repo/
 ├── .deepdoc_manifest.json     # Legacy source hash manifest
 ├── .deepdoc_plan.json         # Legacy compatibility plan file
 ├── .deepdoc_file_map.json     # Legacy compatibility file map
-├── docs/                       # Generated MDX pages
-│   ├── index.mdx
-│   ├── architecture.mdx
-│   ├── setup-and-configuration.mdx
-│   ├── orders-api.mdx
-│   ├── get-api-v1-orders.mdx
+├── docs/                       # Generated Markdown pages
+│   ├── index.md
+│   ├── architecture.md
+│   ├── setup-and-configuration.md
+│   ├── api.md                  # Swagger UI page (when an OpenAPI spec exists)
+│   ├── openapi/                # Staged OpenAPI specs
 │   └── ...
-└── site/                       # Generated Fumadocs app
-    ├── app/
-    ├── components/
-    ├── lib/
-    ├── openapi/                # Staged OpenAPI assets (when a spec exists)
-    ├── public/
-    └── out/                    # Static export after `deepdoc deploy`
+└── site/                       # Generated MkDocs Material site
+    ├── mkdocs.yml
+    ├── docs/stylesheets/extra.css
+    └── out/                    # Static HTML after `deepdoc deploy`
 ```
 
 ---
@@ -1433,10 +1441,6 @@ jobs:
         with:
           python-version: "3.11"
 
-      - uses: actions/setup-node@v4
-        with:
-          node-version: "20"
-
       - name: Install dependencies
         run: |
           pip install deepdoc   # or: pip install "deepdoc[chatbot]" if you use chatbot features
@@ -1489,10 +1493,6 @@ jobs:
         with:
           python-version: "3.11"
 
-      - uses: actions/setup-node@v4
-        with:
-          node-version: "20"
-
       - name: Install deepdoc
         run: pip install deepdoc
 
@@ -1562,7 +1562,7 @@ deepdoc generate --force           # Full regen with new model
 ## Requirements
 
 - Python 3.10+
-- **Node 18+** on `PATH` — used by `deepdoc serve` and `deepdoc deploy` for the generated Fumadocs site
+- **MkDocs Material** (`pip install mkdocs-material`) — used by `deepdoc serve` and `deepdoc deploy` for the generated site. Pure Python, no Node.js. Add `mkdocs-swagger-ui-tag` when your repo has an OpenAPI/Swagger spec.
 - Git (for `deepdoc update` and `deepdoc deploy`)
 - An LLM API key (or Ollama running locally)
 

{deepdoc-2.3.6 → deepdoc-3.1.0}/README.md

@@ -18,7 +18,7 @@
 
 Auto-generate deep engineering documentation from real codebases using AI.
 
-DeepDoc scans your repo, builds a bucket-based documentation plan, generates rich MDX pages with Mermaid diagrams, and builds a local-first Fumadocs site with Orama search.
+DeepDoc scans your repo, builds a bucket-based documentation plan, generates rich Markdown pages with Mermaid diagrams, and builds a local-first MkDocs Material site with built-in search.
 
 ## Contents
 
@@ -43,11 +43,11 @@ DeepDoc scans your repo, builds a bucket-based documentation plan, generates ric
 - **Bucket-based documentation architecture** — system, feature, endpoint, integration, and database buckets instead of one-file-per-page noise.
 - **Multi-step AI planner** — classifies the repo, proposes buckets, then assigns files, symbols, artifacts, and dependencies into a final reader-first plan.
 - **Giant-file handling** — large files are decomposed into feature-aligned clusters so a single controller can feed multiple doc pages.
-- **MDX-safe generation** — generated pages are repaired and validated in Python before being written; deploy-time quality gates block failed, invalid, or stub pages before the Fumadocs build.
+- **Stable plain-Markdown generation** — generated pages are plain CommonMark (no MDX/JSX compile step, so a page can never fail to build); they are repaired and validated in Python before being written, and deploy-time quality gates block failed, invalid, or stub pages before the build.
 - **Evidence-first chatbot answers** — final code proof is hydrated from archived source snippets with exact file paths and line ranges, not just retrieval guesses.
 - **Incremental updates** — `deepdoc update` regenerates only stale or structurally affected docs against the last synced commit.
-- **OpenAPI-aware API docs** — auto-detects OpenAPI/Swagger specs and stages interactive `/api/*` pages in the generated site.
-- **Local-first Fumadocs site** — generates a `site/` Next.js app with Fumadocs UI, Mermaid rendering, and built-in search; `deepdoc deploy` exports a static site to any host.
+- **OpenAPI-aware API docs** — auto-detects OpenAPI/Swagger specs and renders an interactive Swagger UI page (`mkdocs-swagger-ui-tag`) in the generated site.
+- **Local-first MkDocs Material site** — generates a `site/mkdocs.yml` (Material theme, Mermaid, built-in search); `deepdoc deploy` runs `mkdocs build` and exports a static site to any host. Pure Python — no Node.js required.
 
 Works with Anthropic, OpenAI, Azure OpenAI, Google Gemini, Ollama, and any other LiteLLM-compatible provider. Parses Python, JavaScript/TypeScript, Go, PHP, and Vue.
 
@@ -90,7 +90,13 @@ pip install click litellm gitpython rich pyyaml jinja2
 pip install -e . --no-deps
 ```
 
-You will also need **Node 18+** on `PATH` when you run `deepdoc serve` or `deepdoc deploy`. DeepDoc generation itself uses Python-side repair and validation; Node is only needed for the generated Fumadocs site.
+To preview or deploy the generated site you also need **MkDocs Material** (pure Python — no Node.js). Install the `site` extra:
+
+```bash
+pip install 'deepdoc[site]'   # mkdocs-material + pymdown-extensions + mkdocs-swagger-ui-tag
+```
+
+`deepdoc serve` / `deepdoc deploy` will tell you to run `pip install 'deepdoc[site]'` if MkDocs is missing.
 
 ### Verify installation
 
@@ -98,7 +104,7 @@ You will also need **Node 18+** on `PATH` when you run `deepdoc serve` or `deepd
 deepdoc --version
 deepdoc --help
 python -m deepdoc --help
-node --version    # must report 18 or higher
+pip show mkdocs-material   # verify MkDocs Material is installed
 ```
 
 If you installed the chatbot extra, you can verify those dependencies with:
@@ -307,9 +313,9 @@ deepdoc generate --exclude "tests/**"
 
 1. **Phase 1: Scan** — Walk the repo, parse supported languages, detect endpoints, config/setup artifacts, runtime surfaces, integration signals, and OpenAPI specs.
 2. **Phase 2: Plan** — Run the multi-step bucket planner. It classifies the repo, proposes bucket candidates, and assigns files/symbols/artifacts to the final doc structure.
-3. **Phase 3: Generate** — Generate bucket pages in batches with parallel workers. High-level buckets are AI-planned; scanned endpoints enrich grouped API-reference pages instead of creating one page per route. Each page passes through Python-side MDX repair, grounding validation, and bounded quality retries before being written to disk.
-4. **Phase 4: API Ref** — Stage OpenAPI assets for the generated Fumadocs `/api/*` pages when a spec exists.
-5. **Phase 5: Build** — Write the generated `site/` Fumadocs scaffold, page tree, search route, and static assets from the generated plan.
+3. **Phase 3: Generate** — Generate bucket pages in batches with parallel workers. High-level buckets are AI-planned; scanned endpoints enrich grouped API-reference pages instead of creating one page per route. Each page passes through Python-side Markdown repair, grounding validation, and bounded quality retries before being written to disk.
+4. **Phase 4: API Ref** — Stage OpenAPI specs and render them on a single interactive Swagger UI page (`mkdocs-swagger-ui-tag`) when a spec exists.
+5. **Phase 5: Build** — Write the generated `site/mkdocs.yml` scaffold (Material theme), nav, and brand stylesheet from the generated plan.
 
 **Options:**
 
@@ -344,8 +350,8 @@ deepdoc update --deploy           # Update + deploy
    - **incremental** — regenerate only the stale bucket pages
    - **targeted replan** — new/deleted files or endpoint structure changes; re-plans affected buckets then regenerates them. Full replan is never triggered automatically for normal code changes.
 4. Compares the saved scan cache with the current scan so semantic endpoint changes can refresh impacted docs even when ownership files do not line up directly.
-5. Regenerates only the affected bucket pages. Deleted files are cleaned up in-place: orphaned buckets and their MDX pages are removed, partially-emptied buckets are marked stale and regenerated.
-6. Appends an entry to `.deepdoc/changelog.json` and regenerates `docs/whats-changed.mdx` so the docs site always shows a current commit-by-commit change log.
+5. Regenerates only the affected bucket pages. Deleted files are cleaned up in-place: orphaned buckets and their Markdown pages are removed, partially-emptied buckets are marked stale and regenerated.
+6. Appends an entry to `.deepdoc/changelog.json` and regenerates `docs/whats-changed.md` so the docs site always shows a current commit-by-commit change log.
 7. Incrementally refreshes the chatbot corpora from the same update run.
 8. Rebuilds site config and nav afterward.
 
@@ -357,7 +363,7 @@ Generation writes quality artifacts under `.deepdoc/`:
 - `.deepdoc/generation_quality.json` records invalid/degraded pages, coverage metrics, local setup warnings, and consistency summary data.
 - `.deepdoc/consistency_warnings.json` records warning-only cross-page identifier consistency findings.
 
-Generated MDX pages include provenance frontmatter such as `deepdoc_generated_commit`, `deepdoc_generated_at`, `deepdoc_generated_version`, `deepdoc_status`, `deepdoc_evidence_files`, and `deepdoc_prereqs` (prerequisite page slugs). The generated Fumadocs site renders a subtle "Last generated from commit ..." badge and wires prev/next navigation arrows automatically. Pages with prerequisites show a "Read first:" callout at the top.
+Generated Markdown pages include provenance frontmatter such as `deepdoc_generated_commit`, `deepdoc_generated_at`, `deepdoc_generated_version`, `deepdoc_status`, `deepdoc_evidence_files`, and `deepdoc_prereqs` (prerequisite page slugs). The MkDocs Material theme renders these pages with built-in navigation, search, and table of contents.
 
 **Options:**
 
@@ -379,26 +385,26 @@ This is useful after `generate` or `update` when you want a quick health check w
 
 ### `deepdoc serve`
 
-Preview the generated docs locally with live reload using the generated Fumadocs app in `site/`.
+Preview the generated docs locally with live reload using the generated MkDocs Material site in `site/`.
 
 ```bash
 deepdoc serve
 deepdoc serve --port 8001
 ```
 
-Requires Node.js >= 18 to be installed. Site dependencies are auto-installed into `site/node_modules/` on first run.
+Runs `mkdocs serve` against `site/mkdocs.yml`. Requires `pip install mkdocs-material` (pure Python — no Node.js).
 
 ### `deepdoc deploy`
 
-Build and export the generated Fumadocs site.
+Build and export the generated MkDocs Material site.
 
 ```bash
 deepdoc deploy
 ```
 
-This runs `next build` inside `site/` and writes the static export to `site/out/`. You can deploy that directory to Vercel, Netlify, GitHub Pages, Cloudflare Pages, or any static host.
+This runs `mkdocs build` against `site/mkdocs.yml` and writes the static HTML to `site/out/`. You can deploy that directory to Vercel, Netlify, GitHub Pages, Cloudflare Pages, or any static host.
 
-Before building, `deepdoc deploy` checks `.deepdoc/generation_quality.json` and generated MDX frontmatter. It refuses to deploy when the last generation has failed/invalid pages or when `docs/` still contains pages marked `deepdoc_status: "invalid"` or `stub: true`; rerun `deepdoc generate` after fixing those issues.
+Before building, `deepdoc deploy` checks `.deepdoc/generation_quality.json` and generated page frontmatter. It refuses to deploy when the last generation has failed/invalid pages or when `docs/` still contains pages marked `deepdoc_status: "invalid"` or `stub: true`; rerun `deepdoc generate` after fixing those issues.
 
 If you want GitHub Pages specifically, this repo includes a workflow at `.github/workflows/github-pages.yml` that publishes the checked-in `site/out/` export through the official Pages Actions flow. That means you do not need to move the export into a branch `docs/` folder.
 
@@ -645,7 +651,7 @@ site:
 | `project_name` | directory name | Project name used in site title |
 | `description` | `""` | Short project description |
 | `output_dir` | `docs` | Where generated markdown pages are written |
-| `site_dir` | `site` | Where the generated Fumadocs site lives |
+| `site_dir` | `site` | Where the generated MkDocs site config (`mkdocs.yml`) lives |
 | **LLM** | | |
 | `llm.provider` | `anthropic` | `anthropic`, `openai`, `azure`, `ollama`, or any LiteLLM alias |
 | `llm.model` | `claude-3-5-sonnet-20241022` | Model name (use provider prefix for non-Anthropic, e.g. `azure/gpt-4.1`) |
@@ -672,7 +678,7 @@ site:
 | `github_pages.branch` | `gh-pages` | Branch for GitHub Pages deploy |
 | `github_pages.remote` | `origin` | Git remote for deploy |
 | **Site** | | |
-| `site.repo_url` | `""` | Repo URL shown in the generated Fumadocs navigation |
+| `site.repo_url` | `""` | Repo URL shown in the generated MkDocs Material navigation |
 | `site.favicon` | `""` | Path to favicon |
 | `site.logo` | `""` | Path to logo |
 | **Compatibility** | | |
@@ -700,7 +706,7 @@ The chatbot has three independent model surfaces that you can mix across provide
 | `chatbot.answer.*` | Chatbot answer generation | GPT-4o-mini, Claude, Gemini Flash |
 | `chatbot.embeddings.*` | Vector embeddings for retrieval | text-embedding-3-large, Gemini text-embedding-004 |
 
-`deepdoc serve` auto-starts the chatbot backend alongside the Fumadocs site. The backend port is deterministically assigned from your repo path (range 8100–8799) unless you set an explicit `base_url`.
+`deepdoc serve` auto-starts the chatbot backend alongside the MkDocs site. The backend port is deterministically assigned from your repo path (range 8100–8799) unless you set an explicit `base_url`.
 
 ### Evidence-First Responses
 
@@ -1099,8 +1105,8 @@ During `deepdoc generate`, six corpora are built and stored in `.deepdoc/chatbot
 |--------|--------|-------------|
 | **Code chunks** | All parsed source files | Code split by line count with overlap, tagged with symbols and file paths |
 | **Artifact chunks** | Config files (Dockerfile, package.json, OpenAPI specs, etc.) | Non-code project files split similarly |
-| **Doc summary chunks** | Generated documentation pages | First sections extracted from each generated MDX page |
-| **Doc full chunks** | Generated documentation pages | Section-level chunks from the full generated MDX pages |
+| **Doc summary chunks** | Generated documentation pages | First sections extracted from each generated Markdown page |
+| **Doc full chunks** | Generated documentation pages | Section-level chunks from the full generated Markdown pages |
 | **Repo doc chunks** | Repo-authored docs such as `README.md`, `docs/`, design notes, and notebooks | Raw repo documentation kept separate from generated pages |
 | **Relationship chunks** | Imports, symbols, call graph, and graph-neighbor summaries | Lightweight graph-style retrieval context |
 
@@ -1189,7 +1195,7 @@ POST /query-context
 
 For local development, `deepdoc serve` handles everything automatically. For production:
 
-1. Deploy the Fumadocs static site (`site/out/`) to any static host.
+1. Deploy the MkDocs static site (`site/out/`) to any static host.
 2. Deploy `chatbot_backend/` separately to a Python-capable host.
 3. Set `chatbot.backend.base_url` in `.deepdoc.yaml` to point at the deployed backend URL.
 4. Rebuild the site so the frontend picks up the new backend URL: `deepdoc deploy`.
@@ -1305,20 +1311,17 @@ your-repo/
 ├── .deepdoc_manifest.json     # Legacy source hash manifest
 ├── .deepdoc_plan.json         # Legacy compatibility plan file
 ├── .deepdoc_file_map.json     # Legacy compatibility file map
-├── docs/                       # Generated MDX pages
-│   ├── index.mdx
-│   ├── architecture.mdx
-│   ├── setup-and-configuration.mdx
-│   ├── orders-api.mdx
-│   ├── get-api-v1-orders.mdx
+├── docs/                       # Generated Markdown pages
+│   ├── index.md
+│   ├── architecture.md
+│   ├── setup-and-configuration.md
+│   ├── api.md                  # Swagger UI page (when an OpenAPI spec exists)
+│   ├── openapi/                # Staged OpenAPI specs
 │   └── ...
-└── site/                       # Generated Fumadocs app
-    ├── app/
-    ├── components/
-    ├── lib/
-    ├── openapi/                # Staged OpenAPI assets (when a spec exists)
-    ├── public/
-    └── out/                    # Static export after `deepdoc deploy`
+└── site/                       # Generated MkDocs Material site
+    ├── mkdocs.yml
+    ├── docs/stylesheets/extra.css
+    └── out/                    # Static HTML after `deepdoc deploy`
 ```
 
 ---
@@ -1394,10 +1397,6 @@ jobs:
         with:
           python-version: "3.11"
 
-      - uses: actions/setup-node@v4
-        with:
-          node-version: "20"
-
       - name: Install dependencies
         run: |
           pip install deepdoc   # or: pip install "deepdoc[chatbot]" if you use chatbot features
@@ -1450,10 +1449,6 @@ jobs:
         with:
           python-version: "3.11"
 
-      - uses: actions/setup-node@v4
-        with:
-          node-version: "20"
-
       - name: Install deepdoc
         run: pip install deepdoc
 
@@ -1523,7 +1518,7 @@ deepdoc generate --force           # Full regen with new model
 ## Requirements
 
 - Python 3.10+
-- **Node 18+** on `PATH` — used by `deepdoc serve` and `deepdoc deploy` for the generated Fumadocs site
+- **MkDocs Material** (`pip install mkdocs-material`) — used by `deepdoc serve` and `deepdoc deploy` for the generated site. Pure Python, no Node.js. Add `mkdocs-swagger-ui-tag` when your repo has an OpenAPI/Swagger spec.
 - Git (for `deepdoc update` and `deepdoc deploy`)
 - An LLM API key (or Ollama running locally)
 

{deepdoc-2.3.6 → deepdoc-3.1.0}/deepdoc/__init__.py

@@ -1,3 +1,3 @@
 """DeepDoc — Auto-generate beautiful docs from any codebase."""
 
-__version__ = "2.3.5"
+__version__ = "3.1.0"

{deepdoc-2.3.6 → deepdoc-3.1.0}/deepdoc/changelog_writer.py

@@ -72,11 +72,10 @@ def _build_md(entries: list[dict]) -> str:
 
     if not entries:
         lines.append(
-            ":::note\nNo changelog entries yet. Run `deepdoc generate` to create the first entry.\n:::"
+            "/// note\nNo changelog entries yet. Run `deepdoc generate` to create the first entry.\n///"
         )
         return "\n".join(lines)
 
-    lines.append(":::accordions")
     for entry in entries:
         date = entry.get("date", "")
         msg = entry.get("commit_message", "update")
@@ -88,7 +87,7 @@ def _build_md(entries: list[dict]) -> str:
         strategy_label = _STRATEGY_LABEL.get(strategy, strategy)
 
         title = f"{date} — {msg[:72]} ({sha})"
-        lines.append(f'::accordion{{title="{title}"}}')
+        lines.append(f"/// details | {title}")
         lines.append("")
 
         # Commit metadata row
@@ -109,17 +108,17 @@ def _build_md(entries: list[dict]) -> str:
                 lines.append("**Pages generated:**")
                 lines.append("")
                 for s in pages:
-                    lines.append(f"- [{_slug_to_title(s)}](/{s})")
+                    lines.append(f"- [{_slug_to_title(s)}]({s}.md)")
         else:
             # Pages updated
             if pages:
                 lines.append(f"**{len(pages)} page(s) updated:**")
                 lines.append("")
                 for s in pages:
-                    lines.append(f"- [{_slug_to_title(s)}](/{s})")
+                    lines.append(f"- [{_slug_to_title(s)}]({s}.md)")
             else:
                 lines.append(
-                    ":::info\nNo pages were regenerated — only metadata or chatbot corpora were refreshed.\n:::"
+                    "/// info\nNo pages were regenerated — only metadata or chatbot corpora were refreshed.\n///"
                 )
 
             # Source files that changed
@@ -148,9 +147,8 @@ def _build_md(entries: list[dict]) -> str:
                 )
 
         lines.append("")
-        lines.append("::")
+        lines.append("///")
 
-    lines.append(":::")
     return "\n".join(lines)
 
 

{deepdoc-2.3.6 → deepdoc-3.1.0}/deepdoc/chatbot/answer_mixin.py

@@ -668,15 +668,15 @@ class AnswerMixin:
                     reason=str(row.get("reason", "") or ""),
                 )
             )
-        if mode == "code_deep" and not evidence:
-            diagnostics.warnings.append("No source/config evidence was available for Code Deep.")
+        if mode == "deep" and not evidence:
+            diagnostics.warnings.append("No source/config evidence was available for deep mode.")
         return evidence, diagnostics
 
     def _evidence_role(self, row: dict[str, Any], *, source_kind: str, mode: str) -> str:
         reason = str(row.get("reason", "") or "")
         if source_kind == "config" or row.get("artifact_type"):
             return "config"
-        if reason in {"investigation_step", "research_step"} or mode == "code_deep":
+        if reason in {"investigation_step", "research_step"} or mode == "deep":
             return "implementation"
         if reason == "mentioned_source":
             return "supporting"

{deepdoc-2.3.6 → deepdoc-3.1.0}/deepdoc/chatbot/deep_research.py

@@ -426,7 +426,7 @@ class DeepResearcher:
         step: int,
     ) -> ResearchStep:
         """Run a Tool-Using ReAct loop for a single sub-question."""
-        max_iterations = 3
+        max_iterations = 5
         chunks = self._retrieve_for_question(
             question,
             history,
@@ -468,8 +468,9 @@ class DeepResearcher:
             "You have access to the following initial evidence chunks from the codebase.\n\n"
             "If the evidence is sufficient, provide your final answer in plain text.\n"
             "If you need to explore the codebase further, you can use the following tools by outputting a JSON object and NOTHING else:\n"
-            '1. read_file: `{"action": "read_file", "path": "file/path.py", "start": 10, "end": 50}`\n'
-            '2. grep: `{"action": "grep", "pattern": "def main"}`\n\n'
+            '1. search: `{"action": "search", "query": "what you want to find"}`  — semantic search over the code index\n'
+            '2. read_file: `{"action": "read_file", "path": "file/path.py", "start": 10, "end": 50}`\n'
+            '3. grep: `{"action": "grep", "pattern": "def main"}`\n\n'
             "Answer ONLY based on evidence. Prefer a detailed, implementation-level walkthrough.\n\n"
             "## STRICT GROUNDING RULES\n"
             "- Do NOT invent, fabricate, or hallucinate any code, function names, class names, "
@@ -632,6 +633,35 @@ class DeepResearcher:
                 results.append("... [truncated due to length]")
             return "\n".join(results)
 
+        elif action == "search":
+            query = str(tool_call.get("query", "")).strip()
+            if not query or len(query) < 3:
+                return "Error: search requires a non-empty 'query' (min 3 characters)."
+            try:
+                retrieve_context = getattr(self.service, "retrieve_context", None)
+                if not callable(retrieve_context):
+                    return "Error: search tool unavailable."
+                context = retrieve_context(query, [], mode="fast")
+                code_hits = context.get("code_hits", [])[:8]
+                if not code_hits:
+                    return f"No code matches found for '{query}'."
+                parts = []
+                for i, hit in enumerate(code_hits, 1):
+                    record = getattr(hit, "record", hit)
+                    source = (
+                        getattr(record, "file_path", None)
+                        or getattr(record, "doc_path", None)
+                        or "unknown"
+                    )
+                    text = getattr(record, "text", "")[:1600]
+                    score = round(float(getattr(hit, "score", 0.0)), 3)
+                    parts.append(f"[{i}] {source} (score={score}):\n{text}")
+                    if source not in sources_used:
+                        sources_used.append(source)
+                return "\n\n".join(parts)
+            except Exception as e:
+                return f"Error: Search failed - {e}"
+
         return f"Error: Unknown action '{action}'"
 
     def _synthesise(

{deepdoc-2.3.6 → deepdoc-3.1.0}/deepdoc/chatbot/retrieval_mixin.py

@@ -780,8 +780,10 @@ class RetrievalMixin:
         source_kind = record.source_kind or ""
         if source_kind == "product":
             priority += 0.8 if supporting_requested else 2.5
-        elif source_kind in {"config", "docs", "ops", "tooling"}:
+        elif source_kind in {"config", "ops", "tooling"}:
             priority += 1.2
+        elif source_kind == "docs":
+            priority += 0.2
         elif source_kind in {"test", "fixture", "example", "generated"}:
             priority += 4.5 if supporting_requested else -1.0