terminology-plugin-instructions.md 3.6 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11
---
id: terminology-plugin-instructions
title: Terminology & Glossary plugin docs
---
import useBaseUrl from '@docusaurus/useBaseUrl';


### How it works

This plugin parses docs in two ways:

fmerg's avatar
fmerg committed
12 13 14
  1. Parses all `*.mdx` files under `docs/` and replaces each pattern with an
  appropriate React component supporting a tooltip functionality (see below)
  2. Generates a glossary with all terms corresponding to the `*.md` files under `docs/terms/`.
15

fmerg's avatar
fmerg committed
16 17 18 19 20
Parses all markdown files and generates a glossary page with all the pattern terms found in the .md files

## Replace patterns with dynamical elements

When writing docs, in order to refer to a term, you may use the following syntax:
21 22 23 24 25 26

```
%%term_text|term_name%%
```

where:
fmerg's avatar
fmerg committed
27
- `term_text`: The terminology text you want it to be visible in the documentation
28 29 30
page
- `term_name`: The filename of the term file, which resides under `./docs/terms` directory.

fmerg's avatar
fmerg committed
31 32 33 34 35
inside `docs/*.mdx` files. After successfully running the script, the above occurrence
will be replaced by a React component, which will render `term_text` as a link to the
corresponding term page, which is in turn generated from the `term_name` attribute;
furthermore, *hovering* over `term_text` displays a term summary, as extracted from the
corresponding term page.
36 37 38

### Example usage

fmerg's avatar
fmerg committed
39 40
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
41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58
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:

fmerg's avatar
fmerg committed
59
Each term should have its own `.md` file, inside the `./docs/terms` directory,
60 61 62 63 64 65 66 67 68 69 70 71 72 73
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
```

fmerg's avatar
fmerg committed
74 75
> Pay attention to the `hoverText` attribute, as it's important to provide this
>attribute (along with the default docusaurus attributes), so the plugin can
76 77 78 79
>fetch the correct popup text to show when referencing a term.

### Running the script

fmerg's avatar
fmerg committed
80 81
When you are finished referencing terms and have written corresponding term pages,
you can test this locally by running the following command:
82 83 84 85 86 87 88 89 90

```.shell script
$ yarn parse
yarn run v1.22.5
 docusaurus parse
Replacing patterns with <Term />
Done in 1.41s.
```

fmerg's avatar
fmerg committed
91 92
This will replace all `%%term_text|term_name%%` occurrences with the React component
supporting the required functionality.
93

fmerg's avatar
fmerg committed
94
Here's an example where the terms have been replaced. When the project is up
95 96 97 98 99 100 101
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

fmerg's avatar
fmerg committed
102
If everything works well with the above procedure, you can then generate a
103 104 105 106 107 108 109 110 111 112
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.
```

fmerg's avatar
fmerg committed
113
This will generate a file in `./docs/glossary.md` where every term that has been
114 115 116 117 118
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')}/>