html-compiler

Plain HTML with inlcudes support. Say what?

Indeed!

html-compiler compiles your HTML adding includes support using special string(s) you add to your HTML.

NOTE: The destination folder, dist by default, is cleaned out with every build. Also, your static assets(images, css, js) are not copied accross by this utility. Because, do one thing and do it well.

For a simple file system command utility in Nodejs, take a look at fs-extra-cli

Tell me more

Inside your HTML document, add the following string where you want to include a file:

#html-include=folder/index.html

The path specified should be relative to the root of your project folder. When you run html-compiler, it will replace the above string with the contents of the file you specified, and write the processed contents to a folder called dist by default.

When including assets, these need to be linked absolutely to avoid problems with nested files and folders when serving your site. html-compiler takes the grunt work out of this with the #html-include-asset string. For exmaple:

<link rel="stylesheet" href="#html-include-asset=/css/libs/prism.css" media="screen" />

When using common incldues such as a navigation menu, one rus into the same problem as with assets, where relative linking will cause the navigation to not function on any nested pages. To remedy this, html-compiler includes the #html-include-link directive. For example:

<li><a href="#html-include-link=/style/color/">Color</a></li>

As with assets, this will cause the above string to be processed prepending the site root to the specified URL.

Have a look at the styleguide folder in this repo for example usage, and see the documentation below for more on the options available.

Install

npm install html-compiler

Usage

From the command line call html-compiler specifying the folder containing the HTML files.

html-compiler --rootFolder=foldername --siteRoot=http://localhost:8000/dist

The preserveRoot option [added in v0.0.4]

Currently, when writing your files to the destination directory, the original root folder is preserved. This is not always desirable. html-compiler now includes a preserveRoot command line parameter to control this behaviour.

If you want to write the contents of your root folder directly to the destination directory, without preserving the root folder, run the command as before.

html-compiler --rootFolder=foldername

If however you wish to preserve the original root, call html-compiler as follows:

html-compiler --rootFolder=foldername ---preserveRoot

The siteRoot argument [added in v0.0.6]

Assets needs to be linked absolutely from the site root, in order to facilitate this, html-compiler uses the string #html-include-asset, for example:

In your HTML

<link rel="stylesheet" href="#html-include-asset=/css/libs/prism.css" media="screen" />

Now call the utility as follows:

html-compiler --rootFolder=styleguide --siteRoot=http://localhost:8000/dist

The dest argument [added in v0.0.8]

Allows you to specify the output directory for processed files. Defaults to dist

html-compiler --rootFolder=styleguide --dest=public --siteRoot=http://localhost:8000/dist