A docsify plugin to work with namespaces
npm install docsify-namespacedA docsify plugin that makes dealing with _multi-dimensional_ documentation (_namespaces_) simpler:
- Automatically updates sidebar links to match the current namespace.
- Handles select input interactions (but do not adds -s for you).
This plugin was built to support multi-language and multi-version documentation for AnyCable and TestProf.
``html`
Register namespaces in you configuration:
`js`
window.$docsify = {
namespaces: [
{
// uniq namespace identifier (no used internally yet but maybe in the future)
id: "lang",
// recognizable values
values: ["ru", "de"],
// whether this namespace must be present in the path or not
optional: true,
},
{
id: "version",
values: ["v1", "v2"],
optional: true,
}
]
}
With the configuration above, whenever the page is loaded, with match the current path using the generated regexp (/^(\/(ru|de))?(\/(v1|v2))?/),/ru/v1/getting_started.md
and update all the links in the sidebar to start with the matching prefix. For example, if the current page is , we make sure that all sidebar links start with /ru/v1.
This allows us to use relative paths in namespace-specific documentations and do not care about absolute links in the sidebar (thus, no need to update them when new namespace levels are added).
A typical way of switching between namespaces is by adding a
For example:
`js`
window.$docsify = {
name: 'Home' +
'',
// disable automatic linking to avoid navigating when clicking on select
nameLink: false,
namespaces: [
{
id: "lang",
values: ["ru", "de"],
optional: true,
// Specify select element query selector
selector: "#lang-selector",
}
],
}
Now this plugin takes care of reacting on select changes and also updating the current select value in case of a direct namespaced URL opening.
You can specify a default namespace to navigate to on page load (in case no namespace is specified in the url) by adding a default option:
`js``
window.$docsify = {
namespaces:
{
id: "version",
values: ["v1", "v2"],
optional: true,
default: "v2",
}
]
}
The project's scaffold is based on docsify-copy-code.
This project is licensed under the MIT License. See the LICENSE for details.