Skip to content
GitLab
Projects
Groups
Snippets
/
Help
Help
Support
Community forum
Keyboard shortcuts
?
Submit feedback
Contribute to GitLab
Sign in
Toggle navigation
Menu
Open sidebar
ESSIF-Lab
eSSIF-Lab framework
Commits
51d2ae03
Commit
51d2ae03
authored
Sep 28, 2020
by
Maria Iliadi
Browse files
Add Terminology & Glossary plugin docs
parent
12cb2a51
Changes
4
Hide whitespace changes
Inline
Side-by-side
docs/terminology-plugin-instructions.md
0 → 100644
View file @
51d2ae03
---
id
:
terminology-plugin-instructions
title
:
Terminology & Glossary plugin docs
---
import useBaseUrl from '@docusaurus/useBaseUrl';
### How it works
This plugin parses docs in two ways:
1.
Parses all markdown files and replaces a specific pattern with a React
component which supports a tooltip functionality (more information below)
2.
Parses all markdown files and generates a glossary page with all the
pattern terms found in the
`.md`
files
## Replace all patterns with tooltip information
When writing documentation, you can use the following syntax:
```
%%term_text|term_name%%
```
where:
-
`term_text`
: The terminology text you want it to be visible in the documentation
page
-
`term_name`
: The filename of the term file, which resides under
`./docs/terms`
directory.
After the successful run of the script, the output of this functionality will be
a React Component, which will render the
`term_text`
as a link, directing to
the term page (which will be generated from the
`term_name`
attribute), and
when the user
*hovers*
the
`term_text`
it will show a brief summary of the term.
### Example usage
Say you want to reference a term that exists under the
`./docs/terms/`
directory,
e.g.
`./docs/terms/party.md`
. You can use the following syntax to reference
this term in your documentation page:
```
Some content that wants to reference the %%Party|party%% term
```
When the script runs, this will be replaced as follows:
```
Some content that wants to reference the <Term reference="party" popup="Popup text">Party</Term> term
```
which supports the functionality explained above.
### How to correctly write a term
This plugin assumes that you follow the structure, as explained below:
Each term should have its own
`.md`
file, inside the
`./docs/terms`
directory,
and it needs to consist of the following structure:
```title="./docs/terms/term.md"
---
id: term
title: Term page
hoverText: This hover text will appear in the documentation page that you reference this term
---
### Term explanation
content here
```
> Pay attention to the `hoverText` attribute, as it's important to provide this
>attribute (along with the default docusaurus attributes), so the plugin can
>fetch the correct popup text to show when referencing a term.
### Running the script
When you are finished referencing terms and generating term pages, you can test
this locally by running the following command:
```
.shell script
$ yarn parse
yarn run v1.22.5
docusaurus parse
Replacing patterns with
<Term
/>
Done in 1.41s.
```
This will replace all `%%term_text|term_name%%` occurrences everywhere with the
React component to support the functionality above.
Here's an example where the terms have been replaced. When the project is up
and running, you can visit the test example on the `/docs/replacement-test` page:
<img alt="replacement-test" src={useBaseUrl('images/replacement-test.png')}/>
## Generate the glossary page
If everything works well with the above procedure, you can then generate a
glossary page, by running the following command:
```
.shell script
$ yarn glossary
yarn run v1.22.5
docusaurus glossary
Alphabetical list of terms
Done in 1.53s.
```
This will generate a file in `./docs/glossary.md` where every term that has been
mentioned above, will be populated in the `glossary.md` page.
When the project is up and running, you can visit the glossary on the `/docs/essif-lab-glossary` page:
<img alt="glossary-page" src={useBaseUrl('images/glossary-page.png')}/>
plugins/terminology-parser/index.js
View file @
51d2ae03
...
...
@@ -46,7 +46,7 @@ function parser(err, files) {
console
.
log
(
'
Error
'
,
err
);
}
else
{
// Iterate through the .md(x) files
for
(
let
filepath
of
files
.
filter
(
filepath
=>
filepath
!=
'
./docs/instructions.md
'
))
{
for
(
let
filepath
of
files
.
filter
(
filepath
=>
filepath
!=
'
./docs/
terminology-plugin-
instructions.md
'
))
{
fs
.
readFile
(
filepath
,
'
utf8
'
,
function
(
err
,
content
)
{
if
(
err
)
throw
err
;
// Regex for finding the pattern: %token_1,token_2%
...
...
static/images/glossary-page.png
0 → 100644
View file @
51d2ae03
111 KB
static/images/replacement-test.png
0 → 100644
View file @
51d2ae03
110 KB
Write
Preview
Supports
Markdown
0%
Try again
or
attach a new file
.
Cancel
You are about to add
0
people
to the discussion. Proceed with caution.
Finish editing this message first!
Cancel
Please
register
or
sign in
to comment