fix(docs): document sanitizeLinkHref and gate api docs build in ci

- Add @sanitizeLinkHref to the preset-commonmark api template (public
  export from #2410 that was missing from the doc template).
- Exit non-zero when any module fails to build. The script previously
  logged per-module failures but always resolved, so a broken api docs
  build (e.g. the builddocs bump) exited 0 and slipped past ci.
- Run the api docs build as an explicit step in the ci build job so
  regressions are caught.

Author: Saul-Mirone

.github/workflows/ci.yml

@@ -65,6 +65,9 @@ jobs:
       - name: Build packages
         run: pnpm build
 
+      - name: Build API docs
+        run: pnpm --filter=@milkdown/docs run build
+
       - name: Publish snapshot
         if: ${{ github.event_name == 'pull_request' }}
         run: >

docs/api/preset-commonmark.md

@@ -166,6 +166,7 @@ Editor.make()
 @linkSchema
 @toggleLinkCommand
 @updateLinkCommand
+@sanitizeLinkHref
 
 ---
 

docs/src/index.ts

@@ -32,7 +32,7 @@ const logError = (error: unknown) => {
 const write = readdirSync(apiDir)
   .filter((dir) => dir !== '.DS_Store')
   .map((pathname) => parse(pathname).name)
-  .map(async (name) => {
+  .map(async (name): Promise<boolean> => {
     const main = resolve(apiDir, `${name}.md`)
     const out = resolve(apiOutDir, `${name}.md`)
 
@@ -51,27 +51,38 @@ const write = readdirSync(apiDir)
         })
         await writeFile(out, markdown)
         logger.info(`Build module: @milkdown/${name} finished.`)
+        return true
       } catch (error) {
         logger.error(`Build module: @milkdown/${name} failed.`)
         logError(error)
+        return false
       }
     } catch {
       // copy the main file to out
       logger.log(`Copying module: @milkdown/${name}...`)
       try {
         await copyFile(main, out)
         logger.info(`Copy module: @milkdown/${name} finished.`)
+        return true
       } catch (error) {
         logger.error(`Copy module: @milkdown/${name} failed.`)
         logError(error)
+        return false
       }
     }
   })
 
 Promise.all(write)
-  .then(() => {
+  .then((results) => {
+    const failed = results.filter((ok) => !ok).length
+    if (failed > 0) {
+      logger.error(`Build api failed: ${failed} module(s) could not be built.`)
+      process.exitCode = 1
+      return
+    }
     logger.info('Build api done.')
   })
   .catch((error) => {
-    throw error
+    logError(error)
+    process.exitCode = 1
   })