# Fumadocs reference (for repo2docs)

Just enough Fumadocs to author and configure a polished docs site served under
`/docs`. For the authoritative, version-current docs, see
https://fumadocs.dev — this file captures the decisions that matter for this
skill, not the full framework.

## Scaffolding

`create-fumadocs-app` is the official scaffolder. The skill calls it
non-interactively via `scripts/scaffold_docs.py`. Relevant flags (confirmed CLI
surface):

```
--template +next+fuma-docs-mdx     # Next.js + Fumadocs MDX (default we use)
--src                              # put app/ and content/ under src/
--install                          # install deps
--no-git                           # we manage git ourselves
--search orama                     # built-in client search
--pm pnpm|npm|yarn|bun
```

Other templates exist (`waku`, `react-router`, `tanstack-start`, `+static`). We
default to Next.js because Vercel + basePath is the smoothest path to
`{id}.example.com/docs`.

## Directory layout (with `--src`)

```
src/
  app/
    (home)/            # optional landing area
    docs/
      [[...slug]]/page.tsx   # renders a doc page
      layout.tsx             # DocsLayout (sidebar, nav)
    layout.config.tsx        # shared nav/links/title
    layout.tsx               # RootProvider
  content/
    docs/
      index.mdx
      meta.json              # sidebar order for this folder
      guides/
        meta.json
        *.mdx
  lib/
    source.ts                # loader() binding content → source
source.config.ts             # defineDocs / frontmatter schema
next.config.mjs
```

Without `--src`, drop the `src/` prefix (`app/`, `content/`, `lib/`).

## The `/docs` basePath — the key gotcha

The site must live at `domain/docs`, NOT `domain/`. Two distinct concerns:

1. **Next.js `basePath`** — makes the WHOLE app serve under `/docs`. Set in
   `next.config.mjs`:
   ```js
   const config = {
     basePath: '/docs',
     // ...
   };
   ```
   `scaffold_docs.py` injects this automatically. With basePath set, Next.js
   prefixes all routes and assets with `/docs`; `<Link>` hrefs stay root-relative
   (`/guides/x`) and Next adds the prefix.

2. **Fumadocs page routing** — the docs themselves already mount at `/docs`
   inside the app (the `app/docs/` route). With Next `basePath: '/docs'` ALSO
   set, the docs pages would end up at `/docs/docs`. Pick ONE of:
   - **Recommended**: keep Fumadocs at the app ROOT (move the docs route to
     `app/[[...slug]]/`) and rely on Next `basePath: '/docs'` to provide the
     `/docs` prefix. Simpler mental model: app root = docs, basePath shifts
     everything to `/docs`.
   - Or: leave Fumadocs at `app/docs/` and do NOT set Next basePath — but then
     the deploy must route the subdomain root to it, which is messier.

   Default to the first. After scaffolding, if the template put docs under
   `app/docs/`, move it to the root route group so basePath alone yields `/docs`.
   Verify with `pnpm build` + `pnpm start` then `curl localhost:3000/docs`.

If a page renders 404 under `/docs`, it's almost always a double-prefix
(`/docs/docs`) or a missing basePath. Check both.

## Authoring MDX

Front-matter per page:

```mdx
---
title: Getting Started
description: Install and run your first command
---
```

`meta.json` controls sidebar order and grouping per folder:

```json
{
  "title": "Guides",
  "pages": ["installation", "configuration", "deployment"]
}
```

Use `"---Section---"` separators and `"[Label](url)"` items in `pages` for
dividers/external links.

## Built-in MDX components (import from fumadocs-ui)

Use these for a polished, non-boilerplate feel:

- `<Cards>` / `<Card>` — link grids on landing/index pages
- `<Tabs>` / `<Tab>` — multi-language install or code variants
- `<Steps>` / `<Step>` — numbered getting-started sequences
- `<Callout type="info|warn|error">` — admonitions
- `<TypeTable>` — render prop/config tables for API reference
- Auto syntax-highlighted code fences (```ts, ```bash) with copy buttons

Example index page:

```mdx
---
title: MyProduct
description: Short tagline
---

import { Cards, Card } from 'fumadocs-ui/components/card';

<Cards>
  <Card title="Getting Started" href="/getting-started" />
  <Card title="Guides" href="/guides" />
  <Card title="API Reference" href="/api" />
</Cards>
```

## Branding (optional, Skill Publisher Configurable Academic)

Fumadocs theming is Tailwind-based. To match Skill Publisher, set CSS variables in the
global stylesheet:
- primary / accent → terracotta `#4F46E5`
- background → `#F9F9F7`, foreground → `#181818`

Keep it light-touch; a clean default Fumadocs theme already looks professional.

## Build & verify

```bash
pnpm build         # fails loudly on broken MDX links / bad imports
pnpm start         # serve the production build
curl -sI localhost:3000/docs | head -1   # expect 200
```

Fix all build errors before deploying — Vercel will fail the same way.

# User Configuration

This skill follows the portable agent skill profile contract. It must not
assume a private workspace, personal absolute paths, or private brand assets.

## Resolution Order

1. Explicit CLI flags.
2. Environment variables.
3. Shared profile JSON.
4. Safe defaults such as the current working directory or `$HOME/Documents`.
5. Ask the user once for missing required fields.

## Shared Profile

Default profile path:

```bash
${SKILL_PROFILE_PATH:-$HOME/.skill-publisher/skills/profile.json}
```

Example:

```json
{
  "user": {
    "name": "Your Name",
    "language": "zh-CN",
    "timezone": "Asia/Shanghai"
  },
  "workspace": {
    "root": "$HOME/projects",
    "output_dir": "$HOME/Documents/lov-skill-output"
  },
  "brand": {
    "name": "Your Brand",
    "site": "https://example.com",
    "profile": "$HOME/.skill-publisher/skills/brand.json",
    "design_guide": "$HOME/.skill-publisher/skills/design-guide.md"
  }
}
```

Environment variable overrides:

| Variable | Meaning |
|----------|---------|
| `SKILL_PROFILE_PATH` | Path to the shared profile JSON |
| `SKILLS_CONFIG_DIR` | Shared Skill Publisher skills config/data directory |
| `SKILL_WORKSPACE_ROOT` | User workspace root |
| `SKILL_OUTPUT_DIR` | Default generated output directory |
| `SKILL_PROFILE_PATH` | Brand profile JSON or Markdown |
| `SKILL_DESIGN_GUIDE` | Design guide path |

## Implementation Notes

- Scripts should accept explicit paths via CLI flags.
- Missing profile fields should produce actionable errors.
- Skill Publisher maintainer defaults belong in an optional profile, not in the workflow.

#!/usr/bin/env python3
"""
Copy images from a source folder into a Fumadocs site's public/ tree and emit a
path mapping the agent uses to embed them in MDX.

Images in a content folder are first-class — they must end up under the site's
`public/` so MDX can reference them as `/assets/<...>`. With Next.js basePath
'/docs', a `/assets/x.png` reference resolves to `/docs/assets/x.png`
automatically, so MDX should use root-relative `/assets/...` paths.

Optionally downsizes/transcodes large or non-web-friendly images (HEIC/TIFF/BMP)
to web formats when Pillow is available; otherwise copies verbatim.

Usage:
    python3 copy_assets.py --src ./my-folder --site ./my-docs
    python3 copy_assets.py --src ./my-folder --site ./my-docs --max-width 1600
    python3 copy_assets.py --src ./my-folder --site ./my-docs --out assets-map.json

Output (JSON): { "<source-rel-path>": "/assets/<dest-rel-path>", ... }
"""

import argparse
import json
import os
import shutil
import sys
from pathlib import Path

IMAGE_EXTS = {".png", ".jpg", ".jpeg", ".gif", ".webp", ".svg", ".avif",
              ".bmp", ".heic", ".heif", ".tiff"}
# Formats we transcode to web-friendly when Pillow is present.
TRANSCODE = {".heic", ".heif", ".tiff", ".bmp"}
SKIP_DIRS = {".git", "node_modules", ".next", "dist", "build", "out",
             "__pycache__", ".venv", "venv", ".obsidian"}


def find_images(root: Path):
    for dirpath, dirnames, filenames in os.walk(root):
        dirnames[:] = [d for d in dirnames if d not in SKIP_DIRS and not d.startswith(".")]
        for fn in filenames:
            if Path(fn).suffix.lower() in IMAGE_EXTS:
                yield Path(dirpath) / fn


def try_pillow():
    try:
        from PIL import Image  # noqa
        return True
    except Exception:
        return False


def process(src_img: Path, dest_img: Path, max_width: int, has_pillow: bool) -> Path:
    """Copy or transcode/resize. Returns the final dest path (extension may
    change when transcoding)."""
    ext = src_img.suffix.lower()
    dest_img.parent.mkdir(parents=True, exist_ok=True)

    needs_transcode = ext in TRANSCODE
    if not has_pillow or (ext == ".svg") or (ext == ".gif"):
        # Verbatim copy (SVG/GIF must not be rasterized; no Pillow → no resize).
        shutil.copy2(src_img, dest_img)
        return dest_img

    try:
        from PIL import Image
        with Image.open(src_img) as im:
            if needs_transcode:
                dest_img = dest_img.with_suffix(".jpg" if im.mode == "RGB" else ".png")
            if im.width > max_width:
                ratio = max_width / im.width
                im = im.resize((max_width, max(1, int(im.height * ratio))))
            save_kwargs = {}
            if dest_img.suffix.lower() in (".jpg", ".jpeg"):
                im = im.convert("RGB")
                save_kwargs = {"quality": 85, "optimize": True}
            im.save(dest_img, **save_kwargs)
        return dest_img
    except Exception as exc:
        print(f"WARN: {src_img}: {exc}; copying verbatim", file=sys.stderr)
        dest_img = dest_img.with_suffix(ext)
        shutil.copy2(src_img, dest_img)
        return dest_img


def main():
    ap = argparse.ArgumentParser(description="Copy/optimize images into a Fumadocs public/ tree")
    ap.add_argument("--src", required=True, help="Source content folder")
    ap.add_argument("--site", required=True, help="Fumadocs site root (contains public/)")
    ap.add_argument("--subdir", default="assets", help="Subdir under public/ (default: assets)")
    ap.add_argument("--max-width", type=int, default=1600, help="Downscale wider images (default 1600px)")
    ap.add_argument("--no-optimize", action="store_true", help="Copy verbatim, never transcode/resize")
    ap.add_argument("--out", default="", help="Write the path map JSON here (default: stdout)")
    args = ap.parse_args()

    root = Path(os.path.expanduser(args.src)).resolve()
    site = Path(os.path.expanduser(args.site)).resolve()
    if not root.is_dir():
        sys.exit(f"ERROR: --src not a directory: {root}")
    if not site.is_dir():
        sys.exit(f"ERROR: --site not a directory: {site}")

    public = site / "public" / args.subdir
    has_pillow = (not args.no_optimize) and try_pillow()

    mapping = {}
    n = 0
    for img in find_images(root):
        rel = img.relative_to(root)
        dest = public / rel
        if args.no_optimize:
            dest.parent.mkdir(parents=True, exist_ok=True)
            shutil.copy2(img, dest)
            final = dest
        else:
            final = process(img, dest, args.max_width, has_pillow)
        web_path = "/" + str(Path(args.subdir) / final.relative_to(public)).replace(os.sep, "/")
        mapping[str(rel).replace(os.sep, "/")] = web_path
        n += 1

    text = json.dumps(mapping, ensure_ascii=False, indent=2)
    if args.out:
        Path(args.out).write_text(text, encoding="utf-8")
        print(f"✓ {n} images → {public}  (pillow={'yes' if has_pillow else 'no'})", file=sys.stderr)
    else:
        print(text)


if __name__ == "__main__":
    main()

#!/usr/bin/env python3
"""
Inventory a source folder for the incremental docs build.

Walks a folder (a code repo, an article collection, a mixed knowledge dump —
they're all just "a folder of source material"), classifies each file, and emits
a JSON manifest the agent uses to drive the incremental authoring loop.

It does NOT read file *contents* into the manifest (the agent does that, one unit
at a time). It only enumerates, classifies, guesses titles cheaply, and orders
files so overview material comes first.

Usage:
    python3 inventory.py --src ./my-folder
    python3 inventory.py --src ./my-folder --out manifest.json
    python3 inventory.py --src ./my-folder --max-bytes 2000000

Output (JSON):
    {
      "root": "/abs/path",
      "counts": {"article": 12, "code": 30, "image": 40, ...},
      "units": [
        {"path": "README.md", "kind": "article", "title": "...", "bytes": 1234,
         "order": 0, "images": []},
        ...
      ]
    }
"""

import argparse
import json
import os
import re
import sys
from pathlib import Path

# Extension → kind
TEXT_DOC = {".md", ".mdx", ".markdown", ".rst", ".txt", ".adoc", ".org"}
IMAGE = {".png", ".jpg", ".jpeg", ".gif", ".webp", ".svg", ".avif", ".bmp",
         ".heic", ".heif", ".tiff"}
DATA = {".json", ".yaml", ".yml", ".toml", ".csv", ".tsv", ".xml", ".ini"}
CODE = {".py", ".js", ".jsx", ".ts", ".tsx", ".go", ".rs", ".java", ".kt",
        ".rb", ".php", ".c", ".h", ".cpp", ".hpp", ".cs", ".swift", ".sh",
        ".lua", ".sql", ".vue", ".svelte", ".scala", ".clj", ".ex", ".dart"}
PDF = {".pdf"}
OFFICE = {".docx", ".pptx", ".xlsx", ".doc", ".ppt", ".xls"}

# Directories never worth walking.
SKIP_DIRS = {
    ".git", "node_modules", ".next", "dist", "build", "out", "target",
    "__pycache__", ".venv", "venv", ".idea", ".vscode", "coverage",
    ".turbo", ".cache", "vendor", ".pnpm-store", ".obsidian",
}

# Overview-ish names float to the front of the reading order.
OVERVIEW_HINTS = ("readme", "index", "intro", "introduction", "overview",
                  "start", "getting-started", "about", "_index", "home")


def classify(path: Path) -> str:
    ext = path.suffix.lower()
    if ext in IMAGE:
        return "image"
    if ext in TEXT_DOC:
        return "article"
    if ext in CODE:
        return "code"
    if ext in PDF:
        return "pdf"
    if ext in OFFICE:
        return "office"
    if ext in DATA:
        return "data"
    return "other"


def guess_title(path: Path, kind: str, max_read: int = 4096) -> str:
    """Cheap title guess: markdown frontmatter title, first ATX heading, or
    a humanized filename."""
    stem = path.stem.replace("-", " ").replace("_", " ").strip()
    if kind != "article":
        return stem
    try:
        head = path.read_text(encoding="utf-8", errors="ignore")[:max_read]
    except OSError:
        return stem
    # YAML frontmatter title
    m = re.search(r"^---\s*\n(.*?)\n---", head, re.DOTALL)
    if m:
        t = re.search(r"^title:\s*(.+)$", m.group(1), re.MULTILINE)
        if t:
            return t.group(1).strip().strip('"\'')
    # First ATX heading
    h = re.search(r"^#\s+(.+)$", head, re.MULTILINE)
    if h:
        return h.group(1).strip()
    return stem


def order_key(rel: str, kind: str):
    """Overview material first, then articles, then code, then the rest;
    shallower paths before deeper ones; alpha within a level."""
    name = rel.lower()
    overview = 0 if any(h in os.path.basename(name) for h in OVERVIEW_HINTS) else 1
    kind_rank = {"article": 0, "pdf": 1, "office": 1, "code": 2,
                 "data": 3, "image": 4, "other": 5}.get(kind, 5)
    depth = name.count("/")
    return (overview, kind_rank, depth, name)


def walk(root: Path, max_bytes: int):
    units = []
    for dirpath, dirnames, filenames in os.walk(root):
        dirnames[:] = [d for d in dirnames if d not in SKIP_DIRS and not d.startswith(".")]
        for fn in filenames:
            if fn.startswith("."):
                continue
            p = Path(dirpath) / fn
            try:
                size = p.stat().st_size
            except OSError:
                continue
            kind = classify(p)
            rel = str(p.relative_to(root))
            unit = {
                "path": rel,
                "kind": kind,
                "bytes": size,
                "title": guess_title(p, kind) if size <= max_bytes else p.stem,
            }
            units.append(unit)
    units.sort(key=lambda u: order_key(u["path"], u["kind"]))
    for i, u in enumerate(units):
        u["order"] = i
    return units


def main():
    ap = argparse.ArgumentParser(description="Inventory a source folder for incremental docs")
    ap.add_argument("--src", required=True, help="Source folder to inventory")
    ap.add_argument("--out", default="", help="Write manifest JSON here (default: stdout)")
    ap.add_argument("--max-bytes", type=int, default=2_000_000,
                    help="Skip title-reading files larger than this (default 2MB)")
    args = ap.parse_args()

    root = Path(os.path.expanduser(args.src)).resolve()
    if not root.is_dir():
        sys.exit(f"ERROR: not a directory: {root}")

    units = walk(root, args.max_bytes)
    counts = {}
    for u in units:
        counts[u["kind"]] = counts.get(u["kind"], 0) + 1

    manifest = {"root": str(root), "counts": counts, "units": units}
    text = json.dumps(manifest, ensure_ascii=False, indent=2)
    if args.out:
        Path(args.out).write_text(text, encoding="utf-8")
        print(f"✓ {len(units)} units → {args.out}", file=sys.stderr)
        print("  " + ", ".join(f"{k}:{v}" for k, v in sorted(counts.items())), file=sys.stderr)
    else:
        print(text)


if __name__ == "__main__":
    main()

#!/usr/bin/env python3
"""
Scaffold a Fumadocs documentation site for a product code repository.

Given a product source repo (local path or already-cloned dir), this creates a
sibling Fumadocs (Next.js) app configured to serve under the `/docs` base path,
ready to deploy to https://{product-id}.example.com/docs.

It only scaffolds the shell + config. Actual page authoring is done by the agent
(reading the source repo and writing MDX into content/docs/).

Usage:
    python3 scaffold_docs.py --product-id myapp --out ./myapp-docs
    python3 scaffold_docs.py --product-id myapp --out ./myapp-docs --pm pnpm
    python3 scaffold_docs.py --product-id myapp --out ./myapp-docs --title "MyApp"

The CLI runs `create-fumadocs-app` non-interactively, then rewrites:
  - next.config.mjs  → basePath '/docs'
  - app config       → so internal links resolve under /docs
  - content/docs/    → cleared to a single placeholder index
"""

import argparse
import json
import os
import re
import shutil
import subprocess
import sys
from pathlib import Path


def run(cmd, cwd=None, env=None):
    print(f"$ {' '.join(cmd)}", file=sys.stderr)
    subprocess.run(cmd, cwd=cwd, env=env, check=True)


def proxy_env():
    """Inherit ClashX proxy if present — npm/git over the network need it in
    the Claude Code sandbox."""
    env = os.environ.copy()
    if "https_proxy" not in env and Path.home().exists():
        # Caller is expected to export these; we don't force-set, just pass through.
        pass
    return env


def slugify(value: str) -> str:
    value = value.strip().lower()
    value = re.sub(r"[^a-z0-9]+", "-", value)
    return value.strip("-")


def scaffold(product_id: str, out: Path, pm: str, title: str):
    if out.exists() and any(out.iterdir()):
        sys.exit(f"ERROR: {out} exists and is not empty")

    env = proxy_env()
    # create-fumadocs-app: Next.js + fuma-docs-mdx, no git (we manage git), install deps.
    run(
        [
            "npx", "-y", "create-fumadocs-app@latest", str(out),
            "--template", "+next+fuma-docs-mdx",
            "--pm", pm,
            "--src",
            "--install",
            "--no-git",
            "--search", "orama",
        ],
        env=env,
    )

    patch_basepath(out, title or product_id)
    reset_content(out, title or product_id)
    write_vercel_json(out)
    print(f"✓ Fumadocs site scaffolded at {out}", file=sys.stderr)
    print(f"  basePath: /docs", file=sys.stderr)
    print(f"  next: author MDX in {out}/content/docs/ from the product source", file=sys.stderr)


def patch_basepath(out: Path, title: str):
    """Set Next.js basePath to /docs so the site lives at domain/docs."""
    for name in ("next.config.mjs", "next.config.js", "next.config.ts"):
        cfg = out / name
        if cfg.exists():
            text = cfg.read_text()
            if "basePath" not in text:
                # Inject basePath into the exported config object.
                text = re.sub(
                    r"(const config\s*=\s*\{)",
                    r"\1\n  basePath: '/docs',",
                    text,
                    count=1,
                )
                if "basePath" not in text:
                    # Fallback: handle `export default { ... }` shape.
                    text = re.sub(
                        r"(export default\s*\{)",
                        r"\1\n  basePath: '/docs',",
                        text,
                        count=1,
                    )
            cfg.write_text(text)
            return
    print("WARN: no next.config.* found; set basePath '/docs' manually", file=sys.stderr)


def reset_content(out: Path, title: str):
    """Clear the demo content to a single index page placeholder."""
    docs = out / "content" / "docs"
    if docs.exists():
        for p in docs.iterdir():
            if p.is_dir():
                shutil.rmtree(p)
            else:
                p.unlink()
    docs.mkdir(parents=True, exist_ok=True)

    (docs / "index.mdx").write_text(
        f"""---
title: {title}
description: {title} documentation
---

Welcome to the **{title}** documentation.

> This is a placeholder. The agent will replace it with real pages generated
> from the product source code.
"""
    )
    (docs / "meta.json").write_text(
        json.dumps({"title": title, "pages": ["index"]}, ensure_ascii=False, indent=2)
    )


def write_vercel_json(out: Path):
    """Next.js handles routing natively; deploy skill reads this if present.
    Kept minimal — Next.js does not need SPA rewrites."""
    # Intentionally no rewrites for Next.js. Leave a marker file empty-safe.
    pass


def main():
    ap = argparse.ArgumentParser(description="Scaffold a Fumadocs docs site under /docs")
    ap.add_argument("--product-id", required=True, help="Product id → subdomain {id}.example.com")
    ap.add_argument("--out", required=True, help="Output directory for the docs site")
    ap.add_argument("--pm", default="pnpm", choices=["pnpm", "npm", "yarn", "bun"])
    ap.add_argument("--title", default="", help="Human-facing product title (defaults to product-id)")
    args = ap.parse_args()

    product_id = slugify(args.product_id)
    if not product_id:
        sys.exit("ERROR: --product-id slugifies to empty")
    out = Path(os.path.expanduser(args.out)).resolve()

    scaffold(product_id, out, args.pm, args.title)


if __name__ == "__main__":
    main()