references/manifest.md

# gitbook-manifest.yaml reference

The manifest defines the integration's identity, permissions, editor blocks, installer-facing configuration, and secrets. It's generated by `gitbook new` and read by `gitbook publish`.

Required fields: `name`, `title`, `description`, `organization`, `visibility`, `scopes`, `script` (script is required to publish).

## Identity fields

```yaml
name: acme-changelog          # globally unique across ALL GitBook integrations
title: Acme Changelog         # display name
description: Post changelog updates into your docs.   # short, one line
organization: <org_id>        # org id or subdomain that owns the integration
script: ./src/index.tsx       # entry file; must default-export createIntegration()
```

`summary` is an optional longer Markdown description shown on the installation page, limited to 2048 characters.

## Visibility

| Value | Meaning |
| --- | --- |
| `private` | Default. Only members of the owning organization can install. |
| `unlisted` | Any org can install, but only via the shared install link. |
| `public` | Any org can install; required for marketplace submission (separate review process). |

## Scopes

Request only what the code uses — installers see the list.

```yaml
scopes:
    # Spaces
    - space:content:read      # read space content
    - space:content:write     # write space content
    - space:metadata:read
    - space:metadata:write
    - space:git:sync          # manage Git Sync within a space
    # Sites
    - site:metadata:read
    - site:views:read         # site analytics
    - site:visitor:auth       # authenticated-access workflows
    - site:adaptive:read      # read Adaptive Content claims
    - site:adaptive:write     # write Adaptive Content claims
    # OpenAPI
    - openapi:read
    - openapi:write
    # Conversations
    - conversations:ingest
```

`site:script:inject` and `site:script:cookies` appear in GitBook-owned integrations but are **internal-only** — third-party integrations cannot inject JavaScript into sites. Don't request them and don't design around them.

Events may require matching scopes (e.g. `space_content_updated` needs space content/metadata read access).

## Blocks

Declares custom blocks so they appear in the editor's insert palette (⌘ + /). Each `id` must match a `componentId` in the code.

```yaml
blocks:
  - id: example-block
    title: Example Block
    description: An example block for a GitBook integration
```

Optional per-block keys:

- `urlUnfurl` — list of URL prefixes this block unfurls when pasted into the editor (pairs with the `@link.unfurl` action; see `contentkit.md`).
- `markdown` — serialize the block as a Markdown code-block instead of an opaque node:

  ```yaml
  blocks:
      - id: block-name
        title: My custom block
        markdown:
          codeblock: blocksyntax   # the code fence language
          body: content            # which prop becomes the fence body
  ```

  A block with props `{ "content": "something", "propA": "A" }` serializes as:

  ````markdown
  ```blocksyntax propA="A"
  something
  ```
  ````

  This is how the native Mermaid block works — use it when block content should survive round-trips through Git Sync as readable Markdown.

## Marketplace/installation-page presentation

```yaml
categories:            # any of: analytics, collaboration, content, marketing, authenticated-access, other
    - content
icon: ./assets/icon.png              # local path, shipped with the integration
previewImages:                       # recommended 1600×800 (2:1)
    - ./assets/preview.png
externalLinks:
    - label: Documentation
      url: https://example.com/docs
```

## Configurations (installer-facing settings form)

`configurations.account` renders at org-installation level; `configurations.site` renders per site/space installation. Each takes `properties` (the form fields) and an optional `required` list. Values entered by the installer surface at runtime in `context.environment` (installation `configuration` object).

Property types:

```yaml
configurations:
    account:
        properties:
            oauth_credentials:            # button — the OAuth entry point
                type: button
                title: Connection
                description: Authorization between my app and GitBook.
                button_text: Authorize
                callback_url: /oauth      # route handled by createOAuthHandler in fetch
            api_region:                   # string with fixed choices
                type: string
                title: Region
                enum: [us, eu]
            default_channel:              # string with dynamic choices
                type: string
                title: Default Channel
                completion_url: /channels # integration endpoint returning options
        required:
            - oauth_credentials
    site:
        properties:
            notify_content_update:
                type: boolean
                title: Notify Content Update
                default: true
            max_items:
                type: number
                title: Max items
                default: 5
```

- `string` — free text; `enum` turns it into a fixed dropdown; `completion_url` fetches dropdown options from an endpoint on the integration.
- `number`, `boolean` — plain inputs; support `default`.
- `button` — for OAuth or other callback flows; `button_text` + `callback_url`.

### Installation & configuration flow

`installation_setup` fires when the integration is first installed **and again every time the installer edits a configuration property**. The installation's `status` stays incomplete until the configuration validates against the schema, then becomes `active`. Check `environment.installation.status !== 'active'` to detect unfinished setup — don't assume configuration exists in event handlers that can fire before setup completes.

## Secrets

Runtime secrets (API keys, OAuth client credentials) are declared with environment indirection — never literal values in the manifest:

```yaml
secrets:
    CLIENT_ID: ${{ env.CLIENT_ID }}
    CLIENT_SECRET: ${{ env.CLIENT_SECRET }}
```

Env vars are not loaded into the manifest automatically; wrap the CLI with [`dotenv-cli`](https://www.npmjs.com/package/dotenv-cli) so `.env` is visible at publish time, e.g. in `package.json`:

```json
{ "scripts": { "publish": "dotenv -- gitbook publish" } }
```

At runtime the values appear as `context.environment.secrets.CLIENT_ID`.

## CLI reference

| Command | What it does |
| --- | --- |
| `gitbook auth` | Authenticate with a personal access token (from https://app.gitbook.com/account/developer). Also accepts `--token=<token>`. |
| `gitbook new <dir>` | Scaffold a new integration; prompts for name, title, organization, scopes. |
| `gitbook publish` | Publish (or update) the integration defined by the manifest; prints the install link. |
| `gitbook dev` | Start the local dev proxy — routes the installed integration's traffic to your machine. Requires the integration to be published and installed somewhere first. |
| `gitbook unpublish <name>` | Remove the integration from the platform. |
| `gitbook whoami` | Show the authenticated user. |
| `gitbook help` | Command help. |
| `gitbook openapi publish <spec.yaml> --spec <name> --organization <org_id>` | Publish/update an OpenAPI spec (adjacent tooling, not integration-specific). |

Requires Node v18+. Install with `npm install @gitbook/cli -g`.