write-gitbook

### When to Use This Skill Use this skill when working with GitBook documentation through: * Git-synced repositories (GitHub, GitLab) * Local markdown editors * IDE integrations * Command-line tools * Any environment where you're editing GitBook content as files rather than through the GitBook UI ### Quick Reference #### GitBook Content Structure GitBook organizes content through pages, spaces, and collections: * **Pages** are individual markdown files that make up your documentation * **Spaces** are collections of pages organized into a documentation site * **Collections** are groups of spaces **File structure:** ``` / .gitbook/ assets/ # GitBook-managed images and files includes/ # Reusable content blocks vars.yaml # Space-level variables .gitbook.yaml # Configuration README.md # Homepage SUMMARY.md # Table of contents getting-started/ # Section folder installation.md quickstart.md api-reference/ authentication.md endpoints.md ``` **Frontmatter fields:** ```markdown --- description: Page description for SEO icon: book-open hidden: true cover: .gitbook/assets/hero.png coverY: 0 vars: page_variable: value if: visitor.claims.unsigned.condition layout: width: default # or 'wide' cover: visible: true size: full # or 'hero' title: visible: true description: visible: true tableOfContents: visible: true outline: visible: true pagination: visible: true metadata: visible: true --- ``` **Variables and expressions:** * Space variables: `/.gitbook/vars.yaml` * Page variables: Frontmatter `vars:` * Expression syntax: `<code class="expression">space.vars.variableName</code>` **Most common custom blocks:** * `{% tabs %}...{% endtabs %}` for alternatives * `{% hint style="..." %}...{% endhint %}` for callouts * `{% stepper %}...{% endstepper %}` for sequential steps * `<details>...<summary>...</details>` for expandable content **Links:** * External: `[text](https://example.com)` * Internal (same space): relative paths — `[text](page.md)`, `[text](../folder/page.md)` * Cross-space: relative paths don't work across space boundaries. Use `https://app.gitbook.com/s/<spaceId>/<path>`. If the space ID isn't known yet, use an `XSPACE_<KEY>` sentinel — e.g. `[Auth](https://app.gitbook.com/s/XSPACE_API/authentication)` — and let `manage-gitbook-site` resolve it after space creation. **Key reminders:** * Read SUMMARY.md first when working with existing content to understand structure * Test in GitBook after editing locally * Keep SUMMARY.md synchronized with your file structure * Variables are defined in `.gitbook/vars.yaml` (space-level) or page frontmatter (page-level) * OpenAPI specs must be uploaded via API/CLI/UI, not embedded in markdown ### When to Use Which Block Choose the right GitBook block for your content needs: | Need | Use | Why | | ------------------------------------------ | --------------------------- | --------------------------------------------------------------------- | | Sequential, ordered instructions | `{% stepper %}` | Guides users through multi-step processes with clear progression | | Alternative options (languages, platforms) | `{% tabs %}` | Lets users choose their relevant option without cluttering the page | | Optional or detailed information | `<details>` (Expandable) | Keeps page scannable while providing depth for interested readers | | Important warnings or tips | `{% hint %}` | Draws attention with colored styling (info, warning, danger, success) | | Side-by-side comparisons | `{% columns %}` | Shows related information in parallel (max 2 columns) | | Timeline or changelog | `{% updates %}` | Displays dated entries in reverse chronological order | | Visual navigation cards | `<table data-view="cards">` | Creates clickable card grid for section navigation | | Downloadable files | `{% file %}` | Provides files with captions and descriptions | | Call-to-action links | `<a class="button">` | Highlights primary or secondary actions | | Reusable content across pages | `{% include %}` | Maintains consistency for repeated content blocks | | Dynamic content | `<code class="expression">` | Displays variable values that update automatically | **Variable scope decision:** | If variable is... | Define it as... | Access with... | | -------------------------- | ------------------------------------ | ------------------------- | | Used across multiple pages | Space-level in `/.gitbook/vars.yaml` | `space.vars.variableName` | | Specific to one page | Page-level in frontmatter `vars:` | `page.vars.variableName` | ### Working with Existing Content When working with an existing GitBook space that's synced to Git, follow this workflow to understand the structure: 1. **Read SUMMARY.md first** - This file contains the complete table of contents and navigation structure. It shows you: * All pages and their hierarchy * Page groups and organization * The relative paths to each markdown file 2. **If SUMMARY.md doesn't exist** - GitBook has inferred the structure from your directory layout. Browse the directory structure to understand how pages are organized. 3. **Check .gitbook.yaml** - Review this file to understand: * Where the root documentation directory is located * Any custom paths for README.md or SUMMARY.md * Existing redirects 4. **Explore .gitbook/assets/** - Contains all uploaded images and files referenced in the documentation 5. **Check .gitbook/vars.yaml** - Contains space-level variables if any are defined This approach ensures you understand the existing structure before making changes, helping you maintain consistency and avoid breaking internal links. ### Configuration Files #### .gitbook.yaml The `.gitbook.yaml` file configures your GitBook space. It should be placed at the root of your documentation directory (or in a subdirectory if using monorepos). **Basic structure:** ```yaml root: ./ structure: readme: ./README.md summary: ./SUMMARY.md redirects: old-page: new-page.md help: support.md ``` **Configuration options:** * `root`: The root directory for your documentation (default: `./`) * `structure.readme`: Path to your homepage (default: `./README.md`) * `structure.summary`: Path to your table of contents (default: `./SUMMARY.md`) * `redirects`: Key-value pairs mapping old URLs to new page paths **Monorepo support:** For repositories with multiple documentation projects: ``` / packages/ docs/ .gitbook.yaml README.md SUMMARY.md api/ .gitbook.yaml README.md SUMMARY.md ``` When setting up Git Sync, configure the "Project directory" to point to the subdirectory containing the `.gitbook.yaml` file. **Important notes:** * Paths in `.gitbook.yaml` are relative to the `root` option * Redirects defined here are space-specific (apply only to this space) * For site-wide redirects across multiple spaces, use the GitBook UI instead * When using Git Sync, manage the README file only through your repository to avoid conflicts ### The .gitbook Directory When using Git Sync, GitBook creates a `.gitbook` directory in your repository to store assets, variables, and generated content. **Directory structure:** ``` .gitbook/ assets/ # Uploaded images and files includes/ # Reusable content blocks (exported as individual .md files) vars.yaml # Space-level variables ``` **Important notes about .gitbook:** * **Assets**: Images and files uploaded through the GitBook UI are stored in `.gitbook/assets/` * **Reusable content**: Each reusable content block is exported as a separate markdown file in `.gitbook/includes/` * **Variables**: Space-level variables are stored in `.gitbook/vars.yaml` as key-value pairs * **References**: Pages reference reusable content using `{% include "/reusable-content/rc12345" %}` * **Images**: Markdown pages reference images like `` * **Table of contents**: The `.gitbook/includes` folder and its files may appear in your space's table of contents. You may need to manually hide them from the TOC if this happens. * **Location**: In monorepos, the `.gitbook` directory is created in the root of each synced space (not necessarily the repository root) #### SUMMARY.md The `SUMMARY.md` file defines your table of contents and navigation structure. It's a markdown file with a specific format that mirrors the sidebar navigation in GitBook. **Basic structure:** ```markdown # Summary ## Use headings to create page groups like this one * [First page's title](page1/README.md) * [Some child page](page1/page1-1.md) * [Some other child page](page1/page1-2.md) * [Second page's title](page2/README.md) * [Some child page](page2/page2-1.md) * [Some other child page](page2/page2-2.md) ## A second page group * [Another page](another-page.md) ``` **Key rules:** * Use `#` for the main title (commonly "Table of contents" or "Summary") * Use `##` headings to create page groups (section headers in the sidebar) * Use `*` for unordered lists to define pages and subpages * Indent with spaces (not tabs) to create nested/child pages * Each list item should be a markdown link: `[Link text](path/to/file.md)` * Paths are relative to the location specified in `.gitbook.yaml` (typically the root) **Page link titles (optional):** You can define a different title for the sidebar navigation versus the page itself: ```markdown # Summary * [Page main title](page.md "Page link title") ``` The text in quotes ("Page link title") will be used in: * The table of contents sidebar * Pagination buttons at the bottom of pages * Any relative links to that page **Important notes:** * SUMMARY.md is optional. If not provided, GitBook infers structure from your folder hierarchy * You cannot reference the same markdown file twice in SUMMARY.md (each page has only one URL) * GitBook updates SUMMARY.md automatically when you edit through the GitBook UI * The file structure reflects exactly what users see in the navigation sidebar ### Markdown Formatting GitBook uses GitHub Flavored Markdown with custom extensions. **Standard markdown:** ```markdown # Heading 1 ## Heading 2 ### Heading 3 **bold text** *italic text* `inline code` - Bullet list item - Another item - Nested item 1. Numbered list 2. Second item [Link text](https://example.com) [Internal link](getting-started.md) ``` **Code blocks:** ````markdown ```javascript const foo = 'bar'; console.log(foo); ``` ```` **Code blocks with titles:** ````markdown {% code title="index.js" %} ```javascript const foo = 'bar'; console.log(foo); ``` {% endcode %} ```` **Inline links:** * External links: `[text](https://example.com)` * Internal pages: Use relative file paths like `[text](page.md)`, `[text](../folder/page.md)`, or `[text](subfolder/page.md)` * Email: `[text](mailto:email@example.com)` **Math/TeX:** ```markdown Inline formula: $$E = mc^2$$ Block formula: $$ E = mc^2 $$ ``` **Mermaid diagrams:** Any fenced code block with `mermaid` as the language renders as a diagram. Use Mermaid any time you'd otherwise reach for ASCII art or describe a relationship in prose where a picture would help. ````markdown ```mermaid flowchart LR Pending --> Authorized --> Captured Pending -.->|declined| Failed Authorized -.->|voided| Voided Captured -.->|refund| Refunded ``` ```mermaid sequenceDiagram Client->>Auth: POST /token Auth-->>Client: access_token ``` ```mermaid stateDiagram-v2 [*] --> Draft Draft --> Review Review --> Published Review --> Draft ``` ```mermaid erDiagram USER ||--o{ ORDER : places ORDER ||--|{ LINE_ITEM : contains ``` ````