@cleocode/cleo 2026.2.5 → 2026.2.7

package/packages/ct-skills/skills/ct-gitbook/references/content-blocks.md

@@ -0,0 +1,230 @@
+# Content Blocks Reference
+
+Content types, OpenAPI integration, embeds, and Markdown extensions in GitBook.
+
+## Overview
+
+GitBook's block-based editor supports rich content beyond standard Markdown. When using Git Sync, special syntax and templates map to these blocks.
+
+## Block Types
+
+### Code Blocks
+
+Standard fenced code blocks with syntax highlighting:
+
+````markdown
+```typescript
+const x = 42;
+```
+````
+
+**Code tabs** — multiple language examples in a single block:
+
+```markdown
+{% tabs %}
+{% tab title="TypeScript" %}
+```typescript
+const client = new GitBookAPI({ authToken: token });
+```
+{% endtab %}
+{% tab title="cURL" %}
+```bash
+curl -H "Authorization: Bearer $TOKEN" https://api.gitbook.com/v1/user
+```
+{% endtab %}
+{% endtabs %}
+```
+
+### Hints (Callouts)
+
+```markdown
+{% hint style="info" %}
+This is an informational callout.
+{% endhint %}
+
+{% hint style="warning" %}
+Proceed with caution.
+{% endhint %}
+
+{% hint style="success" %}
+Operation completed successfully.
+{% endhint %}
+
+{% hint style="danger" %}
+This action is irreversible.
+{% endhint %}
+```
+
+Available styles: `info`, `warning`, `success`, `danger`.
+
+### Tabs
+
+```markdown
+{% tabs %}
+{% tab title="macOS" %}
+Installation instructions for macOS.
+{% endtab %}
+{% tab title="Linux" %}
+Installation instructions for Linux.
+{% endtab %}
+{% tab title="Windows" %}
+Installation instructions for Windows.
+{% endtab %}
+{% endtabs %}
+```
+
+### Expandable Sections
+
+```markdown
+<details>
+<summary>Click to expand</summary>
+
+Hidden content goes here. Supports full Markdown.
+
+</details>
+```
+
+### Cards
+
+Link cards with optional images, rendered as visual previews:
+
+```markdown
+{% content-ref url="getting-started.md" %}
+[getting-started.md](getting-started.md)
+{% endcontent-ref %}
+```
+
+### Embedded URLs
+
+Auto-expanding embeds for supported services:
+
+```markdown
+{% embed url="https://www.youtube.com/watch?v=VIDEO_ID" %}
+YouTube video title
+{% endembed %}
+
+{% embed url="https://www.figma.com/file/FILE_ID" %}
+Figma design
+{% endembed %}
+```
+
+Supported embed providers include YouTube, Vimeo, Figma, CodePen, Loom, Google Drive, and others.
+
+### Math (LaTeX)
+
+Inline math: `$$E = mc^2$$`
+
+Block math:
+
+```markdown
+$$
+\int_0^\infty e^{-x^2} dx = \frac{\sqrt{\pi}}{2}
+$$
+```
+
+### Files
+
+Attach downloadable files:
+
+```markdown
+{% file src=".gitbook/assets/report.pdf" %}
+Download the full report
+{% endfile %}
+```
+
+### Drawings
+
+Created in the GitBook editor's built-in drawing tool. These are stored as SVG assets and referenced in the page content. Not editable via Git Sync — use the editor.
+
+### Tables
+
+Standard Markdown tables:
+
+```markdown
+| Header 1 | Header 2 | Header 3 |
+|----------|----------|----------|
+| Cell 1   | Cell 2   | Cell 3   |
+| Cell 4   | Cell 5   | Cell 6   |
+```
+
+### Images
+
+```markdown
+![Alt text](path/to/image.png)
+
+<!-- With caption -->
+<figure><img src="path/to/image.png" alt="Description"><figcaption>Caption text</figcaption></figure>
+```
+
+Image paths in Git Sync should be relative to the page file or use `.gitbook/assets/` for shared assets.
+
+## OpenAPI Integration
+
+GitBook renders OpenAPI (Swagger) specifications as interactive API reference pages.
+
+### Methods
+
+**1. URL reference in the editor:**
+Paste an OpenAPI spec URL in the editor. GitBook fetches and renders it.
+
+**2. File in Git Sync:**
+Place `.yaml` or `.json` OpenAPI files in your repository. Reference them in pages:
+
+```markdown
+{% swagger src="./openapi.yaml" path="/users" method="get" %}
+[openapi.yaml](openapi.yaml)
+{% endswagger %}
+```
+
+**3. Inline specification:**
+Paste the full spec inline (not recommended for large specs).
+
+### Rendered Output
+
+GitBook generates:
+- Endpoint listings with method badges (GET, POST, etc.)
+- Request/response schemas with type information
+- Try-it-out functionality for testing endpoints
+- Authentication configuration display
+- Parameter descriptions and examples
+
+### Supported Versions
+
+- OpenAPI 3.0.x
+- OpenAPI 3.1.x
+- Swagger 2.0 (converted internally)
+
+## Markdown Extensions Summary
+
+| Syntax | Renders As |
+|--------|------------|
+| `{% hint style="..." %}` | Callout box |
+| `{% tabs %}` / `{% tab %}` | Tabbed content |
+| `{% embed url="..." %}` | Rich embed |
+| `{% swagger src="..." %}` | API reference |
+| `{% content-ref url="..." %}` | Link card |
+| `{% file src="..." %}` | File download |
+| `$$...$$` | Math equation |
+| `<details>` / `<summary>` | Expandable section |
+
+## Assets Directory
+
+Git-synced repos store uploaded assets in `.gitbook/assets/`:
+
+```
+docs/
+├── .gitbook/
+│   └── assets/
+│       ├── logo.png
+│       └── diagram.svg
+├── README.md
+└── SUMMARY.md
+```
+
+Reference assets with relative paths from the page: `../.gitbook/assets/logo.png` or absolute from root: `.gitbook/assets/logo.png`.
+
+## Resources
+
+- **Content Editor**: https://docs.gitbook.com/content-editor
+- **OpenAPI**: https://docs.gitbook.com/integrations/openapi
+- **Markdown**: https://docs.gitbook.com/content-editor/editing-content/markdown

package/packages/ct-skills/skills/ct-gitbook/references/docs-sites.md

@@ -0,0 +1,202 @@
+# Docs Sites Reference
+
+Publishing, Site Sections, custom domains, content variants, and SEO for GitBook Docs Sites.
+
+## Overview
+
+A **Docs Site** is the published, visitor-facing representation of your documentation. Sites can combine multiple spaces via Site Sections, apply custom branding, use custom domains, and serve versioned content through variants.
+
+## Creating a Docs Site
+
+### Via UI
+
+1. Navigate to your organization dashboard
+2. Click **New site**
+3. Choose a name and link your first space
+4. Configure audience (public, authenticated, or private)
+
+### Via API
+
+```typescript
+const site = await client.orgs.createSite(orgId, {
+  title: 'Developer Documentation',
+});
+```
+
+## Site Sections
+
+Site Sections combine multiple spaces into a single site with tab-based or dropdown navigation.
+
+### Adding Sections
+
+```typescript
+// Add individual sections
+await client.sites.addSiteSection(siteId, {
+  spaceId: apiDocsSpaceId,
+  title: 'API Reference',
+});
+
+await client.sites.addSiteSection(siteId, {
+  spaceId: guidesSpaceId,
+  title: 'Guides',
+});
+```
+
+### Section Groups
+
+Group sections under a dropdown heading:
+
+```typescript
+await client.sites.addSiteSectionGroup(siteId, {
+  title: 'Products',
+  sections: [productASection, productBSection],
+});
+```
+
+### Nested Groups
+
+Since September 2025, GitBook supports **nested section groups** — groups within groups. This enables hierarchical navigation like:
+
+```
+Products (dropdown)
+├── Platform
+│   ├── API Reference
+│   └── SDK Guide
+└── Tools
+    ├── CLI Reference
+    └── Plugin Guide
+```
+
+### Section Settings
+
+Each section can have:
+- **Title**: Display name in the navigation tab
+- **Icon**: Optional icon next to the title
+- **Description**: Shown in dropdown menus for grouped sections
+
+## Custom Domains
+
+### Setup
+
+1. Add a CNAME DNS record: `docs.example.com → hosting.gitbook.io`
+2. Configure in site settings or via API:
+
+```typescript
+await client.sites.updateSiteCustomization(siteId, {
+  hostname: 'docs.example.com',
+});
+```
+
+3. GitBook provisions an SSL certificate automatically
+
+### Multiple Domains
+
+Each site supports one custom domain. For multiple domains, create separate sites or use DNS-level redirects.
+
+## Branding & Customization
+
+```typescript
+await client.sites.updateSiteCustomization(siteId, {
+  // Colors and fonts
+  styling: {
+    primaryColor: '#0066FF',
+    font: 'Inter', // Inter, Roboto, Poppins, etc.
+  },
+
+  // Theme
+  themes: {
+    default: 'light', // light | dark
+    toggleable: true,  // Allow visitors to toggle
+  },
+
+  // Logos
+  favicon: 'https://example.com/favicon.ico',
+  logo: {
+    light: 'https://example.com/logo-light.png',
+    dark: 'https://example.com/logo-dark.png',
+  },
+});
+```
+
+### Customizable Elements
+
+| Element | Options |
+|---------|---------|
+| Primary color | Any hex color |
+| Font family | Inter, Roboto, Poppins, Source Sans Pro, and others |
+| Theme | Light, dark, or toggleable |
+| Logo | Separate light/dark variants |
+| Favicon | Custom favicon URL |
+| Header links | Custom navigation links |
+| Footer | Custom footer content |
+
+## Content Variants
+
+Variants maintain multiple versions of content within a single space.
+
+### Use Cases
+
+- API version documentation (v1, v2, v3)
+- Product editions (Community, Enterprise)
+- Language variants (en, fr, de)
+
+### Creating Variants
+
+```typescript
+// Create version variants
+await client.spaces.createVariant(spaceId, { title: 'v1.0', slug: 'v1' });
+await client.spaces.createVariant(spaceId, { title: 'v2.0', slug: 'v2' });
+
+// Set the default variant visitors see
+await client.spaces.setDefaultVariant(spaceId, v2VariantId);
+```
+
+### Variant URLs
+
+Variants are accessible via slug in the URL:
+
+```
+https://docs.example.com/v1/getting-started
+https://docs.example.com/v2/getting-started
+```
+
+The default variant is served at the root URL without a slug prefix.
+
+### Variant vs. Site Sections
+
+| Feature | Variants | Site Sections |
+|---------|----------|---------------|
+| Content | Same space, different versions | Different spaces |
+| Navigation | Version dropdown | Top-level tabs |
+| Use case | Versioned docs | Multi-product docs |
+| URL pattern | `/v2/page` | `/section/page` |
+
+## SEO
+
+GitBook generates SEO-friendly output automatically:
+
+- **Sitemaps**: Auto-generated at `/sitemap.xml`
+- **Open Graph**: Meta tags for social sharing
+- **Structured data**: JSON-LD for search engines
+- **Clean URLs**: Slug-based paths without file extensions
+- **Meta descriptions**: Set per page in the editor
+- **Canonical URLs**: Automatically set for custom domains
+
+### Custom Meta
+
+Set per-page descriptions in the GitBook editor via the page settings panel. These appear in search engine results.
+
+## Audience Settings
+
+| Setting | Description |
+|---------|-------------|
+| Public | Anyone can view |
+| Authenticated | Requires login via visitor auth provider |
+| Private | Only organization members |
+
+## Resources
+
+- **Docs Sites**: https://gitbook.com/docs/publishing-documentation
+- **Site Sections**: https://gitbook.com/docs/publishing-documentation/site-structure/site-sections
+- **Custom Domains**: https://docs.gitbook.com/publishing-documentation/custom-domain
+- **Customization**: https://docs.gitbook.com/publishing-documentation/customization

package/packages/ct-skills/skills/ct-gitbook/references/git-sync.md

@@ -0,0 +1,175 @@
+# Git Sync Reference
+
+Bidirectional synchronization between a Git repository (GitHub or GitLab) and a GitBook space.
+
+## Overview
+
+Git Sync connects a GitBook space to a branch in your repository. Edits in either location are synced to the other. The GitHub App integration handles webhooks and authentication.
+
+## Setup
+
+### GitHub Integration
+
+1. Open your space in GitBook
+2. Navigate to **Integrations > Git Sync**
+3. Click **Connect with GitHub** — installs the GitBook GitHub App
+4. Select the repository and branch
+5. Choose sync direction: **GitHub to GitBook**, **GitBook to GitHub**, or **Bidirectional**
+
+### GitLab Integration
+
+1. Navigate to **Integrations > Git Sync**
+2. Click **Connect with GitLab**
+3. Provide a GitLab personal access token with `api` scope
+4. Select the project and branch
+
+## .gitbook.yaml
+
+Optional configuration file at the repository root (or at the root specified by the `root` field).
+
+```yaml
+# Root directory for documentation (relative to repo root)
+root: ./docs/
+
+# Structure files
+structure:
+  readme: README.md    # Main page file name (default: README.md)
+  summary: SUMMARY.md  # Table of contents file (default: SUMMARY.md)
+
+# Redirects for moved/renamed pages
+redirects:
+  previous/page: current/page.md
+  old-guide: guides/new-guide.md
+```
+
+### Fields
+
+| Field | Default | Description |
+|-------|---------|-------------|
+| `root` | `./` | Root directory for docs content |
+| `structure.readme` | `README.md` | Filename for the space's main page |
+| `structure.summary` | `SUMMARY.md` | Filename for the table of contents |
+| `redirects` | — | Map of old paths to new paths |
+
+## SUMMARY.md
+
+Defines the page hierarchy and navigation structure. GitBook reads this file to determine the sidebar tree.
+
+### Format
+
+```markdown
+# Summary
+
+## Section Title
+
+* [Page Title](path/to/page.md)
+* [Another Page](path/to/another.md)
+  * [Nested Page](path/to/nested.md)
+    * [Deep Nested](path/to/deep.md)
+
+## Another Section
+
+* [Page](section2/page.md)
+```
+
+### Rules
+
+- Top-level `## Headings` create navigation groups
+- `* [Title](path.md)` creates a page link
+- Indentation (2 spaces) creates nesting
+- Maximum 3 levels of nesting recommended
+- Links must be relative paths from the `root` directory
+- Each linked file must exist or GitBook shows a warning
+- `README.md` in a directory serves as the group's landing page
+
+### Example — Multi-Section Docs
+
+```markdown
+# Summary
+
+## Getting Started
+* [Introduction](README.md)
+* [Installation](getting-started/installation.md)
+* [Quick Start](getting-started/quickstart.md)
+* [Configuration](getting-started/config.md)
+
+## User Guide
+* [Overview](guide/README.md)
+* [Basic Usage](guide/basics.md)
+* [Advanced Topics](guide/advanced/README.md)
+  * [Plugins](guide/advanced/plugins.md)
+  * [Theming](guide/advanced/theming.md)
+  * [Hooks](guide/advanced/hooks.md)
+
+## API Reference
+* [REST API](api/rest.md)
+* [TypeScript SDK](api/sdk.md)
+* [Webhooks](api/webhooks.md)
+
+## Resources
+* [FAQ](resources/faq.md)
+* [Troubleshooting](resources/troubleshooting.md)
+* [Changelog](CHANGELOG.md)
+```
+
+## Mono-Repo Support
+
+For repositories containing more than just documentation:
+
+```yaml
+# .gitbook.yaml at repo root
+root: ./packages/docs/
+
+structure:
+  readme: README.md
+  summary: SUMMARY.md
+```
+
+Only files under `root` are synced. The rest of the repository is ignored.
+
+## Sync Directions
+
+| Direction | Behavior |
+|-----------|----------|
+| GitHub → GitBook | Repo is source of truth. Push triggers import. GitBook editor is read-only. |
+| GitBook → GitHub | GitBook is source of truth. Edits create commits on the branch. |
+| Bidirectional | Both are editable. Most recent change wins. Conflicts shown in UI. |
+
+### Conflict Resolution
+
+When bidirectional sync encounters conflicts:
+1. GitBook displays a conflict notification
+2. Choose to keep the GitBook version or the Git version
+3. The chosen version is synced to both locations
+
+## Branch Strategy
+
+- **Production branch** (`main`): Sync to the primary space for live docs
+- **Feature branches**: Create a separate space or use Change Requests
+- **Version branches** (`v1`, `v2`): Sync each to a content variant
+
+## Supported File Types
+
+| Extension | Treatment |
+|-----------|-----------|
+| `.md` | Parsed as content pages |
+| `.yaml` / `.json` | OpenAPI specs rendered as API references |
+| Images (`.png`, `.jpg`, `.svg`, `.gif`) | Stored as assets |
+| Other files | Ignored by GitBook |
+
+## Troubleshooting
+
+| Issue | Cause | Fix |
+|-------|-------|-----|
+| Sync not triggering | GitHub App webhook failed | Re-install the GitHub App |
+| Pages missing | Not listed in SUMMARY.md | Add entries to SUMMARY.md |
+| Wrong page order | SUMMARY.md ordering | Reorder entries in SUMMARY.md |
+| Images broken | Path is absolute | Use relative paths from the page file |
+| .gitbook.yaml ignored | File not at repo root | Move to repository root |
+| Conflicts on every sync | Bidirectional with frequent edits | Choose a single direction |
+
+## Resources
+
+- **Git Sync Docs**: https://docs.gitbook.com/integrations/git-sync
+- **GitHub App**: https://github.com/apps/gitbook-com
+- **.gitbook.yaml Reference**: https://docs.gitbook.com/integrations/git-sync/content-configuration