Style Guide Boilerplate v4 turns a folder of HTML and Markdown into a Vite-built style guide

The plugin generates the page, so there is no index.html

The v4 release changed what this project is. It is now a Vite plugin that reads a folder of HTML examples and Markdown docs and serves them as a browsable guide, using your project's real stylesheets rather than a bundled theme. In development you edit a file, save, and the guide updates. `vite build` produces a static site you can host anywhere.

One consequence is stated plainly in the README: there is no index.html to maintain, because the plugin generates the page. That is a real difference from the older PHP-oriented generator, where an index file was part of the project.

Requirements are Node 22 or newer and Vite 8. The published package is @bjankord/style-guide-boilerplate at version 4.0.0-rc.0, a release candidate, tagged on 2026-10-11, the same day as the last push to the repository. The previous release was v3.3.2 from 2018, so this is a rewrite separated by eight years rather than an incremental bump. The package is ESM only, with exports for the plugin itself and for jsx-runtime and jsx-dev-runtime.

The config object is short and every key changes something visible

Installation is a dev dependency, and the plugin takes one options object.

npm install --save-dev vite @bjankord/style-guide-boilerplate

import { defineConfig } from 'vite'
import styleGuide from '@bjankord/style-guide-boilerplate'

export default defineConfig({
  plugins: [
    styleGuide({
      styles: ['./src/styles/main.css'],
      title: 'My Style Guide',
    }),
  ],
})

The `content` option defaults to './style-guide' and is relative to the Vite root. `styles` defaults to an empty array, and local paths go through Vite, which means Sass, PostCSS and hot reload all work; URLs beginning with https:// or // are linked as-is, which suits PHP and Rails projects whose asset pipeline lives elsewhere. `scripts` behaves the same way and loads once on the page.

`title` defaults to 'Style Guide'. `path` defaults to '/' and controls where the guide is served under Vite's base, so setting '/style-guide/' mounts it inside an existing app. `build` defaults to true, and setting it to false leaves the guide out of production builds entirely, which is the setting you want if the guide is a development artifact. `nav` defaults to `{ depth: 3 }`, which controls how far the sidebar descends: depth 1 lists sections, 2 adds their patterns, and 3 adds variants of patterns that have more than one.

Three directory levels decide what the sidebar shows

The content folder has a fixed shape. Each top-level folder is a section, each folder inside a section is a pattern, and each example file or folder inside a pattern is a variant. Ordering comes from a numeric prefix, and the prefix is stripped from the title.

style-guide/
├── 01-getting-started/
│   └── index.md
├── 04-base/
│   ├── headings/
│   │   ├── 01-sizes/
│   │   │   ├── index.md
│   │   │   └── sizes.html
│   │   └── 02-with-links.html
│   └── lists/
│       └── lists.html
└── 05-components/
    └── buttons/
        ├── index.md
        └── buttons.html

A pattern with one variant shows it directly; with several, each variant gets its own heading. Files and folders can sit side by side in a pattern and sort together, which makes it easy to mix one standalone example with numbered variant folders.

Docs are sibling files rather than a special location. `02-with-links.md` documents `02-with-links.html`, and inside a variant folder the doc describes the html file in the same folder. `index.md` or `index.mdx` documents the section or pattern it lives in. Front matter overrides the derived title and order:

---
title: Button styles
order: 1
---
Use `.button` for actions.

Titles otherwise come from file and folder names, so form-buttons.html becomes "Form buttons".

Malformed content is skipped with a warning instead of failing the build

The failure modes are documented and they are soft. A variant folder containing more than one .html file or more than one doc, or containing nested folders, is skipped with a warning. An .html, .md or .mdx file sitting directly in a section folder (other than its index doc), or directly in the content root, is skipped with a warning that suggests where it should be moved.

The second rule catches a genuine authoring mistake: examples always belong in a pattern folder, even a pattern that holds only one file, like `06-base/lists/lists.html`. Someone who drops lists.html straight into 06-base gets a warning rather than a page that quietly never appears.

The soft behaviour is a deliberate trade and it cuts both ways. A documentation site will still build when half the content is misplaced, which is convenient during authoring and inconvenient when you expected a broken layout to be impossible. If you want misplaced content to fail loudly, you need a check of your own; the plugin does not provide one.

Each .html example is rendered, then shown again as source in a View source panel with a Copy button. A doc with no example beside it is still displayed on its own, and Markdown can include raw HTML.

MDX renders at build time, so tokens come from your own files

Any doc can be an .mdx file instead of .md, and that is the mechanism for documenting design tokens from the files that already define them. MDX is Markdown that can import data and use JSX, and imports resolve through Vite, so JSON files, aliases and your own components work.

---
title: Spacing
---
import spacing from '../../src/tokens/spacing.json'

Use the spacing scale for margins and gaps.

<ul class="spacing-scale">
  {Object.entries(spacing).map(([name, value]) => (
    <li>
      <span class="spacing-bar" style={`width: ${value}`} />
      <code>{name}</code> {value}
    </li>
  ))}
</ul>

Two properties make this safe to publish. MDX docs render to static HTML at build time, so no JavaScript from a doc reaches the browser. And editing an imported file reloads the page, which means a token change in your source JSON shows up in the guide without touching the guide.

The JSX dialect is deliberately HTML-flavoured: class and for work, as do className and htmlFor, and style accepts a string or an object. Text and attribute values are escaped.

What the guide does not do is draw the swatches for you. There are no shipped components or styles for color swatches, type samples or spacing scales. Your MDX writes the markup and your project's stylesheets style it, and to reuse markup across pages you write your own component and import it.

Where this is the wrong choice

The README itself points at the alternative: if you want a full component workbench, use Storybook. The difference in approach is concrete. Storybook renders components in isolation through a component contract, with stories, args, addons and a test runner. This plugin does not know about components at all; it renders HTML files and Markdown docs through your CSS. If your system is built as components and you need interaction states, prop tables and visual regression, Storybook answers that and this does not.

The v3 migration is the other boundary. The README states that v3 (PHP) is end of life, with the final version tagged v3-final and a migration section in the README. Projects on PHP, or on Node older than 22, have no forward path in v4 and should stay on that tag.

Licensing is the third thing to check before adopting. The LICENSE file is a custom licence that GitHub cannot classify, and the repository ships LICENSE.txt rather than a standard identifier, so read it yourself before putting this in a commercial product. The last push to the repository was on 2026-10-11, and the current version is a release candidate, so pin the exact tag you test against rather than tracking latest.

Editorial conclusion

Adopt v4 if your design system documentation should be generated from the same CSS the product uses, and you are already on Node 22 with Vite 8. Stay on the v3-final branch if you are on PHP or an older Node. Before upgrading, read the migration notes in the README, since v3 is end of life and the input format and build command both changed.

Frequently asked questions

Official sources

1. bjankord/style-guide-boilerplate on GitHub
2. Issues
3. Project website
4. README
5. Releases