Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/palkan/docsify-namespaced
Docsify plugin to work with namespaces
https://github.com/palkan/docsify-namespaced
docsify hacktoberfest
Last synced: 27 days ago
JSON representation
Docsify plugin to work with namespaces
- Host: GitHub
- URL: https://github.com/palkan/docsify-namespaced
- Owner: palkan
- License: mit
- Created: 2020-07-24T08:49:36.000Z (over 4 years ago)
- Default Branch: master
- Last Pushed: 2021-06-07T12:11:23.000Z (over 3 years ago)
- Last Synced: 2024-10-06T03:53:54.667Z (about 1 month ago)
- Topics: docsify, hacktoberfest
- Language: JavaScript
- Homepage:
- Size: 39.1 KB
- Stars: 12
- Watchers: 3
- Forks: 1
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.txt
Awesome Lists containing this project
README
# docsify-namespaced
A [docsify](https://docsify.js.org) 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](https://github.com/anycable/docs.anycable.io) and [TestProf](https://github.com/test-prof/docs).
## Installation
```html
```
## Usage
### Minimal example
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))?/`),
and update all the links in the sidebar to start with the matching prefix. For example, if the current page is `/ru/v1/getting_started.md`, 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).
### Adding selectors
A typical way of switching between namespaces is by adding a `` input. This plugin can integrate with the existing selects.
For example:
```js
window.$docsify = {
name: 'Home' +
'' +
'English' +
'Русский' +
'Deutsch' +
'',
// 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.
### Default namespace
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",
}
]
}
```
## Acknowledgements
The project's scaffold is based on [docsify-copy-code](https://github.com/jperasmus/docsify-copy-code).
## License
This project is licensed under the MIT License. See the [LICENSE](/LICENSE.txt) for details.