Confluence

Functions

`importConfluence`

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

TypeScript

Use importConfluence to convert a Confluence HTML space export into structured MDX-ready pages you can feed directly into your documentation site.

Reach for this when you're migrating existing team knowledge from Confluence into a skrypt-powered doc site. It handles the full conversion pipeline — scanning the exported HTML files, transforming Confluence-specific markup (callouts, tabs, code blocks), and normalizing frontmatter into a consistent format.

The function walks the export directory, finds every HTML file, and applies a series of transforms to produce clean, portable page content. Confluence exports include proprietary markup that would otherwise render as broken HTML; this function normalizes it so the output works with any MDX platform.

Parameters

Name	Type	Required	Description
`dir`	`string`	Yes	Path to the root of your Confluence HTML space export — the folder you get after extracting the `.zip` from Confluence's Space Export feature
`name`	`string`	No	Display name for the imported space. Appears as the top-level section title in the generated docs. Defaults to the directory name if omitted

Returns

Returns an ImportResult object containing the array of converted pages and a stats summary of every transformation applied (callouts rewritten, code groups created, images found, etc.). Pass the pages to your output writer or skrypt generate pipeline to produce final MDX files. Check the stats to verify the import caught everything you expected — a callouts: 0 on a content-heavy space is a signal something may have gone wrong.

Heads up

This expects the HTML export format from Confluence, not the XML export. If you exported via Space tools → Content Tools → Export → XML, the directory structure won't be recognized.
Nested page hierarchies in Confluence are reflected in the output page paths, but empty index pages (auto-generated by Confluence as section containers) are included in the result — filter them out if you don't want stub pages in your docs.

Example:

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

// --- Inline types (do not import from autodocs) ---
interface ImportedPage {
  title: string
  path: string
  content: string
  frontmatter: Record<string, 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 importConfluence ---
function importConfluence(dir: string, name?: string): ImportResult {
  // In real usage, this scans dir for Confluence HTML export files.
  // Here we simulate a result from a typical small space export.
  return {
    name: name ?? 'Engineering Handbook',
    pages: [
      {
        title: 'Getting Started',
        path: 'getting-started/index',
        content: '## Getting Started\n\nWelcome to the engineering handbook.',
        frontmatter: { title: 'Getting Started', description: 'Onboarding guide' },
      },
      {
        title: 'API Design Guidelines',
        path: 'guidelines/api-design',
        content: '## API Design\n\n> **Note:** Always version your endpoints.\n\n```ts\nGET /v1/users\n```',
        frontmatter: { title: 'API Design Guidelines', description: 'REST API standards' },
      },
      {
        title: 'Deployment',
        path: 'operations/deployment',
        content: '## Deployment\n\nUse the CI pipeline for all production releases.',
        frontmatter: { title: 'Deployment', description: 'Release process' },
      },
    ],
    stats: {
      callouts: 3,
      tabs: 1,
      codeGroups: 2,
      steps: 0,
      accordions: 1,
      images: 5,
      other: 0,
    },
  }
}

// --- Usage ---
async function main() {
  try {
    const exportDir = './confluence-export/engineering-handbook'

    const result = importConfluence(exportDir, 'Engineering Handbook')

    console.log(`Imported space: "${result.name}"`)
    console.log(`Pages found: ${result.pages.length}`)
    console.log('Transform stats:', result.stats)

    // Write each page to an output directory
    const outDir = './content/docs'
    mkdirSync(outDir, { recursive: true })

    for (const page of result.pages) {
      const frontmatterBlock = Object.entries(page.frontmatter)
        .map(([k, v]) => `${k}: "${v}"`)
        .join('\n')

      const mdx = `---\n${frontmatterBlock}\n---\n\n${page.content}`
      const filePath = join(outDir, `${page.path}.mdx`)

      mkdirSync(join(outDir, page.path.split('/').slice(0, -1).join('/')), { recursive: true })
      writeFileSync(filePath, mdx, 'utf-8')
      console.log(`  ✓ Written: ${filePath}`)
    }
  } catch (err) {
    console.error('Import failed:', err)
    process.exit(1)
  }
}

main()

// Expected output:
// Imported space: "Engineering Handbook"
// Pages found: 3
// Transform stats: { callouts: 3, tabs: 1, codeGroups: 2, steps: 0, accordions: 1, images: 5, other: 0 }
//   ✓ Written: ./content/docs/getting-started/index.mdx
//   ✓ Written: ./content/docs/guidelines/api-design.mdx
//   ✓ Written: ./content/docs/operations/deployment.mdx

TypeScript

import — confluence

Confluence

Functions

importConfluence

`importConfluence`