SPA support

Add optional single-page-application navigation support to the page with LFP SPA (repository).

A signifcant advantage of LFP Docs is the fact that the entire documentation is written to disk by default, every documentation page is its own, self-contained HTML page. This offers benefits to employ a documentation locally, save individual pages, or further process them otherwise.

A drawback is that when readers navigate your documentation online, each navigation is a full page reload; and while linked resources (such as scripts and styles) are most likely cached on the client, a full page reload means that everything the reader sees on their screen has to be redrawn, after the entire HTML was loaded and parsed.

LFP SPA provides a simple and straightforward implementation for same-page navigation fo static sites, based on the newly available Navigation API. A slim layer waying in at less than 2 kB minified and gzipped is responsible for managing navigating a static site without full page reloads.

Adding LFP SPA to LFP Docs

LFP SPA very much works exactly the same as LFP Docs by plugging into Eleventy via addPlugin():

import lfpSpaPlugin from '@lowfat/eleventy-plugin-lfp-spa';
import lfpDocsPlugin, { lfpSpaConfig } from '@lowfat/eleventy-plugin-lfp-docs';

export default function (eleventyConfig) {
  // order does not matter
  eleventyConfig.addPlugin(lfpDocsPlugin, {
    scripts: ['spa.js', /* your scripts to include */],
    // your LFP Docs configuration
  });
  eleventyConfig.addPlugin(lfpSpaPlugin, {
    ...lfpSpaConfig,
    // additional SPA configuration
  });

  // additional configuration

  return {
    // your output settings
  };
}

By adding ['spa.js'] (you can add other scripts in this array as well) to scripts, the client-side script generated by LFP SPA will get added to LFP Docs's HTML output. lfpSpaConfig is a configuration preset that sets up LFP Docs with LFP SPA. It looks something like this:

export const lfpSpaConfig = {
  portals: [
    'data-spa-head',
    'data-spa-title',
    'data-spa-site-menu',
    'data-spa-main'
  ],
};

This sets up all active regions for the default LFP Docs theme to be hydrated on same-site navigations; this also means that you should not overwrite portals with your own values (consider using something like mergeDeep from @lowfat/utils or Lodash's cloneDeep).

You're all set and ready to go. LFP SPA now takes care of fetching new resources and even introduces advanced caching for pages the reader shows interest in.

Head over to the repository or package site for more information on LFP SPA, and you can use it with other Eleventy sites as well.