Skip to content

Latest commit

 

History

History
297 lines (208 loc) · 6.82 KB

README.md

File metadata and controls

297 lines (208 loc) · 6.82 KB
Raw

html-insert-assets

Overview

Insert assets such as scripts, stylesheets and shortcut icons into HTML.

Supports stamping of asset URLs, preloading assets and more fine grained options for specific asset types.

CLI

Required

    --html <file>
        the HTML template to insert assets into

    --out <file>
        the output HTML file path

Scripts

    --scripts [--async] [--module] [--nomodule] [--attr name=value] <scripts>...

Add <script src="..."> elements to the end of the <body> for each script.

Options:

    --async
        adds the 'async' attribute

    --module
        marks the scripts as es2015 modules using the 'type="module"' attribute

    --nomodule
        marks the scripts as non-es2015 using the 'nomodule' attribute

    --attr name=value
        add custom attributes, can specify multiple name=value pairs

By default the script will only include the src attribute. If neither --module or --nomodule are present defaults are determined based on file extension or naming conventions:

  • --module is assumed on a per-file basis if the file extension is .mjs or .es2015.js
  • --nomodule is assumed on a per-file basis if a matching es2015 module file is present

See:

Stylesheets

    --stylesheets [--media value] <stylesheets>...

Add <link rel="styleshsheet" href="..."> to the <head> for each stylesheet.

Options:

    --media value
        add the media query attribute

See:

Favicon Images

    --favicons [--rel value] [--sizes value] [--type value] <images>...

Add <link rel="icon" type="..." href="..."> to the <head> for eached image.

Options:

    --rel value
        add the specified 'rel' attribute value, defaults to '"icon"'

    --sizes value
        add the specified 'size' attribute value

    --type value
        add the specified 'type' attribute value

By default rel="icon" is added and the type attribute is determined per-file based on file extension.

See:

Generic Assets

    --assets <assets>...

Attempts to automatically determine asset types based on file extension and inserts such assets with the default configurations listed above.

  • *.{js,mjs} for scripts
  • *.css for stylesheets
  • *.ico for favicons

Preloading

    --preload <assets>...

Add <link rel="preload" href="..." as="..."> for each asset, determining the as attributed based on file extension.

Allows preloading assets that your page will need very soon, which you want to start loading early in the page lifecycle.

Stamping

Adds paramaters to inserted URLs to create versioned URLs, allowing long cache times while busting the cache when resources change.

Examples

Basic

Functionality shared across asset types, using --scripts for these examples.

Basic relative paths:

    html-insert-assets
        --html ./index.tmpl.html
        --out ./index.html
        --scripts ./a.js b.js sub/c.js

will insert:

    <script src="./a.js"></script>
    <script src="./b.js"></script>
    <script src="./sub/c.js"></script>

If the --out file is in a separate directory, URLs are relative to that directory

    html-insert-assets
        --html ./index.tmpl.html
        --out ./sub/index.html
        --scripts ./a.js b.js sub/c.js

will insert:

    <script src="../a.js"></script>
    <script src="../b.js"></script>
    <script src="./c.js"></script>

Root asset directories to trim and convert to URLs relative to the the --out directory

    html-insert-assets
        --html ./index.tmpl.html
        --out ./index.html
        --roots .
        --scripts ./a.js b.js sub/c.js

will insert:

    <script src="./a.js"></script>
    <script src="./b.js"></script>
    <script src="./sub/c.js"></script>

Root directories of assets (multiple):

    html-insert-assets
        --html ./index.tmpl.html
        --out ./index.html
        --roots sub /abs/path
        --scripts /abs/path/a.js b.js sub/c.js

will insert:

    <script src="./a.js"></script>
    <script src="./b.js"></script>
    <script src="./c.js"></script>

Root directories of assets (multiple + alternate --out):

    html-insert-assets
        --html ./index.tmpl.html
        --out ./out/index.html
        --roots sub /abs/path
        --scripts /abs/path/a.js b.js sub/c.js

will insert:

    <script src="./a.js"></script>
    <script src="../b.js"></script>
    <script src="./c.js"></script>

Absolute paths outside any root directories:

    html-insert-assets
        --html ./index.tmpl.html
        --out sub/index.html
        --roots sub /abs/path
        --scripts /path/to/my.js

will insert:

    <script src="/path/to/my.js"></script>

Assets

Scripts, auto detecting type="module" vs nomodule

    html-insert-assets
        --html ... --out ...
        --scripts foo.mjs foo.js

Scripts, manually specifying type="module" vs nomodule

    html-insert-assets
        --html ... --out ...
        --scripts --module app.mjs
        --scripts --nomodule app-legacy.js

Multiple favicons:

    html-insert-assets
        --html ... --out ...
        --favicon --sizes=16x16 default.ico
        --favicon --sizes=128x128 large.png

Stylesheets:

    html-insert-assets
        --html ... --out ...
        --stylesheets main.css
        --stylesheets --media=print print-only.css

Preloading Examples

Preloading some .js and .jpg files.

    html-insert-assets
        --html ./index.tmpl.html
        --out ./index.html
        --preload load-later.js large-image.jpg

will insert:

    <link rel="preload" href="./load-later.js" as="script">
    <link rel="preload" href="./large-image.jpg" as="image">

Notes

Originally forked from rules_nodejs.