@baiyibai-antora/extensions 1.0.0

package/README.adoc

@@ -0,0 +1,645 @@
+= Baiyibai Docs Extensions
+:toc: left
+:toclevels: 3
+:sectnums:
+:source-highlighter: highlight.js
+
+A consolidated package of Antora extensions for documentation workflows.
+
+== Overview
+
+This package provides six Antora extensions:
+
+[cols="1,3"]
+|===
+|Extension |Description
+
+|<<collector-writer>>
+|Writes collected content (themes, Vale rules) from Antora's content catalog to disk
+
+|<<assembler-ruby-preflight>>
+|Validates Ruby/Ghostscript versions and manages gem dependencies for PDF generation
+
+|<<assembler-rename-pdf>>
+|Renames PDF exports based on document attributes
+
+|<<external-asset-downloader>>
+|Downloads external assets from HTTP/HTTPS URLs
+
+|<<vale-integration>>
+|Integrates Vale linting into the Antora build pipeline
+
+|<<asciidoctorconfig>>
+|Copies `.asciidoctorconfig` files from content catalog to project root
+|===
+
+== Installation
+
+[source,bash]
+----
+npm install @baiyibai-antora/extensions
+----
+
+== Quick Start
+
+Add extensions to your `antora-playbook.yml`:
+
+[source,yaml]
+----
+antora:
+  extensions:
+    - require: '@baiyibai-antora/extensions/collector-writer'
+      collectorWriter:
+        enabled: true
+        targets:
+          - component: vale-styles
+            write_dir: ./vale-rules
+            ephemeral: true
+----
+
+== Extension Pairings
+
+Some extensions work well together:
+
+=== PDF Generation Pipeline
+
+For PDF generation, use these extensions in order:
+
+1. **collector-writer** - Writes PDF themes (Gemfile, YAML configs) to disk
+2. **assembler-ruby-preflight** - Validates Ruby/Ghostscript and installs gems
+3. **assembler-rename-pdf** - Renames generated PDFs based on attributes
+
+[source,yaml]
+----
+antora:
+  extensions:
+    # 1. Write themes to disk
+    - require: '@baiyibai-antora/extensions/collector-writer'
+      collectorWriter:
+        enabled: true
+        targets:
+          - component: pdf-themes
+            write_dir: ./assembler-themes
+            ephemeral: false
+
+    # 2. Validate Ruby and install gems
+    - require: '@baiyibai-antora/extensions/assembler-ruby-preflight'
+      preflight:
+        enabled: true
+        gemfile_path: './assembler-themes/Gemfile'
+
+    # 3. Rename PDFs after generation
+    - require: '@baiyibai-antora/extensions/assembler-rename-pdf'
+      renamer:
+        enabled: true
+        pdf_filename_attribute: 'pdf-filename'
+----
+
+=== Vale Linting Pipeline
+
+For Vale integration, use these extensions:
+
+1. **collector-writer** - Writes Vale styles/rules to disk
+2. **vale-integration** - Runs Vale linting on content
+
+[source,yaml]
+----
+antora:
+  extensions:
+    # 1. Write Vale rules to disk
+    - require: '@baiyibai-antora/extensions/collector-writer'
+      collectorWriter:
+        enabled: true
+        targets:
+          - component: vale-styles
+            write_dir: ./vale-rules
+            ephemeral: true
+
+    # 2. Run Vale linting
+    - require: '@baiyibai-antora/extensions/vale-integration'
+      vale:
+        enabled: true
+        config_file: './vale-rules/.vale.ini'
+----
+
+== Extension Reference
+
+[[collector-writer]]
+=== collector-writer
+
+Copies assets discovered by `@antora/collector-extension` from the Antora content catalog into local folders.
+
+==== Configuration
+
+[cols="2,1,3,2"]
+|===
+|Key |Type |Description |Default
+
+|`enabled`
+|boolean
+|Enable/disable the extension
+|`true`
+
+|`quiet`
+|boolean
+|Suppress informational output
+|`true`
+
+|`output_dir`
+|string
+|Base output directory
+|`'vale-output'`
+
+|`targets`
+|array
+|List of target configurations
+|`[]`
+
+|`required`
+|array
+|List of required component targets
+|`[]`
+|===
+
+==== Target Configuration
+
+[cols="2,1,3,2"]
+|===
+|Key |Type |Description |Default
+
+|`component`
+|string
+|Component name to match in content catalog
+|_(required)_
+
+|`write_dir`
+|string
+|Directory to write files to
+|`'target'`
+
+|`ephemeral`
+|boolean
+|Delete directory after site is published
+|`true`
+|===
+
+==== Playbook Configuration
+
+[source,yaml]
+----
+- require: '@baiyibai-antora/extensions/collector-writer'
+  collectorWriter:
+    enabled: true
+    quiet: false
+    targets:
+      - component: pdf-themes
+        write_dir: ./assembler-themes
+        ephemeral: false
+      - component: vale-styles
+        write_dir: ./vale-rules
+        ephemeral: true
+----
+
+[[assembler-ruby-preflight]]
+=== assembler-ruby-preflight
+
+Coordinates Ruby/Ghostscript version checks and gem bundling for PDF generation.
+
+==== Configuration
+
+[cols="2,1,3,2"]
+|===
+|Key |Type |Description |Default
+
+|`enabled`
+|boolean
+|Enable/disable the extension
+|`true`
+
+|`quiet`
+|boolean
+|Suppress informational output
+|`true`
+
+|`gemfile_path`
+|string
+|Path to source Gemfile
+|_(required for gem bundling)_
+
+|`use_system_gems`
+|boolean
+|Use system-installed gems instead of vendor/bundle
+|`false`
+
+|`platforms`
+|object
+|Per-platform configuration
+|_(see below)_
+|===
+
+==== Platform Configuration
+
+Each platform (`win32`, `linux`, `darwin`) supports:
+
+[cols="2,1,3,2"]
+|===
+|Key |Type |Description |Default
+
+|`ruby_version`
+|string
+|Expected Ruby version (e.g., `'3.3.8'`)
+|_(none)_
+
+|`ruby_revision`
+|string
+|Expected Ruby revision hash
+|_(none)_
+
+|`ruby_guidance`
+|string
+|Message shown if Ruby check fails
+|_(none)_
+
+|`gs_version`
+|string
+|Expected Ghostscript version
+|_(none)_
+
+|`gs_guidance`
+|string
+|Message shown if Ghostscript check fails
+|_(none)_
+
+|`check_ruby`
+|boolean
+|Enable Ruby version check
+|`true`
+
+|`check_gs`
+|boolean
+|Enable Ghostscript version check
+|`false` (linux), `true` (others)
+|===
+
+==== Playbook Configuration
+
+[source,yaml]
+----
+- require: '@baiyibai-antora/extensions/assembler-ruby-preflight'
+  preflight:
+    enabled: true
+    quiet: false
+    gemfile_path: './assembler-themes/Gemfile'
+    use_system_gems: true
+    platforms:
+      linux:
+        ruby_version: '3.3.8'
+        ruby_revision: 'b200bad6cd'
+        check_ruby: true
+        check_gs: false
+      win32:
+        ruby_version: '3.3.8'
+        gs_version: '10.05.1'
+        check_ruby: true
+        check_gs: true
+----
+
+[[assembler-rename-pdf]]
+=== assembler-rename-pdf
+
+Renames exported PDF files based on document attributes.
+
+==== Configuration
+
+[cols="2,1,3,2"]
+|===
+|Key |Type |Description |Default
+
+|`enabled`
+|boolean
+|Enable/disable the extension
+|`true`
+
+|`quiet`
+|boolean
+|Suppress informational output
+|`true`
+
+|`pdf_filename_attribute`
+|string
+|Document attribute containing the desired PDF filename
+|`'pdf-filename'`
+
+|`assembler_base_dir`
+|string
+|Base directory for assembler output
+|`'build/assembler-pdf'`
+
+|`site_base_dir`
+|string
+|Base directory for site output
+|_(uses playbook output.dir)_
+
+|`exports_subdir`
+|string
+|Subdirectory containing exports
+|`'_exports'`
+
+|`copy_target_dir`
+|string
+|Directory to copy renamed PDFs to
+|_(disabled)_
+|===
+
+==== Playbook Configuration
+
+[source,yaml]
+----
+- require: '@baiyibai-antora/extensions/assembler-rename-pdf'
+  renamer:
+    enabled: true
+    quiet: false
+    pdf_filename_attribute: 'pdf-filename'
+    assembler_base_dir: 'build/assembler-pdf'
+    exports_subdir: '_exports'
+    copy_target_dir: '.'
+----
+
+[[external-asset-downloader]]
+=== external-asset-downloader
+
+Downloads external assets from HTTP/HTTPS URLs into component directories.
+
+==== Configuration
+
+[cols="2,1,3,2"]
+|===
+|Key |Type |Description |Default
+
+|`enabled`
+|boolean
+|Enable/disable the extension
+|`true`
+
+|`quiet`
+|boolean
+|Suppress informational output
+|`true`
+
+|`attribute_prefix`
+|string
+|Attribute name prefix to scan (matches `image`, `image2`, etc.)
+|`'image'`
+
+|`include_commented`
+|boolean
+|Also scan commented attributes in antora.yml
+|`true`
+
+|`target_dir`
+|string
+|Directory to download assets to
+|_(required)_
+
+|`overwrite`
+|string
+|Overwrite behavior: `'never'` or `'always'`
+|`'never'`
+
+|`concurrency`
+|number
+|Number of concurrent downloads
+|`5`
+
+|`directory_listing`
+|boolean
+|Enable HTTP directory listing crawl
+|`false`
+
+|`url_replace`
+|array
+|URL transformation rules
+|`[]`
+|===
+
+==== URL Replace Rules
+
+[cols="2,1,3"]
+|===
+|Key |Type |Description
+
+|`pattern`
+|string
+|Regex pattern to match
+
+|`replacement`
+|string
+|Replacement string
+|===
+
+==== Playbook Configuration
+
+[source,yaml]
+----
+- require: '@baiyibai-antora/extensions/external-asset-downloader'
+  assetDownloader:
+    enabled: true
+    quiet: false
+    attribute_prefix: 'image'
+    target_dir: 'modules/ROOT/images'
+    overwrite: 'never'
+    concurrency: 5
+    directory_listing: true
+    url_replace:
+      - pattern: '/artifactory/'
+        replacement: '/artifactory/api/storage/'
+----
+
+[[vale-integration]]
+=== vale-integration
+
+Integrates Vale linting into the Antora build pipeline.
+
+==== Configuration
+
+[cols="2,1,3,2"]
+|===
+|Key |Type |Description |Default
+
+|`enabled`
+|boolean
+|Enable/disable the extension
+|`true`
+
+|`quiet`
+|boolean
+|Suppress informational output
+|`true`
+
+|`output_dir`
+|string
+|Directory for Vale log files
+|`'vale-output'`
+
+|`config_file`
+|string
+|Path to Vale configuration file
+|`'./.vale.ini'`
+
+|`ignore_files`
+|array
+|Patterns for files to ignore
+|`[]`
+
+|`toolchain_config_path`
+|string
+|Path to toolchain config with additional ignores
+|`'./toolchain-config.ini'`
+
+|`max_logs`
+|number
+|Maximum number of log files to keep
+|`10`
+
+|`list_limit`
+|number
+|Maximum files to list in verbose output
+|`20`
+|===
+
+==== Playbook Configuration
+
+[source,yaml]
+----
+- require: '@baiyibai-antora/extensions/vale-integration'
+  vale:
+    enabled: true
+    quiet: false
+    output_dir: 'vale-output'
+    config_file: './vale-rules/.vale.ini'
+    ignore_files:
+      - 'partials/generated'
+    toolchain_config_path: './toolchain-config.ini'
+    max_logs: 10
+----
+
+[[asciidoctorconfig]]
+=== asciidoctorconfig
+
+Copies `.asciidoctorconfig.adoc` and `.asciidoctorconfig` files from content catalog to project root.
+
+==== Configuration
+
+[cols="2,1,3,2"]
+|===
+|Key |Type |Description |Default
+
+|`enabled`
+|boolean
+|Enable/disable the extension
+|`true`
+
+|`quiet`
+|boolean
+|Suppress informational output
+|`true`
+
+|`version`
+|string
+|Version prefix for resource ID (e.g., `'1.0'`)
+|`''`
+
+|`component`
+|string
+|Component containing config files
+|`'asciidoctorconfig'`
+
+|`module`
+|string
+|Module containing config files
+|`'ROOT'`
+
+|`location`
+|string
+|Location family for config files
+|`'partial$'`
+
+|`asciidoctorconfig_adoc_filename`
+|string
+|Source filename for `.asciidoctorconfig.adoc`
+|_(disabled)_
+
+|`asciidoctorconfig_filename`
+|string
+|Source filename for `.asciidoctorconfig`
+|_(disabled)_
+|===
+
+==== Playbook Configuration
+
+[source,yaml]
+----
+- require: '@baiyibai-antora/extensions/asciidoctorconfig'
+  asciidoctorconfig:
+    enabled: true
+    quiet: false
+    component: 'asciidoctorconfig'
+    module: 'ROOT'
+    location: 'partial$'
+    asciidoctorconfig_adoc_filename: 'asciidoctorconfig.adoc'
+    asciidoctorconfig_filename: 'asciidoctorconfig'
+----
+
+== Vendorization
+
+To vendorize extensions into your project:
+
+[source,bash]
+----
+# Copy the dist folder to your project
+cp -r node_modules/@baiyibai-antora/extensions/dist ./lib/docs-extensions
+
+# Update your playbook to use local paths
+----
+
+[source,yaml]
+----
+antora:
+  extensions:
+    - require: './lib/docs-extensions/collector-writer'
+      collectorWriter:
+        enabled: true
+----
+
+== Development
+
+=== Building
+
+[source,bash]
+----
+npm install
+npm run build
+----
+
+=== Project Structure
+
+[source]
+----
+baiyibai-extensions/
+├── package.json
+├── tsconfig.json
+├── README.adoc
+├── src/
+│   └── extensions/
+│       ├── collector-writer/
+│       ├── assembler-ruby-preflight/
+│       ├── assembler-rename-pdf/
+│       ├── external-asset-downloader/
+│       ├── vale-integration/
+│       └── asciidoctorconfig/
+└── dist/                      # Built output
+----
+
+== License
+
+MIT

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

@@ -0,0 +1,71 @@
+/**
+ * @baiyibai-antora/docs-extensions - asciidoctorconfig
+ *
+ * Copies .asciidoctorconfig.adoc and .asciidoctorconfig files from the content
+ * catalog to the project root for AsciiDoctor tooling.
+ *
+ * Configuration in antora-playbook.yml:
+ *
+ * antora:
+ *   extensions:
+ *     - require: '@baiyibai-antora/docs-extensions/asciidoc-extensions/asciidoctorconfig'
+ *       asciidoctorconfig:
+ *         enabled: true
+ *         quiet: false
+ *         version: ''
+ *         component: 'asciidoctorconfig'
+ *         module: 'ROOT'
+ *         location: 'partial$'
+ *         asciidoctorconfig_adoc_filename: 'asciidoctorconfig.adoc'
+ *         asciidoctorconfig_filename: 'asciidoctorconfig'
+ */
+interface AsciidoctorconfigConfig {
+    enabled: boolean;
+    quiet: boolean;
+    version: string;
+    component: string;
+    module: string;
+    location: string;
+    asciidoctorconfig_adoc_filename: string | undefined;
+    asciidoctorconfig_filename: string | undefined;
+}
+interface AntoraLogger {
+    debug?: (msg: string) => void;
+    info?: (msg: string) => void;
+    warn?: (msg: string) => void;
+    error?: (msg: string) => void;
+}
+interface ExtensionEntry {
+    require?: string;
+    asciidoctorconfig?: Partial<AsciidoctorconfigConfig>;
+}
+interface Playbook {
+    dir?: string;
+    antora?: {
+        extensions?: ExtensionEntry[];
+    };
+}
+interface VirtualFile {
+    src?: {
+        component?: string;
+        module?: string;
+        family?: string;
+        relative?: string;
+        basename?: string;
+    };
+    contents: Buffer | Uint8Array;
+}
+interface ContentCatalog {
+    getFiles: () => VirtualFile[];
+    resolveResource: (resourceId: string, context?: unknown) => VirtualFile | undefined;
+}
+interface Registry {
+    getLogger?: (name: string) => AntoraLogger;
+    once: (event: string, callback: (context: {
+        playbook: Playbook;
+        contentCatalog?: ContentCatalog;
+    }) => Promise<void>) => void;
+}
+export declare function register(context: Registry): void;
+export {};
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/extensions/asciidoctorconfig/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAKH,UAAU,uBAAuB;IAC/B,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,OAAO,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,+BAA+B,EAAE,MAAM,GAAG,SAAS,CAAC;IACpD,0BAA0B,EAAE,MAAM,GAAG,SAAS,CAAC;CAChD;AAUD,UAAU,YAAY;IACpB,KAAK,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAC9B,IAAI,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAC7B,IAAI,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAC7B,KAAK,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;CAC/B;AAED,UAAU,cAAc;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,iBAAiB,CAAC,EAAE,OAAO,CAAC,uBAAuB,CAAC,CAAC;CACtD;AAED,UAAU,QAAQ;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE;QACP,UAAU,CAAC,EAAE,cAAc,EAAE,CAAC;KAC/B,CAAC;CACH;AAED,UAAU,WAAW;IACnB,GAAG,CAAC,EAAE;QACJ,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;KACnB,CAAC;IACF,QAAQ,EAAE,MAAM,GAAG,UAAU,CAAC;CAC/B;AAED,UAAU,cAAc;IACtB,QAAQ,EAAE,MAAM,WAAW,EAAE,CAAC;IAC9B,eAAe,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,KAAK,WAAW,GAAG,SAAS,CAAC;CACrF;AAED,UAAU,QAAQ;IAChB,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,YAAY,CAAC;IAC3C,IAAI,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,OAAO,EAAE;QAAE,QAAQ,EAAE,QAAQ,CAAC;QAAC,cAAc,CAAC,EAAE,cAAc,CAAA;KAAE,KAAK,OAAO,CAAC,IAAI,CAAC,KAAK,IAAI,CAAC;CAC9H;AAoID,wBAAgB,QAAQ,CAAC,OAAO,EAAE,QAAQ,GAAG,IAAI,CA8DhD"}