Docsify Breeze is a documentation toolkit, powered by Docsify, to enable joyful documentation of Web Components. The template incorporates a suite of custom Docsify plugins, plus a custom theme, that make documenting Web Components a breeze.
Docsify is a lightweight documentation site generator with no statically generated HTML files. All documentation is written in Markdown.
Breeze includes a custom theme for Docsify, plus a suite of custom plugins that enable robust documentation of Web Components. Features include resizable component previews with source code rendering, a zero-configuration customization UI editing a component's attributes and slots, and automatic documentation of the component API.
Unlike heavyweight tools such as Storybook, Breeze's documentation implementation is specifically tuned for documenting and developing Web Components. It boots instantly in development, integrates seamlessly with existing component build processes, and allows for high levels of customization.
Several of the Docsify plugins created for this project are also available à la carte for any Docsify installation:
- docsify-web-component-docs
- docsify-web-component-viewer
- docsify-theme-switcher
- docsify-github-edit-link
Docsify Breeze is for organizations looking to document a Web Component-based component library or design system.
If you're creating a new Docsify site from scratch, first install the Docsify CLI:
npm i docsify-cli -gThen initialize your new Docsify site:
docsify init ./docsTo setup Breeze, modify the index.html file to load its plugins, styles,
and default theming tokens:
<html>
<head>
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />
<meta name="viewport" content="width=device-width,initial-scale=1" />
<meta charset="UTF-8" />
<link
rel="stylesheet"
href="//cdn.jsdelivr.net/npm/docsify-breeze@1/dist/breeze/theme/breeze.min.css"
/>
<link
rel="stylesheet"
href="//cdn.jsdelivr.net/npm/docsify-breeze@1/dist/breeze/theme/tokens/breeze-tokens.min.css"
/>
</head>
<body>
<div id="app"></div>
<script>
window.$docsify = {
name: "",
repo: "",
};
</script>
<script src="//cdn.jsdelivr.net/npm/docsify@4"></script>
<script
src="//cdn.jsdelivr.net/npm/docsify-breeze@1/dist/breeze/index.min.js"
type="module"
></script>
<script src="//cdn.jsdelivr.net/npm/docsify-github-edit-link@1/dist/github-edit-link.min.js"></script>
<script src="//cdn.jsdelivr.net/npm/docsify-theme-switcher@1/dist/theme-switcher.min.js"></script>
<script
src="//cdn.jsdelivr.net/npm/docsify-web-component-docs@1/dist/web-component-docs.min.js"
defer
></script>
<script src="//cdn.jsdelivr.net/npm/docsify-web-component-viewer@1/dist/web-component-viewer.min.js"></script>
</body>
</html>For more documentation about Docsify itself, visit the Docsify site.
You can configure the site name, description, and logo that appears in the sidebar by adding the following to your Docsify configuration:
<script>
window.$docsify = {
// ... (your existing Docsify config)
siteTitle: {
primary: "My Site Title",
secondary: "My Site Description",
logo: '<svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke-width="1.5" stroke="currentColor"><path stroke-linecap="round" stroke-linejoin="round" d="M19.5 14.25v-2.625a3.375 3.375 0 00-3.375-3.375h-1.5A1.125 1.125 0 0113.5 7.125v-1.5a3.375 3.375 0 00-3.375-3.375H8.25m2.25 0H5.625c-.621 0-1.125.504-1.125 1.125v17.25c0 .621.504 1.125 1.125 1.125h12.75c.621 0 1.125-.504 1.125-1.125V11.25a9 9 0 00-9-9z" /></svg>',
logoFill: "#ff6842",
},
};
</script>This includes the following options:
- siteTitle.primary: The name of your site.
- siteTitle.secondary: Optional. A description to appear below your site's name.
- siteTitle.logo: Your site's logo as SVG markup.
-
siteTitle.logoFill: Optional. The fill color of your logo (requires that your SVG uses
currentColorfor stroke and fill values).
Refer to docsify-github-edit-link for a full list of requirements, configuration, and usage options.
GitHub Edit Link comes bundled with Breeze, so there's no need to separately include it's JavaScript plugin.
Refer to docsify-theme-switcher for a full list of requirements, configuration, and usage options.
Theme Switcher comes bundled with Breeze, so there's no need to separately include it's JavaScript plugin.
Refer to docsify-web-component-docs for a full list of requirements, configuration, and usage options.
Web Components Docs comes bundled with Breeze, so there's no need to separately include it's JavaScript plugin.
Refer to docsify-web-component-viewer for a full list of requirements, configuration, and usage options.
Web Components Viewer comes bundled with Breeze, so there's no need to separately include it's JavaScript plugin.
Breeze is fully themeable through the use of "tokens," which are simply native CSS Custom Properties. You can create your own token set by downloading a copy of breeze-tokens.css, editing the values as desired, and including it with your local Docsify installation.
The use of Docsify as a web components documentation platform was inspired by the Shoelace component library documentation by Cory LaViska.
This project was created by Kevin Zolkiewicz and is licensed under an MIT License.
This project is supported by 8th Light.