snapshot of https://github.com/mattermost/mattermost.git (master, 2026-09-16; blobs > 131072B omitted)

docs/pdf/scripts/build-book-pdf.mjs

@@ -0,0 +1,215 @@
+#!/usr/bin/env node
+/*
+ * Concatenate a section's pages into a single book PDF.
+ *
+ * Strategy:
+ *   1. Load the configured "spine" (an ordered list of URLs to include).
+ *   2. For each URL, fetch via Puppeteer and pull out just the article
+ *      content (.theme-doc-markdown).
+ *   3. Inject a brand-aligned cover page at the top.
+ *   4. Inject the concatenated content into a single static HTML page.
+ *   5. Apply the print CSS, render to PDF.
+ *
+ * For Mattermost API v4, the spine is generated from the OpenAPI tags
+ * — overview + examples + each tag's landing + each endpoint within.
+ * For a smaller demo, the API "Overview" + "Examples" + the first
+ * tag's endpoints is a reasonable target.
+ *
+ * Usage:
+ *   node pdf/scripts/build-book-pdf.mjs --book api      # default
+ *   node pdf/scripts/build-book-pdf.mjs --book api --base http://localhost:3000
+ *
+ * Configurable via pdf/books/<book>.json — see pdf/books/api.json.
+ */
+
+import puppeteer from 'puppeteer';
+import {readFileSync, mkdirSync, statSync} from 'node:fs';
+import {dirname, resolve} from 'node:path';
+import {fileURLToPath} from 'node:url';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const PDF_ROOT = resolve(HERE, '..');
+
+function arg(name, fallback) {
+  const i = process.argv.indexOf(`--${name}`);
+  if (i === -1) return fallback;
+  return process.argv[i + 1] ?? fallback;
+}
+
+function loadSpine(book) {
+  const path = resolve(PDF_ROOT, 'books', `${book}.json`);
+  const cfg = JSON.parse(readFileSync(path, 'utf8'));
+  return cfg;
+}
+
+function coverHtml(cfg) {
+  const buildDate = new Date().toISOString().slice(0, 10);
+  return `
+    <section class="mm-print-cover">
+      <div>
+        <div class="cover-meta">${cfg.eyebrow}</div>
+        <h1 class="cover-title">${cfg.title}</h1>
+        <div class="cover-subtitle">${cfg.subtitle}</div>
+      </div>
+      <div class="cover-bottom">
+        <div class="cover-version">${cfg.version} · ${buildDate}</div>
+        <div class="cover-tagline">Mission in Motion</div>
+      </div>
+    </section>
+  `;
+}
+
+async function fetchArticle(page, url, index) {
+  await page.goto(url, {waitUntil: 'networkidle0', timeout: 60_000});
+  await page.evaluateHandle('document.fonts.ready');
+  // Pull just the article body so the book doesn't carry navbar / sidebar / footer.
+  // Also extract heading metadata so the book builder can compose a ToC.
+  return page.evaluate((idx) => {
+    const article = document.querySelector('article') || document.querySelector('.theme-doc-markdown');
+    if (!article) {
+      return {html: '<!-- no article found -->', title: 'Untitled', subsections: []};
+    }
+    const clone = article.cloneNode(true);
+    const chapterId = `mm-chapter-${idx}`;
+    clone.setAttribute('id', chapterId);
+    const h1 = clone.querySelector('h1');
+    const title = (h1 && h1.textContent.trim()) || document.title || 'Untitled';
+    // Anchor the H1 itself so the ToC entry jumps to the start of the chapter.
+    if (h1 && !h1.id) h1.id = chapterId + '-title';
+    const subsections = Array.from(clone.querySelectorAll('h2')).map((h, i) => {
+      if (!h.id) h.id = `${chapterId}-h2-${i}`;
+      return {text: h.textContent.trim().replace(/​/g, ''), id: h.id};
+    });
+    return {html: clone.outerHTML, title, subsections};
+  }, index);
+}
+
+function escapeHtml(s) {
+  return String(s).replace(/[&<>"']/g, (c) => ({'&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;'}[c]));
+}
+
+function tocHtml(articles) {
+  const items = articles.map((a, i) => {
+    const sub = a.subsections.length
+      ? `<ol class="toc-sub">${a.subsections
+          .map((s) => `<li><a href="#${s.id}"><span class="toc-text">${escapeHtml(s.text)}</span><span class="toc-leader"></span><span class="toc-page" data-href="#${s.id}"></span></a></li>`)
+          .join('')}</ol>`
+      : '';
+    return `<li class="toc-chapter">
+      <a href="#mm-chapter-${i}">
+        <span class="toc-num">${String(i + 1).padStart(2, '0')}</span>
+        <span class="toc-text">${escapeHtml(a.title)}</span>
+        <span class="toc-leader"></span>
+        <span class="toc-page" data-href="#mm-chapter-${i}"></span>
+      </a>
+      ${sub}
+    </li>`;
+  }).join('');
+  return `
+    <section class="mm-print-toc">
+      <header class="toc-header">
+        <div class="toc-eyebrow">Contents</div>
+        <h1 class="toc-heading">Table of Contents</h1>
+      </header>
+      <ol class="toc-list">${items}</ol>
+    </section>
+  `;
+}
+
+async function main() {
+  const bookName = arg('book', 'api');
+  const base = arg('base', 'http://localhost:3000');
+  const output = arg('out', resolve(PDF_ROOT, 'build', `mattermost-${bookName}.pdf`));
+
+  const cfg = loadSpine(bookName);
+  console.log(`[book] ${cfg.title} · ${cfg.spine.length} pages from ${base}`);
+
+  const printCss = readFileSync(resolve(PDF_ROOT, 'styles', 'print.css'), 'utf8');
+  mkdirSync(dirname(resolve(output)), {recursive: true});
+
+  const browser = await puppeteer.launch({
+    headless: 'new',
+    args: ['--no-sandbox', '--font-render-hinting=none'],
+  });
+
+  try {
+    const fetcher = await browser.newPage();
+    fetcher.on('pageerror', (e) => console.error(`[book:browser-error] ${e.message}`));
+
+    const articles = [];
+    for (let i = 0; i < cfg.spine.length; i++) {
+      const path = cfg.spine[i];
+      const url = base + path;
+      console.log(`[book]   ${path}`);
+      articles.push(await fetchArticle(fetcher, url, i));
+    }
+
+    // Compose the book document. We let Docusaurus's built CSS load too
+    // (so MDX components keep their layout); the print CSS overrides
+    // what's needed for paper.
+    const stylesUrl = `${base}/assets/css/styles.css`;
+    const htmlPath = resolve(PDF_ROOT, 'build', `${bookName}-book.html`);
+    const html = `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <title>${cfg.title}</title>
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+  <link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Archivo+Black&family=Inter:wght@400;500;600;700&family=JetBrains+Mono:wght@400;600&display=swap">
+  <style id="print-stylesheet">${printCss}</style>
+</head>
+<body>
+  ${coverHtml(cfg)}
+  ${tocHtml(articles)}
+  ${articles.map((a) => a.html).join('\n<hr class="mm-page-break"/>\n')}
+</body>
+</html>`;
+    const fs = await import('node:fs/promises');
+    await fs.writeFile(htmlPath, html);
+
+    const printer = await browser.newPage();
+    printer.on('console', (m) => {
+      if (m.type() === 'error') console.error(`[book:browser-error] ${m.text()}`);
+    });
+    await printer.goto(`file://${htmlPath}`, {waitUntil: 'networkidle0'});
+    await printer.emulateMediaType('print');
+    await printer.evaluateHandle('document.fonts.ready');
+
+    // Rewrite the OpenAPI dev-server URL prefix to a generic example
+    // so the printed reference doesn't carry "http://localhost:8065"
+    // through to readers. This applies only to print captures; the
+    // live dev site keeps the localhost default for "Send API Request"
+    // testing convenience.
+    await printer.evaluate(() => {
+      const REPLACEMENT = 'https://your-mattermost-server.com';
+      const PATTERN = /https?:\/\/localhost:\d+/g;
+      const walker = document.createTreeWalker(document.body, NodeFilter.SHOW_TEXT);
+      let n;
+      while ((n = walker.nextNode())) {
+        if (n.nodeValue && PATTERN.test(n.nodeValue)) {
+          n.nodeValue = n.nodeValue.replace(PATTERN, REPLACEMENT);
+        }
+      }
+    });
+
+    console.log(`[book] rendering → ${output}`);
+    await printer.pdf({
+      path: resolve(output),
+      format: 'A4',
+      printBackground: true,
+      preferCSSPageSize: true,
+      displayHeaderFooter: false,
+    });
+
+    const {size} = statSync(resolve(output));
+    const pages = Math.ceil(size / 25_000);    // very rough estimate — replace with PDF probe later
+    console.log(`[book] done — ${(size / 1024).toFixed(1)} KB (~${pages} pages estimated)`);
+  } finally {
+    await browser.close();
+  }
+}
+
+main().catch((e) => {
+  console.error('[book] fatal:', e);
+  process.exit(1);
+});

docs/pdf/scripts/build-page-pdf.mjs

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+/*
+ * Capture a single docs page to PDF, applying the brand-aligned print
+ * stylesheet. Used both for on-demand single-page PDF (the per-page
+ * "Download PDF" button) and as the unit primitive that the book
+ * builder concatenates.
+ *
+ * Usage:
+ *   node pdf/scripts/build-page-pdf.mjs <url> <output.pdf>
+ *   node pdf/scripts/build-page-pdf.mjs http://localhost:3000/api pdf/build/api-overview.pdf
+ *
+ * Pre-req: the docs site is built (npm run build) and being served
+ * either by `npm run serve` or some other static server. Pass the URL
+ * the page is reachable at.
+ */
+
+import puppeteer from 'puppeteer';
+import {readFileSync, mkdirSync, existsSync} from 'node:fs';
+import {dirname, resolve} from 'node:path';
+
+async function main() {
+  const [url, output] = process.argv.slice(2);
+  if (!url || !output) {
+    console.error('usage: build-page-pdf.mjs <url> <output.pdf>');
+    process.exit(2);
+  }
+
+  const printCss = readFileSync(new URL('../styles/print.css', import.meta.url), 'utf8');
+  mkdirSync(dirname(resolve(output)), {recursive: true});
+
+  console.log(`[pdf] launching headless Chromium…`);
+  const browser = await puppeteer.launch({
+    headless: 'new',
+    args: ['--no-sandbox', '--font-render-hinting=none'],
+  });
+
+  try {
+    const page = await browser.newPage();
+    page.on('console', (m) => console.log(`[pdf:browser] ${m.type()}: ${m.text()}`));
+    page.on('pageerror', (e) => console.error(`[pdf:browser-error] ${e.message}`));
+
+    console.log(`[pdf] loading ${url}`);
+    await page.goto(url, {waitUntil: 'networkidle0', timeout: 60_000});
+
+    // Apply the print stylesheet (so it lays out for paper while still
+    // running with media:screen — works around quirks where some
+    // Docusaurus chrome only renders for screen).
+    await page.addStyleTag({content: printCss});
+    await page.emulateMediaType('print');
+
+    // Give web fonts time to settle so headlines don't fall back.
+    await page.evaluateHandle('document.fonts.ready');
+
+    console.log(`[pdf] rendering PDF → ${output}`);
+    await page.pdf({
+      path: resolve(output),
+      format: 'A4',
+      printBackground: true,
+      preferCSSPageSize: true,
+      margin: {top: '22mm', right: '18mm', bottom: '24mm', left: '18mm'},
+      displayHeaderFooter: false,           // headers/footers come from @page in print.css
+    });
+
+    const fs = await import('node:fs/promises');
+    const {size} = await fs.stat(resolve(output));
+    console.log(`[pdf] done — ${(size / 1024).toFixed(1)} KB`);
+  } finally {
+    await browser.close();
+  }
+}
+
+main().catch((e) => {
+  console.error('[pdf] fatal:', e);
+  process.exit(1);
+});

docs/pdf/scripts/gen-main-docs-books.mjs

@@ -0,0 +1,124 @@
+#!/usr/bin/env node
+// Generate book spines for each main-docs section from the Documentation
+// sidebar config. One JSON per section under pdf/books/, consumable by
+// build-book-pdf.mjs.
+//
+// Sources:
+//   site/sidebars/documentation.generated.json  (already authoritative)
+//
+// Outputs:
+//   pdf/books/product-overview.json
+//   pdf/books/use-case-guide.json
+//   ... etc. (one per top-level section that exists)
+//
+// Usage: node pdf/scripts/gen-main-docs-books.mjs
+
+import {readFileSync, writeFileSync, mkdirSync} from 'node:fs';
+import {resolve, dirname} from 'node:path';
+import {fileURLToPath} from 'node:url';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const PDF_ROOT = resolve(HERE, '..');
+const REPO_ROOT = resolve(PDF_ROOT, '..');
+const SIDEBAR = resolve(REPO_ROOT, 'site/sidebars/documentation.generated.json');
+const BOOKS_DIR = resolve(PDF_ROOT, 'books');
+
+// Mapping from sidebar category label → book metadata (eyebrow/version).
+// The label must match the top-level category's `label` in the sidebar JSON.
+const BOOK_META = {
+  'Product Overview': {
+    file: 'product-overview',
+    eyebrow: 'PRODUCT OVERVIEW',
+    subtitle: 'Editions, plans, releases, and the platform at a glance.',
+  },
+  'Use Case Guide': {
+    file: 'use-case-guide',
+    eyebrow: 'USE CASES',
+    subtitle: 'Mission-critical scenarios served by Mattermost.',
+  },
+  'Deployment Guide': {
+    file: 'deployment-guide',
+    eyebrow: 'DEPLOYMENT',
+    subtitle: 'Plan, provision, and ship a production Mattermost deployment.',
+  },
+  'Administration Guide': {
+    file: 'administration-guide',
+    eyebrow: 'ADMINISTRATION',
+    subtitle: 'Configure, manage, scale, secure, and comply.',
+  },
+  'Security Guide': {
+    file: 'security-guide',
+    eyebrow: 'SECURITY',
+    subtitle: 'Security architecture, threat model, and hardening guidance.',
+  },
+  'End User Guide': {
+    file: 'end-user-guide',
+    eyebrow: 'END USER GUIDE',
+    subtitle: 'Everything users need to know to collaborate in Mattermost.',
+  },
+  'Integrations Guide': {
+    file: 'integrations-guide',
+    eyebrow: 'INTEGRATIONS',
+    subtitle: 'Bring your tools into Mattermost — from webhooks to platform plugins.',
+  },
+  'Get Help': {
+    file: 'get-help',
+    eyebrow: 'SUPPORT',
+    subtitle: 'Channels for help, escalation, and feedback.',
+  },
+};
+
+function collectDocIds(node, out = []) {
+  if (!node) return out;
+  if (Array.isArray(node)) { node.forEach((n) => collectDocIds(n, out)); return out; }
+  if (node.type === 'doc') out.push(node.id);
+  if (node.type === 'category') {
+    // Prepend the category's link if it points at a doc (the IA's landing
+    // page for that branch — naturally first in print order).
+    if (node.link && node.link.type === 'doc') out.push(node.link.id);
+    if (node.items) collectDocIds(node.items, out);
+  }
+  return out;
+}
+
+function spineFromCategory(cat) {
+  return collectDocIds(cat).map((id) => '/' + id.replace(/^\/+/, ''));
+}
+
+function getVersion() {
+  // Try to read from a VERSION file or fall back to today's date.
+  try {
+    return readFileSync(resolve(REPO_ROOT, 'VERSION'), 'utf8').trim() || 'unreleased';
+  } catch {
+    return 'unreleased';
+  }
+}
+
+function main() {
+  const sidebar = JSON.parse(readFileSync(SIDEBAR, 'utf8'));
+  mkdirSync(BOOKS_DIR, {recursive: true});
+  const version = getVersion();
+
+  let written = 0;
+  for (const node of sidebar) {
+    if (node.type !== 'category') continue;
+    const meta = BOOK_META[node.label];
+    if (!meta) continue;
+    const spine = spineFromCategory(node);
+    if (!spine.length) continue;
+    const config = {
+      title: `Mattermost ${node.label}`,
+      subtitle: meta.subtitle,
+      eyebrow: meta.eyebrow,
+      version,
+      spine,
+    };
+    const out = resolve(BOOKS_DIR, `${meta.file}.json`);
+    writeFileSync(out, JSON.stringify(config, null, 2));
+    console.log(`[book] ${out}  (${spine.length} pages)`);
+    written++;
+  }
+  console.log(`\n[book] wrote ${written} book configs to ${BOOKS_DIR}`);
+}
+
+main();