@mantlebee/docsify-glossary v2.0.3
docsify-glossary
Docsify plugin for auto replacing terms with link to one or more glossaries.
Fork of TheGreenToaster/docsify-glossary, this package aims to improve the previous plugin, adding a configuration section and more flexibility.
Quick Start
Install
- Insert script into docsify document
<script src="//unpkg.com/@mantlebee/docsify-glossary/dist/docsify-glossary.min.js"></script>
- Create a
_glossary.md
file in the root directory - Populate the
_glossary.md
file with terms.
Usage
- Terms must be predicated with
"## "
(without quotes) to get recognized by the glossary - Terms are replaced with links in the order that they appear in the glossary file.
See the examples/default
example, running
npm run example:default
Example: with default options
File _glossary.md
## Main User
Primary user of the platform
File user-example.md
The Main user is responsible for ...
Advanced Usage
The configuration object allows to change the default behaviour.
window.$docsify.glossary = {
filePaths: { "/": "/_glossary.md" },
caseSensitive: false,
glossaryTermRegex: /^## .{1,}/,
convertGlossaryTermRegexMatch: (match) => match.replace("## ", ""),
matchDocumentationTerm: (term, slug) => term,
};
Change how the plugin find and replace terms
The default behaviour is to find the glossary term as is, but is possible to use a different pattern, changing the matchDocumentationTerm
option.
Example: different term match
Configuration
window.$docsify = {
...
glossary: {
matchDocumentationTerm: term = `{${term}}`
}
}
File _glossary.md
## Main User
Primary user of the platform
File user-example.md
The {Main User} is responsible for ...
It is possible to use the slug too.
Example: slug as term match
Configuration
window.$docsify = {
...
glossary: {
matchDocumentationTerm: (term, slug) = slug
}
}
File _glossary.md
## Main User
Primary user of the platform
File user-example.md
The main-user is responsible for ...
Use different glossary files
If your documentation involves different areas that has to be separated, multiple glossary files can be adopted.
Use the following folder structure as reference:
doc/
users/
groups/
...
permissions/
...
...
_glossary.md
licensing/
...
_glossary.md
Configure the plugin to assign a specific glossary file using the route to match the correct one.
Example: multiple glossaries
Configuration
window.$docsify = {
...
glossary: {
filePaths: {
"/users": "/users/_glossary.md",
"/licensing": "/licensing/_glossary.md"
}
}
}
When the page /users/permissions/index.md
is loaded (and all other routes starting with /users
) links to the glossary will redirect to the /users/_glossary.md
page. Same behaviour for routes starting with /licensing
and the /licensing/_glossary.md
page.