@ng-doc/builder 22.0.0 → 22.1.0

package/generator/vite/lifecycle.d.ts

@@ -111,6 +111,7 @@ export declare class ViteAdapterLifecycle {
     private reconcile;
     private fail;
     private report;
+    private warn;
     private isCurrent;
     private log;
     private interrupt;

package/generator/vite/prerender-entry.js

@@ -301,13 +301,82 @@ async function runPrerender(request, options = {}) {
     errors.push({ route: current, message: format(...args) });
     log.apply(console, args);
   };
+  const warnings = [];
   try {
-    return { ...await renderRoutes(), errors };
+    const report = await renderRoutes();
+    if (request.demoServerEntry) report.routes = await renderDemoRoutes(report.routes);
+    return { ...report, errors, ...warnings.length ? { warnings } : {} };
   } finally {
     console.error = log;
     restoreWarnings();
     globalThis.fetch = originalFetch;
   }
+  async function renderDemoRoutes(rendered) {
+    const shellFile2 = path2.join(browserDir, DEMO_SHELL);
+    const message = (error) => error instanceof Error ? error.message : String(error);
+    let demoDocument;
+    let demo;
+    let inventory;
+    current = `/${DEMO_SHELL}`;
+    try {
+      demoDocument = await readFile(shellFile2, "utf8");
+      demo = serverEntry(
+        await importModule(pathToFileURL(path2.resolve(request.demoServerEntry)).href)
+      );
+      await withTimeout(
+        demo.renderApplication(
+          async (context) => {
+            const application = await demo.bootstrap(context);
+            const router = application.injector.get(demo.Router);
+            inventory = await enumerateRoutes(Array.isArray(router?.config) ? router.config : [], {
+              invoke: (factory) => demo.runInInjectionContext(application.injector, factory)
+            });
+            return application;
+          },
+          { document: demoDocument, url: url("/"), allowedHosts: [HOST] }
+        ),
+        request.routeTimeoutMs,
+        current
+      );
+    } catch (error) {
+      warnings.push({
+        route: current,
+        message: `[NGDOC_PRERENDER_DEMO_APPLICATION] The demo pages were not prerendered: ${message(error)}`
+      });
+      return rendered;
+    }
+    const taken = new Set(rendered.map((route) => route.path));
+    const result = [...rendered];
+    for (const route of inventory.routes) {
+      if (route.redirectTo !== void 0 || taken.has(route.path)) continue;
+      const file = routeFile(route.path);
+      current = route.path;
+      let html;
+      try {
+        html = await withTimeout(
+          demo.renderApplication(demo.bootstrap, {
+            document: demoDocument,
+            url: url(route.path),
+            allowedHosts: [HOST]
+          }),
+          request.routeTimeoutMs,
+          route.path
+        );
+      } catch (error) {
+        warnings.push({
+          route: route.path,
+          message: `[NGDOC_PRERENDER_DEMO_FALLBACK] The demo page did not render on the server, so it renders in the browser only: ${message(error)}`
+        });
+        html = demoDocument;
+      }
+      await mkdir(path2.dirname(path2.join(browserDir, file)), { recursive: true });
+      await writeFile(path2.join(browserDir, file), html);
+      result.push({ ...route, file });
+    }
+    return result.sort(
+      (left, right) => left.path < right.path ? -1 : left.path > right.path ? 1 : 0
+    );
+  }
   async function renderRoutes() {
     const discovered = [];
     const excluded = [];
@@ -374,13 +443,14 @@ function runPrerenderChild(port, run = runPrerender) {
     );
   });
 }
-var SHELL, HOST;
+var SHELL, DEMO_SHELL, HOST;
 var init_prerender_runtime = __esm({
   "libs/builder/generator/vite/prerender-runtime.ts"() {
     "use strict";
     init_mime();
     init_route_inventory();
     SHELL = "index.csr.html";
+    DEMO_SHELL = "ng-doc-demo.html";
     HOST = "localhost";
   }
 });

package/generator/vite/prerender-runtime.d.ts

@@ -11,6 +11,11 @@ export interface PrerenderRequest {
     discoverRoutes: boolean;
     /** Fails a route that takes longer to render, in milliseconds. */
     routeTimeoutMs?: number;
+    /**
+     * The server bundle of the demo application (`demo-server.mjs`), when the build has demo pages.
+     * Its routes are rendered into the demo application's page (`ng-doc-demo.html`).
+     */
+    demoServerEntry?: string;
 }
 export interface PrerenderReport {
     /** Every rendered route, in code-unit order, with the file written for it. */
@@ -26,6 +31,14 @@ export interface PrerenderReport {
         route: string;
         message: string;
     }>;
+    /**
+     * Demo pages that failed to render, which got the demo application's client page instead, and
+     * a demo application that could not be prerendered at all. Absent when there are none.
+     */
+    warnings?: Array<{
+        route: string;
+        message: string;
+    }>;
 }
 export interface PrerenderRuntimeOptions {
     /** Imports the server bundle; tests replace it. */

package/generator/vite/prerender.d.ts

@@ -12,6 +12,8 @@ export interface NgDocPrerenderOptions {
     discoverRoutes?: boolean;
     /** Fails a route that takes longer to render, in milliseconds (default: no limit). */
     routeTimeoutMs?: number;
+    /** The demo application's server bundle (`demo-server.mjs`), when the build has demo pages. */
+    demoServerEntry?: string;
     signal?: AbortSignal;
     /** The child process entry; tests replace it. */
     entryUrl?: URL;

package/helpers/format-cache.d.ts

@@ -0,0 +1,34 @@
+import type { Options } from 'prettier';
+/**
+ * A cache that `formatCode` consults while it is installed with {@link withFormatCodeCache}. The
+ * new engine installs one around its own formatting calls; without one (the legacy engine, the
+ * kill switch, the reference path) `formatCode` resolves the configuration and formats every
+ * call, as it always did.
+ */
+export interface FormatCodeCache {
+    /**
+     * The Prettier configuration for `configDirectory`. `resolve` reads it; the cache may call it
+     * once and return that value for later calls. An error of `resolve` is thrown to the caller.
+     */
+    config(configDirectory: string | undefined, resolve: () => Options | null): Options | null;
+    /**
+     * The formatted code. `format` formats it; the cache may return a value it stored for the same
+     * code, parser and configuration instead. An error of `format` is thrown; the cache may store a
+     * Prettier syntax error (deterministic for these inputs) and throw one again on a hit, so
+     * `formatCode` returns the code unformatted in both cases.
+     */
+    format(input: {
+        code: string;
+        parser: string;
+        config: Options | null;
+    }, format: () => string): string;
+}
+/**
+ * Runs `run` with `cache` installed for every `formatCode` call it makes synchronously, and
+ * restores the previous one afterwards.
+ * @param cache The cache to install, or undefined for none.
+ * @param run The synchronous work that formats.
+ */
+export declare function withFormatCodeCache<T>(cache: FormatCodeCache | undefined, run: () => T): T;
+/** The cache installed by {@link withFormatCodeCache}, if any. */
+export declare function activeFormatCodeCache(): FormatCodeCache | undefined;

package/helpers/format-cache.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withFormatCodeCache = withFormatCodeCache;
+exports.activeFormatCodeCache = activeFormatCodeCache;
+let active;
+/**
+ * Runs `run` with `cache` installed for every `formatCode` call it makes synchronously, and
+ * restores the previous one afterwards.
+ * @param cache The cache to install, or undefined for none.
+ * @param run The synchronous work that formats.
+ */
+function withFormatCodeCache(cache, run) {
+    const previous = active;
+    active = cache;
+    try {
+        return run();
+    }
+    finally {
+        active = previous;
+    }
+}
+/** The cache installed by {@link withFormatCodeCache}, if any. */
+function activeFormatCodeCache() {
+    return active;
+}
+//# sourceMappingURL=format-cache.js.map

package/helpers/format-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"format-cache.js","sourceRoot":"","sources":["../../../../libs/builder/helpers/format-cache.ts"],"names":[],"mappings":";;AAkCA,kDAQC;AAGD,sDAEC;AArBD,IAAI,MAAmC,CAAC;AAExC;;;;;GAKG;AACH,SAAgB,mBAAmB,CAAI,KAAkC,EAAE,GAAY;IACrF,MAAM,QAAQ,GAAG,MAAM,CAAC;IACxB,MAAM,GAAG,KAAK,CAAC;IACf,IAAI,CAAC;QACH,OAAO,GAAG,EAAE,CAAC;IACf,CAAC;YAAS,CAAC;QACT,MAAM,GAAG,QAAQ,CAAC;IACpB,CAAC;AACH,CAAC;AAED,kEAAkE;AAClE,SAAgB,qBAAqB;IACnC,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/helpers/format-code.js

@@ -4,6 +4,7 @@ exports.formatCode = formatCode;
 const tslib_1 = require("tslib");
 const sync_1 = tslib_1.__importDefault(require("@prettier/sync"));
 const node_path_1 = require("node:path");
+const format_cache_1 = require("./format-cache");
 /**
  *    Format code with Prettier
  * @param code - Code to format
@@ -14,14 +15,20 @@ function formatCode(code, codeType = 'TypeScript', configDirectory) {
     try {
         if (codeType) {
             const parser = getPrettierParserFromCodeType(codeType);
-            const config = sync_1.default.resolveConfig(
+            // The new engine's cache, when it formats (see `./format-cache`); none in the legacy engine.
+            const cache = (0, format_cache_1.activeFormatCodeCache)();
+            const resolve = () => sync_1.default.resolveConfig(
             // Prettier searches from a file's parent, so use a synthetic path inside the directory.
             configDirectory ? (0, node_path_1.join)(configDirectory, '__ng_doc_format__.ts') : process.cwd(), { editorconfig: true, useCache: false });
-            return sync_1.default.format(code, {
+            const config = cache ? cache.config(configDirectory, resolve) : resolve();
+            const format = () => sync_1.default.format(code, {
                 ...config,
                 parser,
                 embeddedLanguageFormatting: 'auto',
             }).trim();
+            return cache && typeof parser === 'string'
+                ? cache.format({ code, parser, config }, format)
+                : format();
         }
         return code.trim();
     }

package/helpers/format-code.js.map

@@ -1 +1 @@
-{"version":3,"file":"format-code.js","sourceRoot":"","sources":["../../../../libs/builder/helpers/format-code.ts"],"names":[],"mappings":";;AAWA,gCA2BC;;AArCD,kEAA0C;AAC1C,yCAAiC;AAGjC;;;;;GAKG;AACH,SAAgB,UAAU,CACxB,IAAY,EACZ,WAAiC,YAAY,EAC7C,eAAwB;IAExB,IAAI,CAAC;QACH,IAAI,QAAQ,EAAE,CAAC;YACb,MAAM,MAAM,GAAkC,6BAA6B,CAAC,QAAQ,CAAC,CAAC;YACtF,MAAM,MAAM,GAAG,cAAY,CAAC,aAAa;YACvC,wFAAwF;YACxF,eAAe,CAAC,CAAC,CAAC,IAAA,gBAAI,EAAC,eAAe,EAAE,sBAAsB,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,EAAE,EAC/E,EAAE,YAAY,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,CACxC,CAAC;YAEF,OACE,cAAY,CAAC,MAAM,CAAC,IAAI,EAAE;gBACxB,GAAG,MAAM;gBACT,MAAM;gBACN,0BAA0B,EAAE,MAAM;aACnC,CACF,CAAC,IAAI,EAAE,CAAC;QACX,CAAC;QAED,OAAO,IAAI,CAAC,IAAI,EAAE,CAAC;IACrB,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,SAAS,6BAA6B,CAAC,QAAuB;IAC5D,QAAQ,QAAQ,EAAE,CAAC;QACjB,KAAK,KAAK,CAAC;QACX,KAAK,MAAM,CAAC;QACZ,KAAK,MAAM,CAAC;QACZ,KAAK,MAAM;YACT,OAAO,KAAK,CAAC;QACf,KAAK,MAAM;YACT,OAAO,MAAM,CAAC;QAChB,KAAK,YAAY,CAAC;QAClB,KAAK,YAAY;YACf,OAAO,YAAY,CAAC;QACtB,KAAK,UAAU;YACb,OAAO,UAAU,CAAC;QACpB;YACE,OAAO,SAAS,CAAC;IACrB,CAAC;AACH,CAAC"}
+{"version":3,"file":"format-code.js","sourceRoot":"","sources":["../../../../libs/builder/helpers/format-code.ts"],"names":[],"mappings":";;AAaA,gCAmCC;;AA/CD,kEAA0C;AAC1C,yCAAiC;AAGjC,iDAAuD;AAEvD;;;;;GAKG;AACH,SAAgB,UAAU,CACxB,IAAY,EACZ,WAAiC,YAAY,EAC7C,eAAwB;IAExB,IAAI,CAAC;QACH,IAAI,QAAQ,EAAE,CAAC;YACb,MAAM,MAAM,GAAkC,6BAA6B,CAAC,QAAQ,CAAC,CAAC;YACtF,6FAA6F;YAC7F,MAAM,KAAK,GAAG,IAAA,oCAAqB,GAAE,CAAC;YACtC,MAAM,OAAO,GAAG,GAAG,EAAE,CACnB,cAAY,CAAC,aAAa;YACxB,wFAAwF;YACxF,eAAe,CAAC,CAAC,CAAC,IAAA,gBAAI,EAAC,eAAe,EAAE,sBAAsB,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,EAAE,EAC/E,EAAE,YAAY,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,CACxC,CAAC;YACJ,MAAM,MAAM,GAAG,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,eAAe,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;YAC1E,MAAM,MAAM,GAAG,GAAG,EAAE,CAEhB,cAAY,CAAC,MAAM,CAAC,IAAI,EAAE;gBACxB,GAAG,MAAM;gBACT,MAAM;gBACN,0BAA0B,EAAE,MAAM;aACnC,CACF,CAAC,IAAI,EAAE,CAAC;YAEX,OAAO,KAAK,IAAI,OAAO,MAAM,KAAK,QAAQ;gBACxC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,MAAM,CAAC;gBAChD,CAAC,CAAC,MAAM,EAAE,CAAC;QACf,CAAC;QAED,OAAO,IAAI,CAAC,IAAI,EAAE,CAAC;IACrB,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,SAAS,6BAA6B,CAAC,QAAuB;IAC5D,QAAQ,QAAQ,EAAE,CAAC;QACjB,KAAK,KAAK,CAAC;QACX,KAAK,MAAM,CAAC;QACZ,KAAK,MAAM,CAAC;QACZ,KAAK,MAAM;YACT,OAAO,KAAK,CAAC;QACf,KAAK,MAAM;YACT,OAAO,MAAM,CAAC;QAChB,KAAK,YAAY,CAAC;QAClB,KAAK,YAAY;YACf,OAAO,YAAY,CAAC;QACtB,KAAK,UAAU;YACb,OAAO,UAAU,CAAC;QACpB;YACE,OAAO,SAAS,CAAC;IACrB,CAAC;AACH,CAAC"}

package/helpers/to-template-string.d.ts

@@ -1,5 +1,9 @@
 /**
+ * Escapes text for the body of a template literal, so the literal evaluates to the text itself.
  *
- * @param content
+ * The backslash is escaped first: otherwise `\d` would evaluate to `d`, `\n` to a line break and
+ * `\203A` would fail to compile (octal escapes are not allowed in template literals), and the
+ * escapes added for `` ` `` and `${` must not be escaped again.
+ * @param content - The text to embed.
  */
 export declare function toTemplateString(content: string): string;

package/helpers/to-template-string.js

@@ -2,12 +2,17 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.toTemplateString = toTemplateString;
 /**
+ * Escapes text for the body of a template literal, so the literal evaluates to the text itself.
  *
- * @param content
+ * The backslash is escaped first: otherwise `\d` would evaluate to `d`, `\n` to a line break and
+ * `\203A` would fail to compile (octal escapes are not allowed in template literals), and the
+ * escapes added for `` ` `` and `${` must not be escaped again.
+ * @param content - The text to embed.
  */
 function toTemplateString(content) {
     return (content
-        ?.replace(/`/g, '\\`')
+        ?.replace(/\\/g, '\\\\')
+        .replace(/`/g, '\\`')
         .replace(/\${/g, '\\${')
         .replace(/{/g, '\\{')
         .replace(/}/g, '\\}') ?? '');

package/helpers/to-template-string.js.map

@@ -1 +1 @@
-{"version":3,"file":"to-template-string.js","sourceRoot":"","sources":["../../../../libs/builder/helpers/to-template-string.ts"],"names":[],"mappings":";;AAIA,4CAQC;AAZD;;;GAGG;AACH,SAAgB,gBAAgB,CAAC,OAAe;IAC/C,OAAO,CACN,OAAO;QACN,EAAE,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC;SACrB,OAAO,CAAC,MAAM,EAAE,MAAM,CAAC;SACvB,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC;SACpB,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,CAC5B,CAAC;AACH,CAAC"}
+{"version":3,"file":"to-template-string.js","sourceRoot":"","sources":["../../../../libs/builder/helpers/to-template-string.ts"],"names":[],"mappings":";;AAQA,4CASC;AAjBD;;;;;;;GAOG;AACH,SAAgB,gBAAgB,CAAC,OAAe;IAC9C,OAAO,CACL,OAAO;QACL,EAAE,OAAO,CAAC,KAAK,EAAE,MAAM,CAAC;SACvB,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC;SACpB,OAAO,CAAC,MAAM,EAAE,MAAM,CAAC;SACvB,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC;SACpB,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,CAC9B,CAAC;AACJ,CAAC"}

package/interfaces/code-block-options.d.ts

@@ -8,5 +8,10 @@ export interface NgDocCodeBlockParams {
     icon?: string;
     fileLineStart?: number;
     fileLineEnd?: number;
+    /**
+     * The snippet of `file` to show, from `file="./x.ts"#<id>`: the lines between the two
+     * `snippet#<id>` markers. Only the Vite engine reads it.
+     */
+    snippet?: string;
     highlightedLines?: number[];
 }

package/interfaces/configuration.d.ts

@@ -1,4 +1,4 @@
-import { NgDocHeading, NgDocKeywordsLoader } from '@ng-doc/core';
+import { NgDocDemoProvidersImport, NgDocHeading, NgDocKeywordsLoader } from '@ng-doc/core';
 import { NgDocGlobalKeyword } from '@ng-doc/core/interfaces/keyword-map';
 import { NgDocRepoConfig } from './repo-config';
 /**
@@ -43,6 +43,30 @@ export interface NgDocConfiguration {
      * The configuration for the guides
      */
     guide?: NgDocGuideConfiguration;
+    /**
+     * The configuration for the API pages. Only the Vite engine reads it.
+     */
+    api?: NgDocApiConfiguration;
+    /**
+     * Shows every demo of the `demo` action in an iframe, as `isolated: true` does for one demo
+     * (`false` by default). It also builds a demo page for every demo. Only the Vite engine reads it.
+     */
+    isolatedDemos?: boolean;
+    /**
+     * The demo pages: one page per demo that loads only Angular and that demo, which isolated demos
+     * show in an iframe and "Open in new tab" opens. Only the Vite engine builds them.
+     *
+     * By default only the pages with an isolated demo get them. `true` (or an object) builds them for
+     * every page with demos; `false` never builds them, and isolated demos render in the page.
+     */
+    demoApplication?: boolean | NgDocDemoApplicationConfiguration;
+    /**
+     * Imports the module whose default export lists the providers of the demo pages, for example
+     * `() => import('./demo.providers')`. It must be written in `ng-doc.config.ts` as an arrow
+     * function that returns one `import()` of a file. NgDoc never calls it while it generates; the
+     * demo pages import the module. Only the Vite engine reads it.
+     */
+    demoProviders?: NgDocDemoProvidersImport;
     /**
      * Shiki configuration
      */
@@ -51,8 +75,43 @@ export interface NgDocConfiguration {
             light: string;
             dark: string;
         };
+        /**
+         * Shiki language registrations that code blocks can use in addition to the languages bundled
+         * with Shiki, such as a grammar imported from a `.tmLanguage.json` file or from
+         * `@shikijs/langs`. A registration named like a bundled language replaces it. Only the Vite
+         * engine reads it; load the same languages in the browser with `provideNgDocApp`.
+         */
+        langs?: Array<NgDocShikiLanguage | readonly NgDocShikiLanguage[]>;
     };
 }
+/**
+ * A Shiki (TextMate) language registration: a grammar and the name that code blocks use for it.
+ * It must be plain JSON data, as in a `.tmLanguage.json` file or a module of `@shikijs/langs`.
+ */
+export interface NgDocShikiLanguage {
+    /** The language name: code blocks that name it (for example ` ```my-lang `) use the grammar. */
+    name: string;
+    /** The root scope of the grammar, such as `source.my-lang`. */
+    scopeName: string;
+    /** The name to display for the language. */
+    displayName?: string;
+    /** Other names that code blocks can use for the language. */
+    aliases?: string[];
+    /** The languages that the grammar embeds, which must be bundled or registered too. */
+    embeddedLangs?: string[];
+    /** The languages that the grammar embeds when they are loaded. */
+    embeddedLangsLazy?: string[];
+    /** The scopes that the grammar injects itself into. */
+    injectTo?: string[];
+    /** The TextMate rules of the grammar. */
+    patterns?: unknown;
+    /** The named TextMate rules that `patterns` include. */
+    repository?: unknown;
+    /** TextMate injections. */
+    injections?: unknown;
+    /** The selector of an injection grammar. */
+    injectionSelector?: string;
+}
 /**
  * The configuration for the guide page
  */
@@ -67,6 +126,30 @@ export interface NgDocGuideConfiguration {
      */
     headerTemplate?: string;
 }
+/**
+ * The configuration for the API pages.
+ */
+export interface NgDocApiConfiguration {
+    /**
+     * Whether API pages list the protected members of classes, inherited ones included
+     * (`true` by default). With `false`, they list only public members: hidden members get no row,
+     * anchor, search record or keyword.
+     */
+    protectedMembers?: boolean;
+}
+/**
+ * The configuration of the demo pages.
+ */
+export interface NgDocDemoApplicationConfiguration {
+    /**
+     * The URL path under which the demo pages are served, relative to the base href
+     * (`demo-preview` by default): a demo's page is `<base href><path>/<page route>/<demo name>/`.
+     * One or more URL segments of letters, digits, `-`, `_` and `.`; the first character of a
+     * segment is a letter or a digit, because some static hosts skip folders that start with `_`
+     * or `.`.
+     */
+    path?: string;
+}
 /**
  * The configuration for the global keywords.
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ng-doc/builder",
-  "version": "22.0.0",
+  "version": "22.1.0",
   "description": "Generates an NgDoc documentation site from your Markdown pages and TypeScript code.",
   "keywords": [
     "angular",
@@ -31,8 +31,8 @@
     ]
   },
   "dependencies": {
-    "@ng-doc/core": "22.0.0",
-    "@ng-doc/utils": "22.0.0",
+    "@ng-doc/core": "22.1.0",
+    "@ng-doc/utils": "22.1.0",
     "@angular-devkit/architect": ">=0.2200.0 <0.2300.0",
     "minimatch": "9.0.9",
     "rxjs": "^7.0.0",
@@ -56,7 +56,8 @@
     "parsimmon": "^1.18.1",
     "@parcel/watcher": "^2.5.0",
     "@microsoft/tsdoc": "0.15.1",
-    "@shikijs/rehype": "1.10.3",
+    "@shikijs/rehype": "4.5.0",
+    "shiki": "4.5.0",
     "css-what": "6.1.0",
     "github-slugger": "2.0.0",
     "hast-util-has-property": "3.0.0",

package/parsers/parse-code-block-params.d.ts

@@ -1,6 +1,15 @@
 import type { NgDocCodeBlockParams } from '../interfaces/code-block-options';
+/** Options of {@link parseCodeBlockParams}. */
+export interface NgDocCodeBlockParserOptions {
+    /**
+     * Whether a fragment after the `file` parameter may name a snippet: `file="./x.ts"#greeting`.
+     * Without it, only line ranges are accepted, and any other fragment fails to parse.
+     */
+    snippets?: boolean;
+}
 /**
  * Code block options parser
  * @param options - Options string to parse
+ * @param parserOptions - What the caller supports beyond the original syntax.
  */
-export declare function parseCodeBlockParams(options: string): NgDocCodeBlockParams;
+export declare function parseCodeBlockParams(options: string, parserOptions?: NgDocCodeBlockParserOptions): NgDocCodeBlockParams;

package/parsers/parse-code-block-params.js

@@ -10,11 +10,31 @@ const helpers_1 = require("./helpers");
  * whitespace end it, so the parameters that follow are parsed as before.
  */
 const CODE_BLOCK_LANGUAGE = /[\p{L}\p{N}+#-]+/u;
+/** The characters of a snippet id, as `// snippet#<id>` markers spell it (`parseSnippet`). */
+const SNIPPET_ID = /[a-zA-Z0-9-]+/;
+/** A fragment that is a line range: `L<n>`, `L<n>-` or `L<n>-L<m>`. */
+const LINE_RANGE = /^L(\d+)(?:(-)(?:L(\d+))?)?$/;
+/**
+ * The fragment after a `file` parameter when snippets are on: `#L<n>`, `#L<n>-` and
+ * `#L<n>-L<m>` are line ranges (the same ranges as without snippets), any other id names a
+ * snippet.
+ * @param fragment - The fragment without its `#`.
+ */
+function fileFragment(fragment) {
+    const range = LINE_RANGE.exec(fragment);
+    if (!range)
+        return { snippet: fragment };
+    const fileLineStart = Number(range[1]) - 1;
+    if (!range[2])
+        return { fileLineStart, fileLineEnd: fileLineStart + 1 };
+    return { fileLineStart, fileLineEnd: range[3] === undefined ? undefined : Number(range[3]) };
+}
 /**
  * Code block options parser
  * @param options - Options string to parse
+ * @param parserOptions - What the caller supports beyond the original syntax.
  */
-function parseCodeBlockParams(options) {
+function parseCodeBlockParams(options, parserOptions = {}) {
     const parser = parsimmon_1.default.createLanguage({
         language: () => parsimmon_1.default.regexp(CODE_BLOCK_LANGUAGE)
             .skip(parsimmon_1.default.optWhitespace)
@@ -28,7 +48,9 @@ function parseCodeBlockParams(options) {
             .then(p['fileLineNumber'])
             .map((num) => num - 1)
             .map((fileLineStart) => ({ fileLineStart, fileLineEnd: fileLineStart + 1 })),
-        lineParams: (p) => p['fileLineRange'].or(p['fileLineStart']).fallback({}),
+        lineParams: (p) => (parserOptions.snippets
+            ? parsimmon_1.default.string('#').then(parsimmon_1.default.regexp(SNIPPET_ID)).map(fileFragment)
+            : p['fileLineRange'].or(p['fileLineStart'])).fallback({}),
         highlightedLinesRange: () => parsimmon_1.default.seqMap(helpers_1.number.skip(parsimmon_1.default.string('-')), helpers_1.number, (start, end) => [...Array(end + 1).keys()].slice(start - end - 1)),
         // Main Parsers
         lineNumbers: () => parsimmon_1.default.string('lineNumbers').map(() => ({ lineNumbers: true })),
@@ -38,7 +60,11 @@ function parseCodeBlockParams(options) {
         fileName: () => (0, helpers_1.param)('fileName', 'name'),
         icon: () => (0, helpers_1.param)('icon'),
         active: () => parsimmon_1.default.string('active').map(() => ({ active: true })),
-        file: (p) => parsimmon_1.default.seq(p['filePath'], p['lineParams'].map(({ fileLineStart, fileLineEnd }) => ({ fileLineStart, fileLineEnd }))).map(([file, lineParams]) => ({ ...file, ...lineParams })),
+        file: (p) => parsimmon_1.default.seq(p['filePath'], p['lineParams'].map(({ fileLineStart, fileLineEnd, snippet }) => ({
+            fileLineStart,
+            fileLineEnd,
+            ...(snippet === undefined ? {} : { snippet }),
+        }))).map(([file, lineParams]) => ({ ...file, ...lineParams })),
         highlightedLines: (p) => p['highlightedLinesRange']
             .or(helpers_1.number)
             .sepBy(parsimmon_1.default.string(',').then(parsimmon_1.default.optWhitespace))

package/parsers/parse-code-block-params.js.map

@@ -1 +1 @@
-{"version":3,"file":"parse-code-block-params.js","sourceRoot":"","sources":["../../../../libs/builder/parsers/parse-code-block-params.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"parse-code-block-params.js","sourceRoot":"","sources":["../../../../libs/builder/parsers/parse-code-block-params.ts"],"names":[],"mappings":"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"}

package/schematics/collection.json

@@ -22,7 +22,7 @@
       "schema": "./migrate-to-vite/schema.json"
     },
     "vite-setup": {
-      "description": "Sets up the Vite engine for a project on Angular's application builder (run by ng add @ng-doc/add)",
+      "description": "Sets up the Vite engine for a project on Angular's application builder or Nx's application executor (run by ng add @ng-doc/add)",
       "factory": "./vite-setup/index#viteSetup",
       "schema": "./vite-setup/schema.json",
       "hidden": true

package/schematics/migrate-to-vite/analyze.js

@@ -106,7 +106,15 @@ const MANUAL = {
     serviceWorker: 'The Vite engine does not build the Angular service worker.',
     subresourceIntegrity: 'Use a Vite plugin to add `integrity` attributes.',
     webWorkerTsConfig: 'Vite bundles workers created with `new Worker(new URL(...))` itself.',
+    // Nx's `application` executor runs Angular's builder with these options of its own.
+    indexHtmlTransformer: 'Nx transforms index.html with this function; move it to a Vite plugin with a `transformIndexHtml` hook.',
+    plugins: 'Nx runs these esbuild plugins and Vite does not; add a Vite plugin that does the same to the Vite configuration.',
 };
+/**
+ * `buildLibsFromSource: false` of Nx's executors: Nx builds the buildable libraries first and
+ * resolves them to their output.
+ */
+const BUILD_LIBS_FROM_SOURCE = 'is `false`; the Vite engine reads the workspace libraries from source through the tsconfig `paths` and does not build them first.';
 function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
@@ -526,11 +534,17 @@ function analyzeProject(tree, project, buildName, serveName, options, builderKey
             else
                 add('dropped', 'build.outputHashing', 'Vite hashes the output file names by default.');
         }
-        else if (option === 'scripts') {
+        else if (option === 'scripts' || option === 'plugins') {
             if (values.some((value) => Array.isArray(value) && value.length))
-                add('manual', 'build.scripts', MANUAL['scripts']);
+                add('manual', `build.${option}`, MANUAL[option]);
+            else
+                add('dropped', `build.${option}`, 'The list is empty.');
+        }
+        else if (option === 'buildLibsFromSource') {
+            if (values.includes(false))
+                add('manual', 'build.buildLibsFromSource', BUILD_LIBS_FROM_SOURCE);
             else
-                add('dropped', 'build.scripts', 'The list is empty.');
+                add('dropped', 'build.buildLibsFromSource', 'The Vite engine reads the workspace libraries from source through the tsconfig `paths`.');
         }
         else if (option === 'serviceWorker') {
             if (active.length)
@@ -744,6 +758,35 @@ function analyzeServe(project, serveName, buildName, build, add, plainMode) {
             case 'verbose':
                 add('dropped', subject, 'Vite prebundles dependencies and logs by its own settings.');
                 break;
+            // The options Nx's `dev-server` executor adds to Angular's.
+            case 'buildLibsFromSource':
+                if (value === false)
+                    add('manual', subject, BUILD_LIBS_FROM_SOURCE);
+                else
+                    add('dropped', subject, 'The Vite engine reads the workspace libraries from source.');
+                break;
+            case 'watchDependencies':
+                add('dropped', subject, 'The Vite engine watches the library sources it reads.');
+                break;
+            case 'forceEsbuild':
+            case 'publicHost':
+                add('dropped', subject, 'Nx uses it with webpack-based builds only.');
+                break;
+            case 'disableHostCheck':
+                if (value === true) {
+                    devServer.allowedHosts = true;
+                    add('migrated', subject, 'Vite `server.allowedHosts: true`.');
+                }
+                else
+                    add('dropped', subject, 'The host check is on.');
+                break;
+            case 'esbuildMiddleware':
+                if (Array.isArray(value) && value.length) {
+                    add('manual', subject, 'Add these middleware functions with the `configureServer` hook of a Vite plugin.');
+                }
+                else
+                    add('dropped', subject, 'The list is empty.');
+                break;
             case 'ngDoc':
                 add('manual', subject, 'The development server uses the NgDoc settings of the build target.');
                 break;