@baiyibai-antora/extensions 1.7.0 → 1.8.0

package/CHANGELOG.adoc

@@ -3,6 +3,12 @@
 
 All notable changes to this project will be documented in this file.
 
+== [1.8.0] - 2026-08-17
+
+=== Added
+
+* autoterm: generates a Terminology section and a linked Index from AsciiDoc index term markup, replacing the asciidoctor-autoterm gem and its stub-page extension. A component participates by including `partial$generated-terminology.adoc` or `partial$generated-index.adoc` on a page; definitions merge from the shared `terminology_file` partial with a component's `terminology-local.adoc` rows winning. The PDF index renders through `:assembly-style: index` and stock Asciidoctor PDF; the HTML and Confluence index links to the pages using each term
+
 == [1.7.0] - 2026-08-17
 
 === Added

package/dist/extensions/autoterm/index.d.ts

@@ -0,0 +1,210 @@
+/**
+ * @baiyibai-antora/extensions - autoterm
+ *
+ * Scans the Antora content catalog for AsciiDoc index term markup and injects
+ * two generated AsciiDoc partials into each participating component-version:
+ *
+ *   modules/ROOT/partials/generated-terminology.adoc
+ *   modules/ROOT/partials/generated-index.adoc
+ *
+ * A component participates by containing a page that includes the partial:
+ *
+ *   include::partial$generated-terminology.adoc[]
+ *   include::partial$generated-index.adoc[]
+ *
+ * The including page's position in nav.adoc controls where the section
+ * appears. The terminology page carries :!sectnums: to render unnumbered.
+ * The index page carries :assembly-style: index so the Antora Assembler
+ * preserves the [index] section and stock asciidoctor-pdf renders the
+ * page-numbered index; the generated index partial holds the web-linked
+ * index guarded by ifndef::loader-assembler[] so it renders only outside
+ * the PDF build.
+ *
+ * Definitions come from a shared table (the autoterm-data component's
+ * partial) optionally overridden per component by a local partial named
+ * trademark-local-style: modules/ROOT/partials/terminology-local.adoc.
+ * Local rows replace shared rows for the same term.
+ *
+ * Configuration in antora-playbook.yml:
+ *
+ * antora:
+ *   extensions:
+ *     - require: '@baiyibai-antora/extensions/autoterm'
+ *       autoterm:
+ *         enabled: true
+ *         # Antora resource ID or filename of the shared definitions partial.
+ *         terminology_file: 'ROOT:partial$terminology-table.adoc'
+ *         # Filename of a component's local override partial.
+ *         local_file: 'terminology-local.adoc'
+ *         # Filenames of the generated partials.
+ *         terminology_partial: 'generated-terminology.adoc'
+ *         index_partial: 'generated-index.adoc'
+ *         # AsciiDoc cols attribute for each generated table.
+ *         terminology_cols: '15,85'
+ *         index_cols: '30,70'
+ *         # 'combined' welds each letter into its group's first row (default);
+ *         # 'separate' emits the letter as its own row (may orphan at a page
+ *         # bottom in the PDF).
+ *         letter_style: 'combined'
+ *         # Attribution line rendered above the Terminology content outside
+ *         # the PDF build. AsciiDoc inline markup allowed; empty disables.
+ *         attribution: 'Generated by https://gitlab.com/baiyibai-antora/baiyibai-extensions[autoterm].'
+ *
+ * The including page overrides presentation per component through header
+ * attributes: :autoterm-terminology-cols:, :autoterm-index-cols:,
+ * :autoterm-letter-style:.
+ *
+ * The generated partials live in the content catalog and regenerate on every
+ * build. Setting write_to_disk: true additionally writes them into the
+ * component's local worktree; components loaded from a remote source skip
+ * the disk write, mirroring trademark-it.
+ *
+ * Per-component configuration in a component's antora.yml under
+ * ext.autoterm overrides local_file, terminology_cols, index_cols,
+ * letter_style, write_to_disk, and enabled for that component-version.
+ * Unlike trademark-it, the block is optional: participation comes from the
+ * include, not from the block.
+ */
+interface AutotermConfig {
+    enabled: boolean;
+    quiet: boolean;
+    terminology_file: string;
+    local_file: string;
+    terminology_partial: string;
+    index_partial: string;
+    terminology_cols: string;
+    index_cols: string;
+    letter_style: 'combined' | 'separate';
+    attribution: string;
+    write_to_disk: boolean;
+    suppress_events: boolean;
+}
+export interface TermDefinition {
+    fullTerm: string;
+    abbreviation: string;
+    definition: string;
+}
+export interface IndexTerm {
+    /** Full term without the abbreviation parenthetical, trimmed. */
+    full: string;
+    /** Abbreviation from the trailing parenthetical, or null. */
+    abbr: string | null;
+}
+interface AntoraLogger {
+    debug?: (msg: string) => void;
+    info?: (msg: string) => void;
+    warn?: (msg: string) => void;
+    error?: (msg: string) => void;
+}
+interface ExtensionEntry {
+    require?: string;
+    autoterm?: Partial<AutotermConfig>;
+    autoTerm?: Partial<AutotermConfig>;
+}
+interface Playbook {
+    dir: string;
+    antora?: {
+        extensions?: ExtensionEntry[];
+    };
+}
+interface VirtualFileOrigin {
+    worktree?: string;
+    startPath?: string;
+    type?: string;
+}
+interface VirtualFileSrc {
+    path?: string;
+    family?: string;
+    component?: string;
+    version?: string;
+    module?: string;
+    relative?: string;
+    basename?: string;
+    stem?: string;
+    extname?: string;
+    origin?: VirtualFileOrigin;
+    mediaType?: string;
+}
+interface VirtualFile {
+    src: VirtualFileSrc;
+    contents: Buffer | Uint8Array;
+}
+interface ContentCatalog {
+    getFiles: () => VirtualFile[];
+    addFile: (file: {
+        contents: Buffer;
+        src: VirtualFileSrc;
+    }) => void;
+}
+interface ContentAggregateItem {
+    name: string;
+    version: string;
+    ext?: Record<string, Record<string, unknown>>;
+}
+interface Registry {
+    getLogger?: (name: string) => AntoraLogger;
+    once(event: 'contentAggregated', callback: (context: {
+        contentAggregate: ContentAggregateItem[];
+    }) => void): void;
+    once(event: 'playbookBuilt', callback: (context: {
+        playbook: Playbook;
+    }) => Promise<void>): void;
+    once(event: 'contentClassified', callback: (context: {
+        playbook: Playbook;
+        contentCatalog?: ContentCatalog;
+    }) => Promise<void>): void;
+    once(event: string, callback: (context: unknown) => void): void;
+}
+export declare function parseTerminologyTable(asciidocText: string): Map<string, TermDefinition>;
+/**
+ * Merge a component-local definitions map over the shared map. A local entry
+ * replaces the shared entry whose full term matches exactly, mirroring the
+ * exact-key lookup the definitions serve; remaining local entries are added.
+ */
+export declare function mergeTerminology(shared: Map<string, TermDefinition>, local: Map<string, TermDefinition>): {
+    merged: Map<string, TermDefinition>;
+    overridden: string[];
+};
+/**
+ * Blank the content of listing and literal blocks (---- and .... fences).
+ * Asciidoctor does not process index terms in verbatim context, so the
+ * scanner must not either; documentation showing ((...)) syntax inside a
+ * listing stays inert. Line count is preserved.
+ */
+export declare function stripVerbatimBlocks(text: string): string;
+export declare function scanIndexterms(sourceText: string, ignoreConditionals?: string[]): IndexTerm[];
+interface TerminologyEntry {
+    label: string;
+    body: string;
+    sortKey: string;
+    letter: string;
+}
+/**
+ * Build the terminology entries from the scanned terms and the merged
+ * definitions, applying the ledger rules: a term with an abbreviation always
+ * appears; a term without one appears only when it has a definition; the
+ * entry label is the abbreviation or the full term; the body is
+ * "Full Term – definition" for abbreviated terms, the definition alone
+ * otherwise; duplicate full terms keep the last-scanned occurrence.
+ */
+export declare function buildTerminologyEntries(terms: IndexTerm[], definitions: Map<string, TermDefinition>): TerminologyEntry[];
+export declare function generateTerminologyPartial(entries: TerminologyEntry[], cols?: string, letterStyle?: 'combined' | 'separate', attribution?: string): string;
+export interface IndexOccurrence {
+    display: string;
+    sortKey: string;
+    letter: string;
+    /** xref targets: module, relative, page title */
+    pages: Array<{
+        module: string;
+        relative: string;
+        title: string;
+    }>;
+}
+export declare function generateIndexPartial(occurrences: IndexOccurrence[], cols?: string): string;
+/** Extract the page title from raw AsciiDoc source. */
+export declare function pageTitle(sourceText: string): string;
+/** Read a :name: value from a raw page header, or null. */
+export declare function pageAttribute(sourceText: string, name: string): string | null;
+export declare function register(this: Registry, context?: Registry): void;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/extensions/autoterm/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/extensions/autoterm/index.ts"],"names":[],"mappings":"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"}