Documentation Configuration
How to configure docs tabs, sidebars, and site metadata for the OpenQuok documentation site.
Connect your agent today
Draft from chat, review in your calendar, and publish only what you approve.
Site Configuration
Edit the docs config in:
- web/src/lib/docs/constants/config.ts — site metadata, docsTabs (one sidebar per tab), i18n, optional docsMcpPath (relative path to the documentation MCP typically /mcp)
- web/src/lib/docs/constants/config.ts — assembled docsConfig (merged sidebar, and TOC defaults)
Two MCP servers
docsMcpPath enables Copy MCP URL and Connect to Cursor on docs pages and powers the documentation MCP (search_docs, read_page, …) on the web host. Workspace scheduling MCP stays on the API at BACKEND_DOMAIN_URL/mcp with an opo_ key — see MCP overview.
The header tab bar is docsTabs, left to right: General, Cloud, Self-hosting, CLI, MCP, Public API, Add OpenQuok to your app, Contributing.
Note
/docs loads the General introduction (the /getting-started folder) without redirecting. The same page is also available at /docs/getting-started. Do not treat a root docs/index.md as the tab home.
export const docsTabs: DocsTabDefinition[] = [
{ id: 'general', label: 'General', sidebar: docsSidebarGeneral },
{ id: 'cloud', label: 'Cloud', sidebar: docsSidebarCloud },
{ id: 'self-hosting', label: 'Self-hosting', sidebar: docsSidebarSelfHosting },
{ id: 'cli', label: 'CLI', sidebar: docsSidebarCli },
{ id: 'mcp', label: 'MCP', sidebar: docsSidebarMcp },
{ id: 'public-api', label: 'Public API', sidebar: docsSidebarPublicApi },
{ id: 'oauth-for-apps', label: 'Add OpenQuok to your app', sidebar: docsSidebarOAuthForApps },
{ id: 'contributing', label: 'Contributing', sidebar: docsSidebarContributing }
];
export const docsConfig: DocsConfig = {
site: docsSite,
sidebar: docsSidebarMerged, // flattened from docsTabs (search, prev/next, llms.txt)
tabs: docsTabs,
toc: {
minDepth: 2,
maxDepth: 3
}
};| Tab | Sidebar constant | Tab home |
|---|---|---|
| General | docsSidebarGeneral (getting-started) | /docs |
| Cloud | docsSidebarCloud | /docs/cloud |
| Self-hosting | docsSidebarSelfHosting | /docs/getting-started-for-dev |
| CLI | docsSidebarCli | /docs/getting-started-for-cli |
| MCP | docsSidebarMcp | /docs/getting-started-for-mcp |
| Public API | docsSidebarPublicApi | /docs/getting-started-for-public-api |
| Add OpenQuok to your app | docsSidebarOAuthForApps (oauth2-for-apps) | /docs/oauth2-for-apps |
| Contributing | docsSidebarContributing | /docs/developer-guidelines |
Third-party app OAuth lives on the Add OpenQuok to your app tab. Operator OAuth server setup stays under Self-hosting (admin).
Path matching lives in web/src/lib/docs/navigation.ts. Unknown slugs resolve to General, not Self-hosting.
Sidebar Configuration
Auto-generated Sections
Use autogenerate to build sidebar sections from a directory. Attach each section to the tab that should show it:
export const docsSidebarGeneral: DocsSidebarSection[] = [
{
label: 'Get started',
autogenerate: { directory: 'getting-started' }
},
{
label: 'Channels',
autogenerate: { directory: 'channels' }
}
];This scans src/content/docs/getting-started/ and creates nav items for each .md file.
Manual Sections
You can also define items manually:
{
label: 'Resources',
items: [
{ label: 'GitHub', href: 'https://github.com' },
{ label: 'Discord', href: 'https://discord.gg/example' }
]
}Frontmatter Options
Each markdown file supports these frontmatter fields:
---
title: Page Title # Required — displayed as the page heading
description: A summary # Optional — shown below the title and in meta tags
order: 1 # Optional — controls sidebar ordering (lower = higher)
draft: true # Optional — hides the page from navigation
sidebar:
label: Custom Label # Optional — overrides the title in the sidebar
---