feat(packages): ship bundled markdown docs in html and react tarballs (#1560)

Co-authored-by: Claude <noreply@anthropic.com>

site/scripts/copy-package-docs.ts

@@ -0,0 +1,192 @@
+/**
+ * Copies the per-framework markdown documentation subtree emitted by the site
+ * build into a target package's `docs/` directory, ready to be shipped in the
+ * package tarball.
+ *
+ * Invoked from each package's `prepack` lifecycle script:
+ *   "prepack": "node --import tsx ../../site/scripts/copy-package-docs.ts html"
+ *
+ * Reads `site/dist/docs/framework/<framework>/` (produced by the llms-markdown
+ * integration), rewrites absolute site URLs to local relative paths, strips
+ * the breadcrumb footer from each .md file, synthesizes a short cold-start
+ * `docs/README.md`, and writes the result to `packages/<framework>/docs/`.
+ *
+ * Hard-errors if `site/dist` is missing — run `pnpm build:site` first.
+ */
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join, posix, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const SITE_DIR = resolve(__dirname, '..');
+const WORKSPACE_ROOT = resolve(SITE_DIR, '..');
+
+const PACKAGE_NAMES = {
+  html: '@videojs/html',
+  react: '@videojs/react',
+} as const;
+
+export type Framework = keyof typeof PACKAGE_NAMES;
+
+const DOCS_SITE_BASE = 'https://videojs.org';
+
+function isFramework(value: string): value is Framework {
+  return value in PACKAGE_NAMES;
+}
+
+// ──────────────────────────────────────────────────────────────────────────
+// Pure transforms (exported for unit tests)
+// ──────────────────────────────────────────────────────────────────────────
+
+/**
+ * Removes the trailing breadcrumb block the site appends to every .md page
+ * and to llms.txt (looks like `---\n\n<framework> documentation: ...`).
+ * Mirrors the regex the CLI uses in `packages/cli/src/utils/docs.ts`.
+ */
+export function stripFooter(content: string): string {
+  return content.replace(/\n+---\n\n(\w+ documentation: https:\/\/.*\n)?All documentation: https:\/\/.*\n*$/, '');
+}
+
+/**
+ * Rewrites URLs that point at this framework's docs subtree into paths
+ * relative to the source file's location, so an agent reading from
+ * node_modules can follow links locally instead of via WebFetch.
+ *
+ * - sourceSlug is the path of the file the content belongs to, relative to
+ *   the framework root and without an extension: e.g. `concepts/overview`
+ *   for `concepts/overview.md`, or `llms` for the index `llms.txt`.
+ * - URLs outside the framework's docs subtree (e.g. the root /llms.txt,
+ *   blog posts, the other framework) are left untouched.
+ */
+export function rewriteLinks(content: string, sourceSlug: string, framework: Framework): string {
+  const frameworkPath = `/docs/framework/${framework}/`;
+  // Match URLs in markdown link target position only: `](URL)`. Anchoring to
+  // `](` keeps the regex from chewing through URL-shaped strings inside link
+  // text (e.g. inside code spans like `[\`videojs.org/.../llms.txt\`](...)`)
+  // where the surrounding characters aren't safe to overrun.
+  //
+  // Capture the trailing extension (`.md`, `.txt`, or `/`) so it can be
+  // preserved — links to the framework's `llms.txt` must stay `.txt`, not be
+  // rewritten to `.md`. URLs with no extension and trailing-slash URLs both
+  // map to the `.md` file the site emits for that slug.
+  const pattern = new RegExp(
+    `(\\]\\()(?:https?://[^\\s)]+)?${escapeForRegex(frameworkPath)}([^\\s)#]*?)(\\.md|\\.txt|/)?(?=[)#])`,
+    'g'
+  );
+  const sourceDir = posix.dirname(sourceSlug);
+  return content.replace(pattern, (match, prefix: string, slug: string, ext: string | undefined) => {
+    // Bare framework-root URLs (empty slug) don't map to a single file —
+    // leave them alone rather than synthesizing a nonsense `./.md`.
+    if (!slug) return match;
+    const targetExt = ext === '.txt' ? '.txt' : '.md';
+    return prefix + toRelativePath(sourceDir, `${slug}${targetExt}`);
+  });
+}
+
+/**
+ * Body for the synthesized `docs/README.md` cold-start file. Short on purpose:
+ * agents reflexively read README, this gets them to the structured index.
+ */
+export function synthesizeReadme({
+  framework,
+  version,
+}: {
+  framework: Framework;
+  version: string | undefined;
+}): string {
+  const packageName = PACKAGE_NAMES[framework];
+  if (!packageName) throw new Error(`Unknown framework: ${framework}`);
+  const versionSuffix = version ? ` v${version}` : '';
+  return [
+    `# ${packageName} documentation`,
+    '',
+    `Bundled markdown documentation for \`${packageName}\`${versionSuffix}.`,
+    '',
+    `Start at [\`./llms.txt\`](./llms.txt) — it's the structured index of every page in this directory.`,
+    '',
+    `Canonical online version: ${DOCS_SITE_BASE}/docs/framework/${framework}`,
+    '',
+  ].join('\n');
+}
+
+// ──────────────────────────────────────────────────────────────────────────
+// Helpers
+// ──────────────────────────────────────────────────────────────────────────
+
+function escapeForRegex(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function toRelativePath(sourceDir: string, targetFile: string): string {
+  const fromDir = sourceDir === '.' || sourceDir === '' ? '.' : sourceDir;
+  const rel = posix.relative(fromDir, targetFile);
+  return rel.startsWith('.') ? rel : `./${rel}`;
+}
+
+function isDocFile(path: string): boolean {
+  return path.endsWith('.md') || path.endsWith('.txt');
+}
+
+function walk(dir: string): string[] {
+  const out: string[] = [];
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      out.push(...walk(full));
+    } else if (entry.isFile() && isDocFile(full)) {
+      out.push(full);
+    }
+  }
+  return out;
+}
+
+function slugFor(relPath: string): string {
+  // 'concepts/overview.md' -> 'concepts/overview'
+  // 'llms.txt' -> 'llms'
+  return relPath.replace(/\.(md|txt)$/, '');
+}
+
+// ──────────────────────────────────────────────────────────────────────────
+// Main IO
+// ──────────────────────────────────────────────────────────────────────────
+
+function main(): void {
+  const framework = process.argv[2];
+  if (!framework || !isFramework(framework)) {
+    console.error(`Usage: node --import tsx copy-package-docs.ts <html|react>`);
+    process.exit(1);
+  }
+
+  const sourceDir = join(SITE_DIR, 'dist', 'docs', 'framework', framework);
+  if (!existsSync(sourceDir)) {
+    console.error(`✗ ${sourceDir} not found — run \`pnpm build:site\` first.`);
+    process.exit(1);
+  }
+
+  const targetDir = join(WORKSPACE_ROOT, 'packages', framework, 'docs');
+  const version = process.env.npm_package_version;
+
+  rmSync(targetDir, { recursive: true, force: true });
+  mkdirSync(targetDir, { recursive: true });
+
+  const files = walk(sourceDir);
+  for (const sourcePath of files) {
+    const relPath = posix.relative(sourceDir.split(/[\\/]/).join('/'), sourcePath.split(/[\\/]/).join('/'));
+    const slug = slugFor(relPath);
+    const raw = readFileSync(sourcePath, 'utf-8');
+    const transformed = rewriteLinks(stripFooter(raw), slug, framework);
+    const destPath = join(targetDir, relPath);
+    mkdirSync(dirname(destPath), { recursive: true });
+    writeFileSync(destPath, transformed, 'utf-8');
+  }
+
+  writeFileSync(join(targetDir, 'README.md'), synthesizeReadme({ framework, version }), 'utf-8');
+
+  console.log(`✓ Copied ${files.length} doc files to packages/${framework}/docs/`);
+}
+
+const isEntrypoint = process.argv[1] && resolve(process.argv[1]) === resolve(__filename);
+if (isEntrypoint) {
+  main();
+}