@cleocode/cleo 2026.3.2 → 2026.3.6

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

@@ -1,230 +0,0 @@
-# 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

@@ -1,202 +0,0 @@
-# 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

@@ -1,175 +0,0 @@
-# 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