Skip to main content

Resolve page URLs

Option: router

type Router =
  | boolean
  | {
      enabled?: boolean;
      test?: RegExp | Array<RegExp>;
      rewriteIndex?: false | string;
      resolve?: (props: {
        sourceRoute: string;
        outputRoute: string;
        sourceFile: string;
        outputFile: string;
      }) => void | string;
    };
  • enabled - Enable / disable the route resolving. Defaults true.
  • test - The router resolves values matching to the RegExp only.
    Defaults, defined the same as plugin.test option to match templates of used preprocessor.
  • rewriteIndex - Rewrite the index.html.
  • If publicPath is auto, replaces index.html with the specified string, should be on of: '.', '' (empty).
  • If publicPath is not empty, replaces index.html with '' (empty) regardless of specified value.
  • If the route URL contains a query or a segment (e.g. index.html#contact), the rewriteIndex is ignored.
  • resolve() - Allow modify the resolved route URL.
    The argument is the object:
  • sourceRoute - The resolved attribute value (absolute path).
  • outputRoute - The output URL regards publicPath, e.g. by auto publicPath is relative to outputFile.
  • sourceFile - The absolute path to the template file where is resolved the sourceRoute.
  • outputFile - The output HTML filename of sourceFile, relative to the dist/ directory.
    Return:
  • void - Do nothing.
  • string - The returned string replaces the value.

The router option enable resolving of a.href (by defaults) values as a route URL to inner pages. This is useful for multi-page sites.

Using the sources option you can specify any tag attribute which should be resolved.

note

The router resolves routes specified in the entry plugin option only. An external URL will be ignored.

const HtmlBundlerPlugin = require('html-bundler-webpack-plugin');
module.exports = {
  resolve: {
    alias: {
      // recommended to use the alias for the route in templates
      '@views': path.join(__dirname, 'src/views/pages'),
    },
  },
  plugins: [
    new HtmlBundlerPlugin({
      entry: {
        // multi-pages
        index: './src/views/pages/home/index.html',
        'news/sport/index': './src/views/pages/news/sport/index.html',
      },
      router: true, // enable resolving of route URLs in a.href
    }),
  ],
};

In templates, specify the source path to the linked template. The linked template must be specified in the entry plugin option too.

The source ./src/views/pages/index.html

<html>
<body>
  <h1>Home</h1>
  <a href="@views/home/index.html">Home</a> | <a href="@views/news/sport/index.html">Sport</a>
</body>
</html>

The source ./src/views/pages/news/sport/index.html

<html>
<body>
  <h1>Sports News</h1>
  <a href="@views/home/index.html">Home</a> | <a href="@views/news/sport/index.html">Sport</a>
</body>
</html>
tip

If you use a template, you can include navigation as a partial on all pages, since the route URLs will be automatically resolved from their source files.

The generated dist/index.html

<html>
<body>
  <h1>Home</h1>
  <a href="index.html">Home</a> | <a href="news/sport/index.html">Sport</a>
</body>
</html>

The generated dist/news/sport/index.html

<html>
<body>
  <h1>Sports News</h1>
  <a href="../../index.html">Home</a> | <a href="index.html">Sport</a>
</body>
</html>
tip

You can use the router.rewriteIndex option to rewrite the index.html.