screenci__screenci/docs/manifest.mjs

/**
 * Source of truth for ScreenCI docs information architecture.
 * Slugs are web-facing and stable even if source filenames change.
 */

export const docsManifest = [
  {
    source: 'installation.md',
    slug: 'docs',
    section: 'Getting Started',
    order: 1,
    navLabel: 'Installation',
    title: 'Installation',
    description:
      'Install ScreenCI, initialize a project, run the starter video locally, and record your first final video.',
    prev: null,
    next: 'docs/write-video-scripts',
  },
  {
    source: 'write-video-scripts.md',
    slug: 'docs/write-video-scripts',
    section: 'Getting Started',
    order: 2,
    navLabel: 'Write video scripts',
    title: 'Write Video Scripts',
    description:
      'Author .video.ts files with Playwright-like APIs, ScreenCI narration and camera helpers, and workflow-aware pacing.',
    prev: 'docs',
    next: 'docs/generating-videos',
  },
  {
    source: 'generating-videos.md',
    slug: 'docs/generating-videos',
    section: 'Getting Started',
    order: 3,
    navLabel: 'Generating videos',
    title: 'Generating Videos',
    description:
      'Use Playwright codegen and AI-assisted workflows to generate a first ScreenCI draft, then refine it into a real video script.',
    prev: 'docs/write-video-scripts',
    next: 'docs/run-and-debug-videos',
  },
  {
    source: 'run-and-debug-videos.md',
    slug: 'docs/run-and-debug-videos',
    section: 'Getting Started',
    order: 4,
    navLabel: 'Run and debug videos',
    title: 'Run and Debug Videos',
    description:
      'Use screenci test to iterate locally, inspect failures, and debug pacing, selectors, and visible state before recording.',
    prev: 'docs/generating-videos',
    next: 'docs/record-and-publish',
  },
  {
    source: 'record-and-publish.md',
    slug: 'docs/record-and-publish',
    section: 'Getting Started',
    order: 5,
    navLabel: 'Record and publish',
    title: 'Record and Publish',
    description:
      'Record the final browser session with screenci record, upload the results, and understand how published outputs behave.',
    prev: 'docs/run-and-debug-videos',
    next: 'docs/screenci-vs-playwright',
  },
  {
    source: 'screenci-vs-playwright.md',
    slug: 'docs/screenci-vs-playwright',
    section: 'Getting Started',
    order: 6,
    navLabel: 'ScreenCI vs Playwright',
    title: 'ScreenCI vs Playwright',
    description:
      'See what stays the same from Playwright, what ScreenCI adds for polished video authoring, and when to use each tool.',
    prev: 'docs/record-and-publish',
    next: 'docs/ci-setup',
  },
  {
    source: 'ci-setup.md',
    slug: 'docs/ci-setup',
    section: 'Getting Started',
    order: 7,
    navLabel: 'CI setup',
    title: 'CI Setup',
    description:
      'Understand the generated GitHub Actions workflow, required secrets, and how to keep CI recordings deterministic.',
    prev: 'docs/screenci-vs-playwright',
    next: 'docs/guides/narration-and-localization',
  },
  {
    source: 'narration-and-localization.md',
    slug: 'docs/guides/narration-and-localization',
    section: 'Guides',
    order: 1,
    navLabel: 'Narration and localization',
    title: 'Narration and Localization',
    description:
      'Create spoken cues, overlap narration with visible UI motion, and keep multi-language variants consistent and type-safe.',
    prev: 'docs/ci-setup',
    next: 'docs/guides/camera-and-zooming',
  },
  {
    source: 'camera-and-zooming.md',
    slug: 'docs/guides/camera-and-zooming',
    section: 'Guides',
    order: 3,
    navLabel: 'Camera and zooming',
    title: 'Camera and Zooming',
    description:
      'Choose between autoZoom and manual framing, and use camera direction to guide attention without making the video frantic.',
    prev: 'docs/guides/narration-and-localization',
    next: 'docs/guides/assets-and-overlays',
  },
  {
    source: 'assets-and-overlays.md',
    slug: 'docs/guides/assets-and-overlays',
    section: 'Guides',
    order: 4,
    navLabel: 'Assets and overlays',
    title: 'Assets and Overlays',
    description:
      'Add intro clips, corner logos, transition assets, and timed overlays to ScreenCI recordings.',
    prev: 'docs/guides/camera-and-zooming',
    next: 'docs/guides/public-urls-and-embeds',
  },
  {
    source: 'public-urls-and-embeds.md',
    slug: 'docs/guides/public-urls-and-embeds',
    section: 'Guides',
    order: 5,
    navLabel: 'Public URLs and embeds',
    title: 'Public URLs and Embeds',
    description:
      'Enable public delivery for a video, understand stable language-specific URLs, and embed ScreenCI outputs in other sites.',
    prev: 'docs/guides/assets-and-overlays',
    next: 'docs/guides/update-screenci',
  },
  {
    source: 'update-screenci.md',
    slug: 'docs/guides/update-screenci',
    section: 'Guides',
    order: 5,
    navLabel: 'Update ScreenCI',
    title: 'Update ScreenCI',
    description:
      'Upgrade the screenci package, refresh Playwright when needed, and verify that existing videos still behave as expected.',
    prev: 'docs/guides/public-urls-and-embeds',
    next: 'docs/reference/cli',
  },
  {
    source: 'cli.md',
    slug: 'docs/reference/cli',
    section: 'Reference',
    order: 1,
    navLabel: 'CLI',
    title: 'CLI',
    description:
      'Command reference for screenci init, test, record, project info, and public delivery commands.',
    prev: 'docs/guides/update-screenci',
    next: 'docs/reference/configuration',
  },
  {
    source: 'configuration.md',
    slug: 'docs/reference/configuration',
    section: 'Reference',
    order: 2,
    navLabel: 'Configuration',
    title: 'Configuration',
    description:
      'Configure project identity, file locations, rendering defaults, upload behavior, and Playwright integration in screenci.config.ts.',
    prev: 'docs/reference/cli',
    next: 'docs/reference/video-authoring-api-overview',
  },
  {
    source: 'video-authoring-api-overview.md',
    slug: 'docs/reference/video-authoring-api-overview',
    section: 'Reference',
    order: 3,
    navLabel: 'Video authoring API overview',
    title: 'Video Authoring API Overview',
    description:
      'Human-curated reference for the main ScreenCI authoring primitives, with minimal examples and links into the full typedoc.',
    prev: 'docs/reference/configuration',
    next: 'docs/reference/public-delivery-api',
  },
  {
    source: 'public-delivery-api.md',
    slug: 'docs/reference/public-delivery-api',
    section: 'Reference',
    order: 4,
    navLabel: 'Public delivery API',
    title: 'Public Delivery API',
    description:
      'Technical reference for the unauthenticated endpoints that serve published videos, thumbnails, subtitles, and metadata.',
    prev: 'docs/reference/video-authoring-api-overview',
    next: 'docs/reference/api',
  },
]

export const docsSections = ['Getting Started', 'Guides', 'Reference']

export function getDocBySlug(slug) {
  return docsManifest.find((entry) => entry.slug === slug)
}

export function getOutputPathFromSlug(slug) {
  if (slug === 'docs') return 'index.md'
  return `${slug.replace(/^docs\//, '')}.md`
}

export function getGeneratedDocsManifest() {
  return docsManifest.map((entry) => ({
    ...entry,
    outputPath: getOutputPathFromSlug(entry.slug),
  }))
}

function slugToPath(slug) {
  return `/${slug}`
}

function toSidebarItem(entry) {
  return {
    label: entry.navLabel,
    slug: entry.slug,
  }
}

export function getDocsSidebarConfig(typedocSidebarGroup) {
  return docsSections.map((section) => {
    const items = docsManifest
      .filter((entry) => entry.section === section)
      .sort((a, b) => a.order - b.order)
      .map(toSidebarItem)

    if (section === 'Reference' && typedocSidebarGroup) {
      items.push(typedocSidebarGroup)
    }

    return {
      label: section,
      items,
    }
  })
}

export function getPrevNextLinkConfig(slug) {
  if (!slug) return false
  if (slug === 'docs/reference/api') {
    return {
      label: 'Full API Reference',
      link: '/docs/reference/api',
    }
  }

  const entry = getDocBySlug(slug)
  if (!entry) {
    throw new Error(`Unknown docs slug in prev/next config: ${slug}`)
  }

  return {
    label: entry.navLabel,
    link: slugToPath(entry.slug),
  }
}