Gitbook

Functions

`importGitBook`

function importGitBook(dir: string, name?: string): ImportResult

TypeScript

Use importGitBook to migrate an existing GitBook documentation site into skrypt-compatible MDX, ready to publish with skrypt generate.

When you're moving a project from GitBook to a skrypt-powered doc site, this is your entry point. It handles the full conversion in one call — walking the GitBook directory, transforming GitBook-specific syntax (hints, tabs, steps, expandable sections, content refs, embeds) into standard MDX components, and normalizing frontmatter and image paths along the way.

It reads your GitBook source directory recursively, detects the .gitbook.yaml root config if present, and returns a structured result containing every converted page plus a stats breakdown of what was transformed.

Name	Type	Required	Description
`dir`	`string`	Yes	Path to the root of your GitBook project — the directory containing `.gitbook.yaml` and your Markdown source files.
`name`	`string`	No	Display name for the imported doc set. Defaults to the directory name if omitted. Appears in the generated site's navigation and metadata.

Returns an ImportResult object containing pages (an array of converted MDX pages, each with its path and content) and stats (a count of every GitBook-specific construct that was transformed, such as callouts, tabs, and steps). Pass pages to your output writer to save the converted files, and inspect stats to verify the migration caught everything you expected.

Heads up:

GitBook content refs ({% content-ref %}) are rewritten to relative MDX links — review them after import if your GitBook used cross-book references, which can't be resolved locally.
Images are path-rewritten relative to the output structure, but any GitBook-hosted assets (uploaded via the GitBook UI) won't be downloaded automatically — you'll need to fetch those separately.

Example:

import { existsSync, mkdirSync, writeFileSync } from 'fs'
import { join } from 'path'

// --- Inline types (do not import from autodocs) ---
interface ImportedPage {
  path: string
  content: string
  title?: string
}

interface TransformStats {
  callouts: number
  tabs: number
  codeGroups: number
  steps: number
  accordions: number
  images: number
  other: number
}

interface ImportResult {
  name: string
  pages: ImportedPage[]
  stats: TransformStats
}

// --- Mock implementation of importGitBook ---
function importGitBook(dir: string, name?: string): ImportResult {
  if (!existsSync(dir)) {
    throw new Error(`GitBook directory not found: ${dir}`)
  }

  // Simulate scanning and transforming a GitBook project
  const resolvedName = name ?? dir.split('/').pop() ?? 'docs'

  return {
    name: resolvedName,
    pages: [
      {
        path: 'getting-started/quickstart.mdx',
        title: 'Quickstart',
        content: `---
title: Quickstart
---

# Quickstart

<Callout type="info">
  Run \`npm install\` before continuing.
</Callout>

Follow these steps to get up and running.
`,
      },
      {
        path: 'api-reference/authentication.mdx',
        title: 'Authentication',
        content: `---
title: Authentication
---

# Authentication

Pass your API key in the \`Authorization\` header.
`,
      },
    ],
    stats: {
      callouts: 3,
      tabs: 1,
      codeGroups: 2,
      steps: 4,
      accordions: 0,
      images: 6,
      other: 0,
    },
  }
}

// --- Write converted pages to an output directory ---
function savePages(pages: ImportedPage[], outputDir: string): void {
  for (const page of pages) {
    const fullPath = join(outputDir, page.path)
    const dir = fullPath.substring(0, fullPath.lastIndexOf('/'))
    mkdirSync(dir, { recursive: true })
    writeFileSync(fullPath, page.content, 'utf-8')
  }
}

// --- Run the migration ---
try {
  const result = importGitBook('./gitbook-source', 'Payment API Docs')

  savePages(result.pages, './content/docs')

  console.log(`✓ Imported "${result.name}"`)
  console.log(`  Pages converted : ${result.pages.length}`)
  console.log(`  Callouts        : ${result.stats.callouts}`)
  console.log(`  Tabs            : ${result.stats.tabs}`)
  console.log(`  Steps           : ${result.stats.steps}`)
  console.log(`  Images rewritten: ${result.stats.images}`)
  console.log(`\nNext: run \`skrypt generate ./content/docs -o ./public/docs\``)
} catch (err) {
  console.error('Migration failed:', err)
  process.exit(1)
}

// Expected output:
// ✓ Imported "Payment API Docs"
//   Pages converted : 2
//   Callouts        : 3
//   Tabs            : 1
//   Steps           : 4
//   Images rewritten: 6
//
// Next: run `skrypt generate ./content/docs -o ./public/docs`

TypeScript

import — gitbook

Gitbook

Functions

importGitBook

`importGitBook`