feat(FR-2597): add --chapters option to docs-toolkit pdf for selective chapter export (#6775)

Author: yomybaby

packages/backend.ai-docs-toolkit/src/cli.ts

@@ -41,6 +41,8 @@ Options:
   pdf:
     --lang <all|en|ko|...>    Language(s) to generate (default: all)
     --theme <name>            Theme name (default: default)
+    --chapters <list>         Comma-separated chapter names to include (default: all)
+    --note <text>             Note displayed on the cover page (e.g. "Draft — internal review")
 
   preview:
     --mode <sample|catalog|document>  Preview mode (default: sample)
@@ -66,6 +68,7 @@ Options:
 Examples:
   docs-toolkit pdf --lang all
   docs-toolkit pdf --lang en
+  docs-toolkit pdf --lang ko --chapters "quickstart,session_page,model_serving"
   docs-toolkit preview
   docs-toolkit preview --mode document --lang ko
   docs-toolkit preview:html --lang en
@@ -91,6 +94,17 @@ function hasFlag(argv: string[], flag: string): boolean {
   return argv.includes(flag);
 }
 
+function getFlagValue(argv: string[], flag: string): string | undefined {
+  const idx = argv.indexOf(flag);
+  if (idx < 0) return undefined;
+  const value = argv[idx + 1];
+  if (!value || value.startsWith('--')) {
+    console.error(`Error: ${flag} requires a value.`);
+    process.exit(1);
+  }
+  return value;
+}
+
 // ── Init Command ────────────────────────────────────────────────
 
 async function runInit(): Promise<void> {
@@ -343,11 +357,18 @@ async function main(): Promise<void> {
   switch (command) {
     case 'pdf': {
       const { generatePdf } = await import('./generate-pdf.js');
-      const langIdx = argv.indexOf('--lang');
-      const themeIdx = argv.indexOf('--theme');
+      const langArg = getFlagValue(argv, '--lang') ?? 'all';
+      const themeArg = getFlagValue(argv, '--theme') ?? 'default';
+      const chaptersRaw = getFlagValue(argv, '--chapters');
+      const chaptersArg = chaptersRaw
+        ? chaptersRaw.split(',').map((c) => c.trim())
+        : undefined;
+      const noteArg = getFlagValue(argv, '--note');
       await generatePdf(config, {
-        lang: langIdx >= 0 ? argv[langIdx + 1] : 'all',
-        theme: themeIdx >= 0 ? argv[themeIdx + 1] : 'default',
+        lang: langArg,
+        theme: themeArg,
+        chapters: chaptersArg,
+        note: noteArg,
       });
       break;
     }

packages/backend.ai-docs-toolkit/src/generate-pdf.ts

@@ -18,6 +18,8 @@ interface BookConfig {
 export interface GeneratePdfOptions {
   lang: string;
   theme: string;
+  chapters?: string[];
+  note?: string;
 }
 
 function parseArgs(argv: string[]): GeneratePdfOptions {
@@ -95,12 +97,46 @@ export async function generatePdf(
     const startTime = Date.now();
     console.log(`[${lang}] Generating PDF...`);
 
-    const navigation = bookConfig.navigation[lang];
+    let navigation = bookConfig.navigation[lang];
     if (!navigation) {
       console.warn(`[${lang}] No navigation found, skipping`);
       continue;
     }
 
+    // Filter chapters if --chapters option is specified
+    const chapterFilter = args.chapters?.filter((c) => c.length > 0);
+    if (chapterFilter && chapterFilter.length > 0) {
+      const filterSet = new Set(chapterFilter);
+      const filtered = navigation.filter((nav) => {
+        const noExt = nav.path.replace(/\.md$/, '');
+        const segments = noExt.split('/');
+        const pathStem = segments[segments.length - 1];
+        const dirName = segments.length > 1 ? segments[segments.length - 2] : '';
+        return (
+          filterSet.has(nav.path) ||
+          filterSet.has(pathStem) ||
+          (dirName !== '' && filterSet.has(dirName))
+        );
+      });
+      if (filtered.length === 0) {
+        const available = navigation
+          .map((n) => n.path.replace(/\.md$/, '').split('/').pop())
+          .join(', ');
+        console.error(
+          `[${lang}] No chapters matched filter: ${chapterFilter.join(', ')}`,
+        );
+        console.error(
+          `[${lang}] Chapter identifiers can be a full path (e.g. overview/overview.md), directory name, or filename.`,
+        );
+        console.error(`[${lang}] Available chapters: ${available}`);
+        process.exit(1);
+      }
+      navigation = filtered;
+      console.log(
+        `[${lang}] Filtered to ${navigation.length} chapter(s): ${navigation.map((n) => n.title).join(', ')}`,
+      );
+    }
+
     // Process markdown files
     console.log(`[${lang}] Processing ${navigation.length} chapters...`);
     const chapters = await processMarkdownFiles(
@@ -115,7 +151,7 @@ export async function generatePdf(
     console.log(`[${lang}] Building HTML...`);
     const html = buildFullDocument(
       chapters,
-      { title, version, lang },
+      { title, version, lang, note: args.note },
       config,
       theme,
     );

packages/backend.ai-docs-toolkit/src/html-builder.ts

@@ -9,6 +9,16 @@ export interface DocMetadata {
   title: string;
   version: string;
   lang: string;
+  note?: string;
+}
+
+function escapeHtml(text: string): string {
+  return text
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/\n/g, '<br>');
 }
 
 function getFormattedDate(lang: string): string {
@@ -52,7 +62,7 @@ function buildCoverHtml(
     <p class="company">${config.company}</p>
     <p class="date">${date}</p>
     <p class="lang">${langLabel}</p>
-  </div>
+  </div>${metadata.note ? `\n  <div class="cover-note">${escapeHtml(metadata.note)}</div>` : ''}
 </section>
 `;
 }

packages/backend.ai-docs-toolkit/src/styles.ts

@@ -105,6 +105,19 @@ body {
   border: none;
 }
 
+.cover-note {
+  margin-top: 32px;
+  padding: 12px 20px;
+  border: 1.5px solid ${theme.brandColor};
+  border-radius: 6px;
+  background: #fafafa;
+  color: #444;
+  font-size: 11pt;
+  line-height: 1.5;
+  max-width: 420px;
+  text-align: center;
+}
+
 /* ==========================================================================
    Table of Contents
    ========================================================================== */