A starter template for creating documentation sites with Basedoc. Fork this repo and start writing docs in minutes.
- Fork this repository (or click "Use this template" on GitHub)
- Connect to Basedoc at basedoc.co and link your forked repo
- Edit the docs at the project root and push your changes — your site updates automatically
This repo includes AGENTS.md so coding agents know this is a Basedoc site. For best results when editing docs or basedoc.json, install the writing-basedoc-docs skill from docslab-co/basedoc-skills using --skill writing-basedoc-docs (full steps are in that repository’s README). Then ask your agent to update the docs.
This is an example project, with an index and root-level pages, plus an API docs section and a Guides directory.
Any media for logos or post content should be in the media directory.
├── basedoc.json # Site configuration
├── index.mdx # Homepage
├── getting-started.mdx # Getting started guide
├── concepts.mdx # Core concepts
├── guides/
│ ├── installation.mdx # Installation guide
│ └── deployment.mdx # Deployment guide
├── api/
│ ├── overview.mdx # API overview (regular page)
│ ├── list-users.mdx # GET /v1/users endpoint
│ ├── create-user.mdx # POST /v1/users endpoint
│ ├── get-user.mdx # GET /v1/users/{userId} endpoint
│ └── schemas/
│ ├── user.mdx # User schema definition
│ └── create-user.mdx # CreateUser schema definition
└── media/ # Images, logos, favicons
Edit basedoc.json to customize your site:
{
"title": "Your Site Name",
"description": "Your site description",
"logo": {
"lightMode": "/media/logo.png",
"darkMode": "/media/logo-dark.png"
},
"highlightColors": {
"lightMode": "#4F46E5",
"darkMode": "#818CF8"
},
"navigation": [...]
}| Field | Description |
|---|---|
title |
Site name shown in the header |
description |
Site description for SEO |
logo |
Logo images for light and dark mode |
highlightColors |
Brand accent colors for light and dark mode |
navigation |
Sidebar navigation structure |
api.custom.serverUrl |
Base URL shown in API endpoint docs |
externalLinks |
Links displayed in the header (e.g. GitHub) |
See the full schema for all available options.
Create .mdx or .md files at the project root (or in subfolders). Each page needs YAML frontmatter:
---
title: My Page Title
description: A brief description of this page
---
# My Page Title
Your content here. Supports full Markdown and MDX.| Field | Required | Description |
|---|---|---|
title |
Yes | Page title (used in head and navigation) |
description |
No | Page description (meta tag / subtitle) |
Add your page to the navigation array in basedoc.json:
{
"navigation": [
"my-page",
{
"title": "Section Name",
"pages": ["section/page-one", "section/page-two"]
}
]
}Navigation items can be:
- A string (page path from the project root, without extension)
- An object with
titleandpathfor custom display names - An object with
titleandpagesfor grouped sections
API endpoint pages use special frontmatter under the api.endpoint key.
---
api:
endpoint:
get /v1/resource:
summary: Short description of the endpoint
auth: bearer
params:
path:
id: string
query:
limit?: number
responses:
200:
description: Success
schema: MySchema
example:
id: abc123
name: Example
---
## Overview
<Endpoint />
## Request parameters
<Params />
## Request body
<Body />
## Request examples
<RequestExamples />
## Responses
<Responses />Use these MDX components in your API docs pages:
| Component | Description |
|---|---|
<Endpoint /> |
HTTP method, path, summary, auth |
<Params /> |
All parameters |
<Params location="query" /> |
Parameters filtered by location |
<Body /> |
Request body fields |
<Responses /> |
All responses |
<Response code="200" /> |
A single response |
Define reusable schemas in api/schemas/:
---
api:
schema: MySchema
---
id: string
Unique identifier
name: string
Display name
createdAt: datetime
When the resource was created
optionalField?: string
This field is optional (note the `?`)Each line is fieldName: type (required) or fieldName?: type (optional). Lines below a field definition become its description.
Reference schemas in endpoint pages with schema: MySchema in request body or response definitions.
Place images in the media/ folder and reference them in your pages:
Add your logo files to media/ and update basedoc.json accordingly.
