Docs as Code

Docs as Code

Point Folio at the docs/ folder of a product repository and it becomes a wiki the whole team edits in the browser. The docs stay Markdown in the same repository. Developers keep their IDE and read ordinary commits with the editor's name as author. An agent can edit the same pages.

Set it up

1. Create a token that can read and write the repository (Git access in the user menu).
2. New space, From a git repository: repository URL and the branch the space will follow.
3. Root path inside the repository: type docs, or pick the folder from the repository's folder tree. Only that folder becomes the space.
4. Create the space. Folio clones the repository (a partial clone) and indexes the Markdown files as pages. A README.md becomes the page of its folder when there is no index.md.

Several spaces can share one repository with different root paths.

What is preserved

• Everything outside the folder. Source code and other files are not pages and are never touched.
• Your front matter. Keys from Docusaurus, MkDocs, Hugo or Jekyll (title, sidebar_position, slug, tags, description and others), comments and quoting stay byte for byte when a page is saved, copied or duplicated.
• No ids in your files. A space bound to a folder writes no id; ids live in Folio's index. The one file Folio adds is a hidden docs/.<slug>.folio.
• Links. Moving or renaming a page rewrites the relative links inside it and the links to it from other pages, in one commit.
• Images can live in the repository: a space admin turns on Store images in the repository, and new pasted images go to docs/assets/, linked by a relative path so GitHub shows them.

How edits reach Git

A writer edits in Reading, Live edit or Source, alone or with colleagues, or asks Folio AI in the side panel. Folio writes each edit to the file at once and commits about 90 seconds after the space goes quiet, or immediately on Sync, to the branch the space follows. In git log the author is the person who edited; Folio is the committer and the message is folio:update. Developers' own commits come back by fetch about every three minutes and on every Sync.

Agents work the same pages over MCP with the rights of the token's owner; the commit carries that person's name.

Review before main

A space follows exactly one branch and Folio pushes straight to it, without pull requests. For review, point the space at a docs branch and merge it as you merge anything else. A protected branch makes the push fail; the space shows git's message.

Limits

• A space over the whole repository (no root path) writes an id into every page that lacks one and a small file into the repository root, unless an administrator ticks Light footprint.
• MDX files (.mdx) are not pages.
• A page's title comes from its first # heading, then front matter title:, then the file name. Folio adds no heading to a page without one.
• Pasted images stay in Folio's asset store until the repository option is on; they do not show on GitHub meanwhile.
• Link rewriting covers [text](path) links and images, not HTML tags or reference-style links.
• Folio's Markdown extras (status tags, highlights, underline, page-tree) may show as plain text in other renderers.
• Agents cannot delete or move pages or change access.
• No pull requests, versioned docs or content i18n.

Publish it

Make the space public and the same pages are served as a read-only docs site with search (Publish a Public Website).

See also

Blog: docs-as-code in the browser · Video · README section · Set Up Folio AI