Codex: A Markdown Folder to a Live Docusaurus Docs Site

The Stack

Tested Against

Prerequisites

• Codex with the @build-web-apps and @vercel plugins
• A Docusaurus project and a docs/ folder of markdown
• A Vercel login for the preview deploy

Steps

1. 1

   Ask Codex to assemble the docs and ship a preview

   Use @build-web-apps to turn the markdown in docs/ into a Docusaurus site with a sensible sidebar and search. Fix any broken internal links. Run the local build, then use @vercel to deploy a preview and send me the URL.

2. 2

   What CI checks: broken links fail the build and the build is wired

   Docusaurus's build is the test: with onBrokenLinks set to throw, a broken internal link fails the build, so a green build means a publishable site. CI confirms that guard is enabled in the config and the build is wired (docusaurus build, @docusaurus/core present, docs markdown present). The full docusaurus build that actually crawls the links is fenced.

   mkdir -p docs
   cat > docs/intro.md <<'EOF'
   # Intro
   
   Welcome to the docs.
   EOF
   cat > package.json <<'EOF'
   {
     "name": "docs-site",
     "private": true,
     "scripts": { "build": "docusaurus build", "start": "docusaurus start" },
     "dependencies": { "@docusaurus/core": "^3.6.0", "@docusaurus/preset-classic": "^3.6.0", "react": "^19.0.0", "react-dom": "^19.0.0" }
   }
   EOF
   cat > docusaurus.config.js <<'EOF'
   module.exports = {
     title: 'Docs',
     url: 'https://example.com',
     baseUrl: '/',
     onBrokenLinks: 'throw',
     onBrokenMarkdownLinks: 'throw',
     presets: [['classic', { docs: { path: 'docs' } }]],
   };
   EOF
   cat > checkdocs.mjs <<'EOF'
   import { readFileSync, existsSync } from 'node:fs';
   let ok = true;
   function check(label, cond){ console.log(label + ': ' + (cond ? 'yes' : 'NO')); if(!cond) ok=false; }
   const pkg = JSON.parse(readFileSync('package.json', 'utf8'));
   check('build script is docusaurus build', String((pkg.scripts||{}).build||'').includes('docusaurus build'));
   check('docusaurus core is a dependency', !!(pkg.dependencies && pkg.dependencies['@docusaurus/core']));
   const cfg = existsSync('docusaurus.config.js') ? readFileSync('docusaurus.config.js', 'utf8') : '';
   check('build fails on broken links (onBrokenLinks: throw)', cfg.includes("onBrokenLinks: 'throw'"));
   check('docs folder has markdown', existsSync('docs/intro.md'));
   if(!ok){ console.log('docusaurus build-readiness check FAILED'); process.exit(1); }
   console.log('docusaurus build-readiness check OK');
   EOF
   node checkdocs.mjs

3. 3

   Let Codex build and deploy (the model + account step, not checked by CI)

   Codex assembles the content, runs the full docusaurus build (which crawls and validates every internal link), and @vercel deploys the preview. The assembly and the deploy are non-deterministic and account-gated, so CI never runs them. The badge covers the broken-link guard and a wired build, not the live site.