feat: Implement htmlProcessor as the documentProcessor for HTML

.changeset/new-crews-appear.md

@@ -0,0 +1,5 @@
+---
+'@vivliostyle/cli': minor
+---
+
+Implement htmlProcessor/xhtmlProcessor for HTML document transformation

docs/api-javascript.md

@@ -14,11 +14,13 @@
 
 ### Interfaces
 
+- [`HtmlOptions`](#htmloptions)
 - [`StringifyMarkdownOptions`](#stringifymarkdownoptions)
 - [`TemplateVariable`](#templatevariable)
 
 ### Type Aliases
 
+- [`HtmlProcessorFactory`](#htmlprocessorfactory)
 - [`Metadata`](#metadata)
 - [`StructuredDocument`](#structureddocument)
 - [`StructuredDocumentSection`](#structureddocumentsection)
@@ -28,6 +30,8 @@
 
 ### Variables
 
+- [`defaultHtmlProcessor`](#defaulthtmlprocessor)
+- [`defaultXhtmlProcessor`](#defaultxhtmlprocessor)
 - [`readMetadata`](#readmetadata)
 
 ## Functions
@@ -140,7 +144,7 @@ build({
 
 ###### logLevel?
 
-`"info"` \| `"silent"` \| `"verbose"` \| `"debug"` = `...`
+`"verbose"` \| `"info"` \| `"silent"` \| `"debug"` = `...`
 
 ###### openViewer?
 
@@ -372,7 +376,7 @@ Scaffold a new Vivliostyle project.
 
 ###### logLevel?
 
-`"info"` \| `"silent"` \| `"verbose"` \| `"debug"` = `...`
+`"verbose"` \| `"info"` \| `"silent"` \| `"debug"` = `...`
 
 ###### openViewer?
 
@@ -602,7 +606,7 @@ Scaffold a new Vivliostyle project.
 
 ###### logLevel?
 
-`"info"` \| `"silent"` \| `"verbose"` \| `"debug"` = `...`
+`"verbose"` \| `"info"` \| `"silent"` \| `"debug"` = `...`
 
 ###### openViewer?
 
@@ -852,7 +856,7 @@ Open a browser for previewing the publication.
 
 ###### logLevel?
 
-`"info"` \| `"silent"` \| `"verbose"` \| `"debug"` = `...`
+`"verbose"` \| `"info"` \| `"silent"` \| `"debug"` = `...`
 
 ###### openViewer?
 
@@ -1010,6 +1014,19 @@ Unified processor.
 
 ## Interfaces
 
+### HtmlOptions
+
+#### Properties
+
+| Property | Type |
+| ------ | ------ |
+| <a id="contenttype"></a> `contentType?` | `"text/html"` \| `"application/xhtml+xml"` |
+| <a id="language"></a> `language?` | `string` |
+| <a id="style"></a> `style?` | `string`[] |
+| <a id="title"></a> `title?` | `string` |
+
+***
+
 ### StringifyMarkdownOptions
 
 Option for convert Markdown to a stringify (HTML).
@@ -1022,12 +1039,12 @@ Option for convert Markdown to a stringify (HTML).
 | <a id="disableformathtml"></a> `disableFormatHtml?` | `boolean` | Disable automatic HTML format. |
 | <a id="hardlinebreaks"></a> `hardLineBreaks?` | `boolean` | Add `<br>` at the position of hard line breaks, without needing spaces. |
 | <a id="imgfigcaptionorder"></a> `imgFigcaptionOrder?` | `"img-figcaption"` \| `"figcaption-img"` | Order of img and figcaption elements in figure. |
-| <a id="language"></a> `language?` | `string` | Document language (ignored in partial mode). |
+| <a id="language-1"></a> `language?` | `string` | Document language (ignored in partial mode). |
 | <a id="math"></a> `math?` | `boolean` | Enable math syntax. |
 | <a id="partial"></a> `partial?` | `boolean` | Output markdown fragments. |
 | <a id="replace"></a> `replace?` | `ReplaceRule`[] | Replacement handler for HTML string. |
-| <a id="style"></a> `style?` | `string` \| `string`[] | Custom stylesheet path/URL. |
-| <a id="title"></a> `title?` | `string` | Document title (ignored in partial mode). |
+| <a id="style-1"></a> `style?` | `string` \| `string`[] | Custom stylesheet path/URL. |
+| <a id="title-1"></a> `title?` | `string` | Document title (ignored in partial mode). |
 
 ***
 
@@ -1067,9 +1084,9 @@ Option for convert Markdown to a stringify (HTML).
 | `input.entry` | `string` |
 | `input.format` | `InputFormat` |
 | <a id="installdependencies"></a> `installDependencies?` | `boolean` |
-| <a id="language-1"></a> `language` | `string` |
+| <a id="language-2"></a> `language` | `string` |
 | <a id="logger"></a> `logger?` | `LoggerInterface` |
-| <a id="loglevel"></a> `logLevel?` | `"info"` \| `"silent"` \| `"verbose"` \| `"debug"` |
+| <a id="loglevel"></a> `logLevel?` | `"verbose"` \| `"info"` \| `"silent"` \| `"debug"` |
 | <a id="openviewer"></a> `openViewer?` | `boolean` |
 | <a id="output"></a> `output?` | `object` & `object` & `object`[] |
 | <a id="port"></a> `port?` | `number` |
@@ -1091,12 +1108,12 @@ Option for convert Markdown to a stringify (HTML).
 | <a id="stderr"></a> `stderr?` | `Writable` |
 | <a id="stdin"></a> `stdin?` | `Readable` |
 | <a id="stdout"></a> `stdout?` | `Writable` |
-| <a id="style-1"></a> `style?` | `string` |
+| <a id="style-2"></a> `style?` | `string` |
 | <a id="template"></a> `template?` | `string` |
 | <a id="theme"></a> `theme?` | `string` \| `object` & `object` \| (`string` \| `object` & `object`)[] |
 | <a id="themepackage"></a> `themePackage?` | `VivliostylePackageJson` |
 | <a id="timeout"></a> `timeout?` | `number` |
-| <a id="title-1"></a> `title` | `string` |
+| <a id="title-2"></a> `title` | `string` |
 | <a id="userstyle"></a> `userStyle?` | `string` |
 | <a id="viewer"></a> `viewer?` | `string` |
 | <a id="viewerparam"></a> `viewerParam?` | `string` |
@@ -1105,6 +1122,22 @@ Option for convert Markdown to a stringify (HTML).
 
 ## Type Aliases
 
+### HtmlProcessorFactory()
+
+> **HtmlProcessorFactory** = (`options`) => `unified.Processor`
+
+#### Parameters
+
+##### options
+
+[`HtmlOptions`](#htmloptions)
+
+#### Returns
+
+`unified.Processor`
+
+***
+
 ### Metadata
 
 > **Metadata** = `object`
@@ -1298,6 +1331,18 @@ https://github.com/vivliostyle/vivliostyle-cli/blob/main/docs/config.md
 
 ## Variables
 
+### defaultHtmlProcessor
+
+> `const` **defaultHtmlProcessor**: [`HtmlProcessorFactory`](#htmlprocessorfactory)
+
+***
+
+### defaultXhtmlProcessor
+
+> `const` **defaultXhtmlProcessor**: [`HtmlProcessorFactory`](#htmlprocessorfactory)
+
+***
+
 ### readMetadata()
 
 > `const` **readMetadata**: (`md`, `customKeys?`) => [`Metadata`](#metadata)

docs/config.md

@@ -99,6 +99,12 @@ type VivliostyleConfigSchema =
   - `documentMetadataReader`: (content: string) => import("@vivliostyle/vfm").Metadata  
     Custom function to extract metadata from the source document content.
 
+  - `htmlProcessor`: (options: HtmlOptions) => import("unified").Processor  
+    Custom function to provide a unified Processor for transforming HTML documents.
+
+  - `xhtmlProcessor`: (options: HtmlOptions) => import("unified").Processor  
+    Custom function to provide a unified Processor for transforming XHTML documents.
+
   - `vfm`: [VfmConfig](#vfmconfig)  
     Options for converting Markdown into a stringified format (HTML).
 
@@ -188,6 +194,12 @@ type BuildTask = {
   documentMetadataReader?: (
     content: string,
   ) => import("@vivliostyle/vfm").Metadata;
+  htmlProcessor?: (
+    options: HtmlOptions,
+  ) => import("unified").Processor;
+  xhtmlProcessor?: (
+    options: HtmlOptions,
+  ) => import("unified").Processor;
   vfm?: VfmConfig;
   image?: string;
   http?: boolean;
@@ -344,6 +356,12 @@ type CoverEntryConfig = {
   - `documentMetadataReader`: (content: string) => import("@vivliostyle/vfm").Metadata  
     Custom function to extract metadata from the source document content.
 
+  - `htmlProcessor`: (options: HtmlOptions) => import("unified").Processor  
+    Custom function to provide a unified Processor for transforming HTML documents.
+
+  - `xhtmlProcessor`: (options: HtmlOptions) => import("unified").Processor  
+    Custom function to provide a unified Processor for transforming XHTML documents.
+
 #### Type definition
 
 ```ts
@@ -364,6 +382,12 @@ type ArticleEntryConfig = {
   documentMetadataReader?: (
     content: string,
   ) => import("@vivliostyle/vfm").Metadata;
+  htmlProcessor?: (
+    options: HtmlOptions,
+  ) => import("unified").Processor;
+  xhtmlProcessor?: (
+    options: HtmlOptions,
+  ) => import("unified").Processor;
 };
 ```
 

examples/customize-processor/README.md

@@ -15,7 +15,7 @@ import rehypeStringify from 'rehype-stringify';
 import remarkRuby from 'remark-ruby';
 
 const config = {
-  title: 'Markdown processor customization example',
+  title: 'Processor customization example',
   entry: ['manuscript.md'],
   // config is StringifyMarkdownOptions in @vivliostyle/vfm
   // metadata is Metadata in @vivliostyle/vfm
@@ -41,12 +41,12 @@ export default config;
 You can also set `documentProcessor` and `documentMetadataReader` for individual entries. This allows different processing for each file:
 
 ```js
-import { defineConfig, VFM, readMetadata } from '@vivliostyle/cli';
+import { defineConfig, VFM } from '@vivliostyle/cli';
 import unified from 'unified';
 // ... other imports
 
 const config = defineConfig({
-  title: 'Markdown processor customization example',
+  title: 'Processor customization example',
   entry: [
     // Uses the global documentProcessor
     'manuscript.md',
@@ -55,8 +55,7 @@ const config = defineConfig({
       path: 'manuscript2.md',
       documentProcessor: VFM,
       documentMetadataReader: (content) => {
-        const match = content.match(/^#\s+(.+)$/m);
-        return { title: match ? match[1] : 'Untitled' };
+        return { title: 'Custom title' };
       },
     },
   ],
@@ -75,3 +74,44 @@ const config = defineConfig({
 
 export default config;
 ```
+
+## htmlProcessor and xhtmlProcessor
+
+While `documentProcessor` handles Markdown-to-HTML conversion, `htmlProcessor` and `xhtmlProcessor` allow you to customize the processing of HTML and XHTML source files respectively.
+
+You can extend the built-in `defaultHtmlProcessor` (or `defaultXhtmlProcessor` for XHTML) with additional [rehype](https://github.com/rehypejs/rehype) plugins:
+
+```js
+import { defineConfig, defaultHtmlProcessor } from '@vivliostyle/cli';
+import { visit } from 'unist-util-visit';
+
+const openLinksInNewTab = () => (tree) => {
+  visit(tree, 'element', (node) => {
+    if (
+      node.tagName === 'a' &&
+      String(node.properties?.href).startsWith('http')
+    ) {
+      (node.properties ??= {}).target = '_blank';
+      node.properties.rel = 'noopener noreferrer';
+      node.children.push({
+        type: 'element',
+        tagName: 'span',
+        properties: {},
+        children: [{ type: 'text', value: ' ↗' }],
+      });
+    }
+  });
+};
+
+const config = defineConfig({
+  entry: [
+    {
+      path: 'page.html',
+      htmlProcessor: (options) =>
+        defaultHtmlProcessor(options).use(openLinksInNewTab),
+    },
+  ],
+});
+
+export default config;
+```

examples/customize-processor/package.json

@@ -8,11 +8,12 @@
   },
   "dependencies": {
     "@vivliostyle/cli": "workspace:*",
-    "rehype-expressive-code": "^0.37.0",
+    "rehype-expressive-code": "0.41.6",
     "rehype-stringify": "^8.0.0",
     "remark-parse": "^9.0.0",
-    "remark-rehype": "^9.0.0",
+    "remark-rehype": "^8.1.0",
     "remark-ruby": "^0.4.0",
-    "unified": "^9.2.0"
+    "unified": "^9.2.0",
+    "unist-util-visit": "^4.1.0"
   }
 }

examples/customize-processor/page.html

@@ -0,0 +1,18 @@
+<!doctype html>
+<html>
+  <head>
+    <meta charset="utf-8" />
+    <title>HTML Processor Example</title>
+  </head>
+  <body>
+    <h1>HTML Processor Example</h1>
+    <p>
+      This page is processed with a custom
+      <a href="https://unifiedjs.com/">unified</a> processor. External links
+      like
+      <a href="https://vivliostyle.org/">Vivliostyle</a>
+      will have <code>target="_blank"</code> and an arrow indicator added
+      automatically.
+    </p>
+  </body>
+</html>