Add gitbook content commands: lint, format, broken-links

packages/cli/build.sh

@@ -4,6 +4,8 @@ rm -rf ./dist/
 esbuild ./src/cli.ts \
     --bundle \
     --platform=node \
+    --format=esm \
+    --banner:js="$(cat ./esm-shims.js)" \
     --external:esbuild \
     --external:miniflare \
     --external:fsevents \

packages/cli/cli.js

@@ -4,4 +4,4 @@
  * To avoid the probem of bun/npm only linking the CLI at the installation time.
  * We use a fixed file that will be linked to the bin folder and requires the actual CLI.
  */
-require('./dist/cli.js');
+import './dist/cli.js';

packages/cli/esm-shims.js

@@ -0,0 +1,8 @@
+// Shims for CommonJS globals used by bundled dependencies (require) and by
+// the CLI itself (__dirname), injected as a banner in the ESM bundle.
+import { createRequire as __createRequire } from 'node:module';
+import { fileURLToPath as __fileURLToPath } from 'node:url';
+import { dirname as __pathDirname } from 'node:path';
+const require = __createRequire(import.meta.url);
+const __filename = __fileURLToPath(import.meta.url);
+const __dirname = __pathDirname(__filename);

packages/cli/package.json

@@ -2,8 +2,10 @@
     "name": "@gitbook/cli",
     "description": "CLI to build and publish integrations on GitBook.com",
     "version": "0.28.0",
+    "type": "module",
     "dependencies": {
         "@gitbook/api": "*",
+        "@gitbook/content": "file:../../../gitbook-x/packages/content/dist",
         "check-node-version": "^4.2.1",
         "commander": "^9.2.0",
         "conf": "^13.1.0",
@@ -26,11 +28,11 @@
     },
     "files": [
         "dist/**",
-        "postinstall.js"
+        "postinstall.cjs"
     ],
     "scripts": {
         "build": "./build.sh",
-        "postinstall": "node postinstall.js",
+        "postinstall": "node postinstall.cjs",
         "typecheck": "tsc --noEmit"
     },
     "engines": {

packages/cli/postinstall.js → packages/cli/postinstall.cjs

@@ -2,7 +2,7 @@
  * Script to install cloudflared binary on the current platform.
  * Reference: https://github.com/JacobLinCool/node-cloudflared/blob/main/src/install.ts
  */
-const { execSync } = require('child_process');
+const { execSync } = require('node:child_process');
 const fs = require('fs');
 const https = require('https');
 const path = require('path');

packages/cli/src/cli.ts

@@ -16,6 +16,7 @@ import { publishIntegration, unpublishIntegration } from './publish';
 import { authenticate, whoami } from './remote';
 import { tailLogs } from './tail';
 import { checkIntegrationBuild } from './check';
+import { brokenLinksContentFiles, formatContentFiles, lintContentFiles } from './content';
 import {
     publishOpenAPISpecificationFromFilepath,
     publishOpenAPISpecificationFromURL,
@@ -153,6 +154,54 @@ program
         });
     });
 
+const contentProgram = program
+    .command('content')
+    .description('lint and format markdown content against the GitBook content schema');
+contentProgram
+    .command('lint')
+    .description(
+        'report content that GitBook would remove or restructure on import, and invalid frontmatter',
+    )
+    .argument('[files...]', 'markdown files or directories (searched recursively for *.md)')
+    .option('--strict', 'exit with code 1 on warnings, not only errors')
+    .action(async (files, options) => {
+        const code = await lintContentFiles(files, { strict: options.strict ?? false });
+        if (code !== 0) {
+            process.exit(code);
+        }
+    });
+contentProgram
+    .command('broken-links')
+    .description('check for broken internal links and anchors across markdown files')
+    .argument('[files...]', 'markdown files or directories (searched recursively for *.md)')
+    .option('--strict', 'exit with code 1 on warnings (broken anchors), not only errors')
+    .action(async (files, options) => {
+        const code = await brokenLinksContentFiles(files, { strict: options.strict ?? false });
+        if (code !== 0) {
+            process.exit(code);
+        }
+    });
+contentProgram
+    .command('format')
+    .description(
+        "apply GitBook's canonical style to markdown files; never alters content unless --force",
+    )
+    .argument('[files...]', 'markdown files or directories (searched recursively for *.md)')
+    .option('--write', 'write changes to the files')
+    .option(
+        '--force',
+        "also apply GitBook's normalization: content reported as lint errors is removed or restructured",
+    )
+    .action(async (files, options) => {
+        const code = await formatContentFiles(files, {
+            write: options.write ?? false,
+            force: options.force ?? false,
+        });
+        if (code !== 0) {
+            process.exit(code);
+        }
+    });
+
 const openAPIProgram = program.command('openapi').description('manage OpenAPI specifications');
 openAPIProgram
     .command('publish')