DOCSEARCHbyAlgolia
Submit Docs

docs.page Documentation

repository·main·Indexed 20 days ago

https://github.com/invertase/docs.page

A platform that serves markdown from public GitHub branches as modern, agent-ready documentation sites. Features include Git-based publishing, MDX support, intelligent search, and a CLI (@docs.page/cli) for project initialization, validation, local previewing, and managing documentation agents via providers like OpenAI, Anthropic, Google, and xAI.

Tokens
68.9K
Snippets
232
Records
386
Agent score
69%

What's inside docs.page

  1. Overview of docs.page features

    main

    docs.page provides a platform for serving markdown from public GitHub repositories as modern documentation sites. Key features include:

    • Agent-ready: Automatically generates an llms.txt file and provides an MCP server on every public site. Supports optional agent skills and 'Ask AI' (beta) for LLM querying.
    • Git publishing: Deploys updates directly from your public GitHub repository without requiring build pipelines or hosting configuration.
    • Intelligent search: Includes a built-in full-text index (accessible via Cmd+K) and embedded AI chat.
    • Markdown components: Supports MDX to add interactive components to your markdown files.
    • Branches & versions: Allows serving any Git branch, tag, or release as a distinct documentation site for versioning or staging previews.
    • Modern interface: Uses shadcn/ui design standards for styling and component customization.

  2. Overview of AI Agent surfaces in docs.page

    main

    docs.page provides multiple surfaces to make your documentation accessible to AI assistants without requiring manual scraping or separate mirrors. When your documentation is hosted in a public GitHub repository, most of these surfaces are available automatically.

    Available Surfaces

    SurfaceAvailabilityPurpose
    llms.txtAuto-generatedProvides a single HTTP-fetchable catalog of what exists in your docs.
    MCP serverOn by defaultAllows assistants (in editors or terminals) to list and read individual pages on demand.
    Agent skillsOptionalCustom repo-specific instructions/workflows stored in .agents/skills/.
    Ask AI (beta)Requires setupAn explicit, reader-facing in-docs chat panel on your production site.

    Key Concepts

    • Discovery vs. Interactive Read: Use llms.txt when an HTTP client needs a quick catalog of your content. Use the MCP server when an agent is working within an editor or terminal session and needs to fetch specific pages.
    • Data Sync: All surfaces read directly from your public GitHub repository. Updates to your MDX files are reflected in these agent surfaces on the next request.

  3. Summary of docs.page CLI commands

    main

    The @docs.page/cli provides four primary commands to manage your documentation workflow:

    CommandRole
    docs initCreate docs.json and optional starter pages in a new or existing repo
    docs previewWatch local files and render changes in the docs.page preview UI
    docs checkLint configuration, links, and assets: a quality gate before you push
    docs agentCreate or delete the in-docs chat agent for a repository

  4. Overview of the docs.page MCP server

    main

    docs.page runs a Model Context Protocol (MCP) server for every hosted repository. This allows AI assistants (like Cursor or Claude) to discover pages and read raw MDX source files directly, rather than relying on HTML scraping. This ensures agents use the exact wording, examples, and structure published by your team.

    Each site has its own MCP endpoint scoped to the repository's owner, name, and optional ref (branch, commit, or PR). The server is read-only and does not have write access to your GitHub repo or docs.json.

  5. Understand docs.page URL patterns

    main

    docs.page uses a predictable URL structure based on your GitHub repository. Page URLs mirror the file structure under the docs/ directory.

    File to URL Mapping:

    • docs/index.mdx maps to /
    • docs/next-steps.mdx maps to /next-steps
    • docs/guides/setup/index.mdx maps to /guides/setup

    Production and Ref URLs:

    • Default (Production): Uses the repository's default branch: https://docs.page/{owner}/{repo}/{page-path}
    • Ref URLs: Use a ~{ref} segment to preview specific branches, commits, or pull requests: https://docs.page/{owner}/{repo}~{ref}/{page-path}

    Ref Segment Mapping:

    • ~feature-docs: Resolves to branch feature-docs
    • ~abc123... (40-char SHA): Resolves to that specific commit
    • ~42: Resolves to the head branch of pull request #42
    https://docs.page/{owner}/{repo}~{ref}/{page-path}

  6. Nest callouts inside other components

    main

    Callout components are compatible with other UI containers. You can nest them inside components like <Tabs>, <Accordion>, or <Steps> to provide emphasized detail within a specific section or step.

    <Accordion title="Webhook troubleshooting">
  If events do not arrive, check the delivery log in your repository settings.

  <Warning>
    Webhook secrets rotate when you reconnect a repository. Update the secret in any external integrations.
  </Warning>
</Accordion>

  7. Manage typography and fonts

    main

    Typography is managed via presets. You cannot configure specific font families directly in docs.json. Instead, when you set a theme.preset, docs.page automatically loads the corresponding Google Fonts for the body (--font-sans) and headings (--font-heading).

    To change your site's fonts, you must switch to a different preset code from the shadcn/ui registry that uses the typefaces you prefer.

  8. How the docs.page MCP server works

    main

    The docs.page MCP server provides a read-only, streamable HTTP endpoint scoped to your repository. It allows agents to interact with your documentation via specific tools and resources.

    MCP Endpoint URL

    The endpoint follows this pattern: https://docs.page/{owner}/{repo}/mcp

    For branch or pull request previews, use the ~ref segment: https://docs.page/{owner}/{repo}~ref/{branch_or_pr}/mcp

    Available Tools

    Agents use these tools to navigate and read your documentation:

    • list_doc_files: Returns a list of .mdx pages available in the current repository context.
    • read_doc_page: Fetches the raw MDX source for a specific path (e.g., docs/getting-started.mdx). Note that this returns raw source text, not HTML, ensuring predictable token usage and accurate citations.

    Available Resources

    The server also exposes the following MCP resources:

    • docs-page-config-schema: The JSON schema used for docs.json.
    • Agent Skills: If your repository contains .agents/skills/**, each SKILL.md file is exposed as a markdown resource.

  9. Compare Custom Domains and Vanity Subdomains

    main

    Depending on your branding needs, you can choose between two ways to shorten your documentation URLs:

    1. Custom Domains: Use a hostname you own entirely (e.g., docs.example.com). This requires DNS configuration and manual setup by the docs.page team. It removes the owner/repo segments from the path.
    2. Vanity Subdomains: Use a subdomain of the docs.page host (e.g., {owner}.docs.page). This is a self-serve option that requires no DNS changes and is available immediately. It shortens the path but keeps the docs.page hostname.

  10. How Mermaid diagrams behave and handle errors

    main

    Mermaid diagrams are rendered in the browser after the page loads.

    • Rendering: If the syntax is valid, the diagram renders automatically.
    • Error Handling: If the diagram syntax is invalid, docs.page will display the specific Mermaid error message alongside the original source code so you can identify and fix the syntax issue.

  11. Understand light and dark mode behavior

    main

    docs.page supports both light and dark modes, toggled via a theme toggle in the site header. The system uses a dark class on the document root to switch between CSS token values defined in the preset or your custom overrides.

    Note on defaultTheme: While the theme block accepts a defaultTheme key ('light' or 'dark'), this is currently schema only. Readers will continue to see the platform default (based on their system settings) until full support for pinning the starting mode is implemented.