Aller au contenu principal

What gets committed

Your repo only ever contains files you actually authored. The rendering engine, build configs, and Docsio internals stay on our side.

What's in the repo

<configured-path>/                    (root, or a subdirectory you set)
├── docsio.json                       theme + nav config
├── README.md                         auto-seeded once with a brief intro
├── .docsioignore                     documents what we explicitly skip
├── docs/
│   ├── intro.mdx
│   └── <category>/
│       ├── _category_.json           sidebar label + position
│       └── <slug>.md
└── static/
    └── img/
        ├── logo.svg
        ├── favicon.svg
        └── ...                       any image you've uploaded

That's the entire scope. Five things:

  1. Markdown pages (.md, .mdx) at any path under docs/.
  2. Sidebar metadata (_category_.json) inside category folders.
  3. Uploaded images in static/img/.
  4. docsio.json — small declarative config: primary color, nav overrides, theme tokens.
  5. README.md and .docsioignore — auto-seeded once on the initial commit.

What's NOT in the repo

  • The rendering engine and any Docsio internals
  • Build artifacts (node_modules, build/, .cache/)
  • Generated configs (the actual rendered theme, computed sidebars, etc.)
  • Custom React components from the template — those live inside Docsio
  • Internal state (versioning data, sandbox metadata, search indices)

If you ls your connected repo, you'll see ~5-30 files depending on docs size. Clean.

Why the strict allowlist

Two reasons:

  1. Your repo stays focused. It's your docs content, not a build pipeline you have to maintain. If you rename a Docsio internal at some point, your repo isn't littered with files it doesn't control.
  2. Safety. A bug in our sync code can't corrupt or pollute your repo with unintended files. Even if our code somehow tried, the allowlist refuses.

Reading from the repo

When git pushes happen and Docsio pulls them, the same allowlist applies in reverse:

  • docs/**/*.md and docs/**/*.mdx — read in.
  • docs/**/_category_.json — read in.
  • static/img/** — read in.
  • docsio.json — read in.

Anything else in the repo is ignored. If a teammate adds package.json, .github/workflows/, CONTRIBUTING.md, etc. — Docsio doesn't try to render them. They live in your repo as you intend, without affecting your docs site.

.docsioignore

The .docsioignore file at the repo root is informational — it documents what Docsio skips so anyone reading the repo knows. It looks like:

# Docsio explicitly skips these — they're allowed in your repo but not synced
node_modules/
build/
.next/
*.test.md

You can add patterns, but the server-side allowlist is the real source of truth. The file is a hint, not a config.

Subdirectory mode

If you set a subdirectory (e.g. docs/) when connecting, the allowlist applies relative to that path:

your-app/                             your repo root
├── src/                              your app code (Docsio doesn't touch)
├── package.json                      Docsio doesn't touch
└── docs/                             configured Docsio subdirectory
    ├── docsio.json
    ├── README.md
    ├── docs/
    └── static/img/

Your app code stays at the root, untouched. Only files under docs/ are read or written.

Asset URLs in markdown

When you reference an image in markdown:

![Architecture](/img/architecture.png)

Docsio resolves /img/architecture.png to your project's static/img/architecture.png at render time. Same syntax works in both the editor and in git.

Common patterns

  • Mixed repo (app + docs). Use a subdirectory like docs/ so your app code stays at the root.
  • Dedicated docs repo. Don't use a subdirectory — let Docsio commit to root.
  • Migrating from Mintlify or GitBook. Their formats overlap a lot with Docsio's. Bring the markdown files in via GitHub → Docsio direction; you'll likely need light cleanup of frontmatter.

Next