jhildenbiddle
commented
6 months ago Offering Docsify as a web component would provide encapsulation. Below is a high-level POC of two Docsify web components: <docsify-site> and <docsify-element> (names TBD).
Docsify "Sites"
A single Docsify web component instance presented as a full-page site (similar to what Docsify renders today). The example below shows a Docisfy site configuration using the default theme and multiple plugins.
<!DOCTYPE html>
<html>
<head>
...
</head>
<body>
<docsify-site></docsify-site>
<script type="module">
import Docsify from "...";
import plugin1 from "...";
import plugin2 from "...";
const root = new Docsify({
plugins: [plugin1, plugin2],
});
</script>
</body>
</html>- Docsify available as ES6 module (no longer an IIFE)
- Docsify instance data is stored on the component (instead of
window) - Docsify "sites" handle the address bar as it does today with both
hashandhistoryoptions available. - Docsify ships with a single default theme CSS bundled in JS, reducing the default Docsify install to single JS file. This default theme will provide "auto" light/dark (default), "light", and "dark" variants.
- Themes are scoped and assigned to components using a
data-themeattribute orthemeconfiguration property. If/when@scopedCSS is universally supported, we can consider switching to nested<link>and<style>elements inside each Docsify web component. - Theme customization is available using CSS custom properties (similar in concept to docsify-themeable, but significantly lighter weight). This allows themes to be extremely light weight, including our default theme which will include light, dark, and auto styles with minimal CSS. This approach also increases the likelihood that we can modify the underlying CSS without breaking third-party themes that rely only on CSS custom properties for styling (which will be our recommended method).
Docsify "Elements"
One or more Docsify web component instances rendered as page elements that co-exist with other non-Docsify page elements. I'm purposely avoiding the word "embed" here since Docsify has its own embeddable content. The examples below shows multiple Docsify elements, each using different themes, custom styles, and plugins.
<!DOCTYPE html>
<html>
<head>
<link rel="stylesheet" href="path/to/custom-theme1.css" />
<link rel="stylesheet" href="path/to/custom-theme2.css" />
</head>
<body>
<!-- Theme and style set via config (see below) -->
<docsify-element id="foo"></docsify-element >
<!-- Theme and style set via attributes -->
<docsify-element
id="bar"
data-theme="custom-theme2"
style="--theme-color: blue;">
</docsify-element >
<script type="module">
import Docsify from "...";
import plugin1 from "...";
import plugin2 from "...";
const rootFoo = new Docsify({
el: '#foo',
plugins: [plugin1],
style: {
'theme-color': 'red',
},
theme: 'custom-theme1',
});
const rootBar = new Docsify({
el: '#bar',
plugins: [plugin2],
});
</script>
</body>
</html>-
Docsify "elements" mock the address bar using a
data-urlattribute on the component root. Manual changes to this value will trigger page changes within the component.<!-- Single element --> <docsify-element data-url="/README.md"></docsify-element > <script> // Manual page navigation document.querySelector('docsify-root').setAttribute('data-url', "/page.md"); </script><!-- Multiple elements --> <docsify-element id="foo" data-url="/foo/README.md"></docsify-element > <docsify-element id="bar" data-url="/bar/README.md"></docsify-element > <script> // Manual page navigation document.querySelector('#foo').setAttribute('data-url', "/foo/page1.md"); document.querySelector('#bar').setAttribute('data-url', "/bar/page2.md"); </script> -
Optionally, window URL parameters can be used to get/set Docsify instance URL(s):
# Single element https://mydomain.com?docsify-url=/foo/page1.md # Multiple elements https://mydomain.com?docsify-url=foo(/foo/page1.md)&docsify-url=bar(/bar/page2.md)
If we go this route, life will be easier if we standardize on this as the one and only way to create Docsify instances. If we try to support both an IIFE for standard sites (as we do today) and a web component, everything gets more complicated because plugins, themes, testing, etc. have to support both types of Docsify instances.
To me, this all boils down to an early glimpse of what a release after v5 could look like. Would love to hear what others think.
paulhibbitts
Koooooo-7
trusktr
We need allow the ability to fully encapsulate Docsify features and state.
With encapsulation, it will be possible later on to mount any number of
Docsifyinstances anywhere in a web site, as well as become possible to wrapDocsifyas a React/Vue/Svelte/etc component that can be used in any framework.Encapsulation changes:
Docsifyinstance's route changes, so that they can be mapped to the address bar in a custom way. Also allow setting Docsify's route from outside, so that a website managing multiple instances can "paginate" Docsify manually.Docsifyclass. Some of this this in #2104 in the items where we're bringing some functions into the classes as private methods.