rollup-plugin-posthtml-multi

This plugin allows you to seamlessly integrate posthtml post-processor in rollup build environment.

It allows importing html files as strings, extracting imported html files to output directory (custom paths also supported), watching modules imported from html (when using posthtml-extend, posthtml-include or posthtml-modules).

You can also pass array of configs, with their own include and exclude patterns, generating as many variations of templates as needed. This can be particullary useful e.g. when generating a static website from markdown sources.

If you find this plugin useful do not hesitate to click that star!

Install

npm i -D rollup-plugin-posthtml-multi

Usage

Basic

index.html

1<p>Hello, World!</p>

index.js

1export { default as hello } from './index.html';

rollup.config.js

1import posthtml from 'rollup-plugin-posthtml-multi';
2
3module.exports = {
4	input: 'index.js',
5	output: {
6		dir: 'dist',
7		format: 'iife',
8	},
9	plugins: [posthtml()],
10};

will produce a bundle with following content:

1var hello = '<p>Hello, World!</p>\n'

If you specify extract: true in rollup.config.js like

1/* ... */
2plugins: [posthtml({ options: { extract: true } })],
3/* ... */

the hello variable will be an empty string and index.html file will be written to output directory (dist/ in this case).

extract can also be a path. If it contains an extension it's considered a filename, else it will be used as output directory. It can be an absolute path, otherwise it will be resolved relative to rollup's output directory.

Advanced

src/modules/module.html

1<h1>This is a Title!</h1>

src/index.html

1<module href='./modules/module.html'></module>
2<p>I am a lonely paragraph...</p>

index.js

1export { default as template } from './index.html'

rollup.config.js

1import posthtml from 'rollup-plugin-posthtml-multi';
2import modules from 'posthtml-modules';
3/* ... */
4plugins: [posthtml({
5	watch: true,
6	// usually not necessary, but if watching fails you should specify module path here
7	importPath: 'src/modules/',
8	options: {
9		exclude: '**/modules/*',
10		plugins: [modules({ from: 'src/index.html' })],
11	},
12})],

Now if you start rollup in watch mode (--watch), any edits to index.html, as well as module.html will be picked up by rollup and trigger rebuild.

And beyond...

Now you might wonder why options is an object. That's because it can also be an array of objects with their own includes, excludes, plugins, parsers and so on.

Imagine you have a bunch of markdown files. Their content is irrelevant to this example. Now you have a single html template and you need to generate a page for every markdown file.

This is easy with the help of some extra modules.

template.html

1<!--...-->
2<main markdown>{{ content }}</main>
3<!--...-->

We don't necessarily need any javascript here.

rollup.config.js

1import posthtml from 'rollup-plugin-posthtml-multi';
2
3import fs from 'fs';
4import path from 'path';
5import fastGlob from 'fast-glob';
6import expressions from 'posthtml-expressions';
7import markdown from 'posthtml-markdown';
8
9// no point in using async here
10const configureTemplates = () => fastGlob.sync('markdown/*.md').map((md) => ({
11	// name resulting files after source markdown
12	extract: `${path.basename(md, path.extname(md))}.html`,
13	plugins: [
14		expressions({ locals: { content: fs.readFileSync(md).toString() } }),
15		markdown(),
16	],
17}));
18
19module.exports = {
20	// yes, you can do this
21	input: 'template.html',
22	output: {
23		dir: 'dist/',
24		format: 'iife',
25		// since we're using html as input no bundle will be written
26		// but rollup still complains about missing name with iife
27		name: 'bundle',
28	},
29	plugins: [
30		posthtml({ options: configureTemplates() }),
31	],
32};

For more examples check the tests. If you have an interesting use case in mind, open an issue we'll add it here.

Options

• watch: (boolean; default: false): If true watch files imported by posthtml plugins.
• importPath: (string; default: undefined): Path to search for files imported by posthtml plugins.
• options: (Object | [Object ...]; default: {}): An (array of) object(s) specifying options and plugins.
  • options.include: (string; default: '**/*.html'): A glob matching files to process according to this config.
  • options.exclude: (string; default: undefined): A glob matching files to skip for this config.
  • options.extract: (boolean | string; default: undefined): Whether to extract html to files. Can be a file name or relative/absolute path (determined by presence of extension). If non-falsy, javascript variables contain empty strings.
  • options.plugins: (Array; default: []): An array of plugins to pass to posthtml.
  • options.parser: (Function; default: undefined): Passed directly to posthtml.
  • options.directives: (Array; default: undefined): Passed directly to posthtml.