Understand how AI Docs organizes and renders the generated content, including markdown and UI components.
AI Docs automatically transforms your GitHub repositories into comprehensive, visually appealing documentation sites. Understanding how this documentation is structured, fetched, and displayed is key to leveraging AI Docs effectively. This page delves into the core mechanisms that render your generated content, from routing and data retrieval to interactive elements and custom Markdown extensions.
The overall structure of your documentation site is managed by the app/[domain]/layout.tsx file, which wraps all individual documentation pages within a DocsShell component. This shell provides the consistent elements of your documentation site:
This modular approach ensures a uniform user experience across all your documentation pages.
Each documentation page in AI Docs is dynamically routed based on its domain and slug. When a user navigates to a page, AI Docs performs several steps to retrieve and prepare the content:
https://[your-subdomain].docup.dev/[slug]. The [domain] and [...slug] parameters in the Next.js app/[domain]/[...slug]/page.tsx file capture the specific project and the requested documentation page.getDocData function efficiently fetches the necessary information from the database. This includes the project details, the specific documentation page's content (doc.content), and metadata for navigation (like previous and next pages). It also determines the user's subscription plan to enable or disable features like AI chat.unstable_cache is used to cache documentation data for 3600 seconds (1 hour) and allows for instant purging via revalidateTag when documentation is updated or regenerated. This means your users always see the latest content without waiting for caches to expire.generateMetadata creates SEO-friendly titles and descriptions based on the document's content, improving discoverability. This includes OpenGraph tags for social media sharing and JSON-LD for structured data.Here's a simplified flow of how a page request is handled:
The core of your documentation content is written in Markdown and rendered using the MarkdownRenderer component, found in components/mdx/markdown-renderer.tsx. This component leverages ReactMarkdown along with several plugins to transform raw Markdown into a rich, interactive web experience.
AI Docs fully supports standard Markdown syntax, including:
#, ##, ###, etc.)**bold**, *italic*)To provide a richer documentation experience, AI Docs extends standard Markdown with custom components that are automatically rendered from specific Markdown patterns:
Callouts: GitHub-style admonitions (e.g., > [!info]) are transformed into visually distinct callout boxes, drawing attention to important information, warnings, tips, or notes.
> [!tip]
> Remember to save your changes before deploying.
Code Tabs: Consecutive fenced code blocks with specific labels are rendered as interactive code tabs, allowing you to display code examples in multiple languages or configurations within a single block.
```typescript
// TypeScript example
function greet(name: string) {
console.log(`Hello, ${name}!`);
}
// JavaScript example
function greet(name) {
console.log(`Hello, ${name}!`);
}
Cards and Card Groups: You can create visually appealing card layouts for features, solutions, or related links. These are rendered from custom Markdown syntax that the AI generates.
<card-group data-cols="2">
<card data-title="Feature A" data-href="https://example.com/feature-a">
Description for feature A.
</card>
<card data-title="Feature B">
Description for feature B.
</card>
</card-group>
The stripJSXTags function in markdown-renderer.tsx is crucial. It converts specific Markdown patterns (like GitHub-style admonitions) into a format ReactMarkdown can process, and also ensures that any accidental JSX/HTML generated by the AI is removed to prevent rendering issues.
Code blocks are automatically highlighted for syntax based on the language specified (e.g., typescript, javascript, bash) using rehypeHighlight. Additionally, the Pre component (used for pre tags) can include an "Ask AI" button for Pro and Enterprise plan users, allowing them to query the AI about the code snippet directly.
The sidebar is your users' primary tool for navigating the documentation. AI Docs automatically organizes your generated pages into a logical, hierarchical structure. The app/[domain]/layout.tsx file is responsible for fetching the necessary documentation data (excluding content for efficiency) and structuring it for the sidebar.
Documentation pages are organized into distinct groups (e.g., "Getting Started", "API Reference", "Advanced Topics"). This grouping is determined during the AI generation process and is stored in the doc.group field. The layout.tsx file processes all generated documents, first grouping them by their group property.
AI Docs supports nested documentation structures. A page can be designated as a "child" of another page using the parentSlug property. This creates a clear hierarchy in the sidebar, allowing users to easily understand relationships between topics.
A powerful feature of AI Docs is its ability to automatically generate "virtual" sub-pages within the sidebar based on the H2 headings present in your Markdown content. If a top-level page does not have explicitly defined child pages, AI Docs will parse its metadata (specifically the headings array) to extract H2 headings. These headings then appear as clickable anchor links in the sidebar, allowing users to jump directly to specific sections within a long page. This enhances navigation without requiring additional AI generation or manual configuration.
Beyond content rendering, AI Docs enhances the user experience with several interactive features integrated into each documentation page:
TableOfContents): Automatically generated from the page's headings, providing quick navigation within the current document.order of pages within their respective groups.PageFeedback): Users can provide feedback on the helpfulness of a page, contributing to continuous improvement of your documentation.SelectionAskAI): For projects with AI Chat enabled (based on the Subscription Plans), users can highlight text and ask the AI questions directly within the documentation.CopyPageDropdown): A convenient button allows users to easily copy the entire content of a page.PageViewTracker): AI Docs tracks page views to provide analytics on documentation usage.To make the most of AI Docs' structure and display capabilities, consider these best practices when generating or manually editing your Markdown content:
H2, H3, and H4 headings. These not only improve readability but also contribute to the auto-generated Table of Contents and virtual sub-pages in the sidebar.By understanding these core concepts, you can effectively structure and display your documentation, providing an optimal experience for your users. For details on how to manage and customize your documentation pages, refer to Managing Documentation Pages.