Readme

Functions

`importReadme`

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

TypeScript

Use importReadme to convert a ReadMe.io documentation export into structured MDX content that skrypt can process and publish to your doc site.

Reach for this when you're migrating an existing ReadMe.io project to a skrypt-powered site. It handles the category-based folder structure that ReadMe exports produce, so you don't have to manually reorganize or reformat your content.

ReadMe exports organize pages into category folders with _order.yaml files that define page ordering. importReadme walks that structure, transforms ReadMe-specific components (callouts, code blocks, tabs) into MDX-compatible equivalents, and normalizes frontmatter across all discovered pages.

Parameters

Name	Type	Required	Description
`dir`	`string`	Yes	Path to the root of your ReadMe.io export — the folder containing the category subdirectories and `_order.yaml` files
`name`	`string`	No	Display name for the imported documentation set. Defaults to the directory name if omitted

Returns

Returns an ImportResult object containing the imported pages, transformation statistics (counts of converted callouts, tabs, code groups, etc.), and any warnings encountered during import. Pass the pages to skrypt generate or write them to your output directory to include them in your doc site build.

Heads up

The dir argument must point to the root of the ReadMe export, not a specific category subfolder — importReadme expects to find category directories with _order.yaml files at that level.
Transformation stats in the result are useful for auditing the migration: if callouts or tabs counts are lower than expected, some components may not have been recognized and will appear as raw HTML in the output.

Example:

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

// --- Inline types (do not import from autodocs) ---
interface ImportedPage {
  slug: string
  title: string
  content: string
  order: number
  category: 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
  warnings: string[]
}

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

  const entries = readdirSync(dir, { withFileTypes: true })
  const categories = entries.filter(e => e.isDirectory()).map(e => e.name)

  const pages: ImportedPage[] = []
  const stats: TransformStats = {
    callouts: 0, tabs: 0, codeGroups: 0,
    steps: 0, accordions: 0, images: 0, other: 0,
  }
  const warnings: string[] = []

  for (const category of categories) {
    const categoryDir = join(dir, category)
    const orderFile = join(categoryDir, '_order.yaml')

    if (!existsSync(orderFile)) {
      warnings.push(`No _order.yaml found in category "${category}" — page order may be incorrect`)
    }

    const mdFiles = readdirSync(categoryDir).filter(f => f.endsWith('.md') || f.endsWith('.mdx'))

    mdFiles.forEach((file, index) => {
      const raw = readFileSync(join(categoryDir, file), 'utf-8')

      // Simulate callout transformation
      const calloutMatches = raw.match(/:::note|:::warning|:::danger/g) ?? []
      stats.callouts += calloutMatches.length

      pages.push({
        slug: file.replace(/\.mdx?$/, ''),
        title: file.replace(/[-_]/g, ' ').replace(/\.mdx?$/, ''),
        content: raw.replace(/:::note/g, '<Callout type="info">').replace(/:::warning/g, '<Callout type="warn">'),
        order: index,
        category,
      })
    })
  }

  return {
    name: name ?? dir.split('/').pop() ?? 'imported-docs',
    pages,
    stats,
    warnings,
  }
}

// --- Usage ---
const exportDir = './readme-export'

// Create a mock ReadMe export structure to demonstrate
mkdirSync(join(exportDir, 'getting-started'), { recursive: true })
writeFileSync(join(exportDir, 'getting-started', '_order.yaml'), 'order:\n  - quickstart\n  - authentication')
writeFileSync(join(exportDir, 'getting-started', 'quickstart.md'), '# Quickstart\n\n:::note\nInstall the SDK before proceeding.\n:::\n\nRun `npm install acme-sdk` to get started.')
writeFileSync(join(exportDir, 'getting-started', 'authentication.md'), '# Authentication\n\nPass your API key in the `Authorization` header.')

try {
  const result = importReadme(exportDir, 'Acme API Docs')

  console.log(`Imported "${result.name}"`)
  console.log(`Pages: ${result.pages.length}`)
  console.log(`Callouts transformed: ${result.stats.callouts}`)
  console.log(`Warnings: ${result.warnings.length > 0 ? result.warnings.join(', ') : 'none'}`)
  console.log('\nFirst page slug:', result.pages[0]?.slug)
  // → Imported "Acme API Docs"
  // → Pages: 2
  // → Callouts transformed: 1
  // → Warnings: none
  // → First page slug: quickstart
} catch (err) {
  console.error('Import failed:', err)
}

TypeScript

import — readme

Readme

Functions

importReadme

`importReadme`