Commit 15dc2485 authored by fmerg's avatar fmerg
Browse files

Textual changes

parent 4ad40578
...@@ -9,33 +9,35 @@ import useBaseUrl from '@docusaurus/useBaseUrl'; ...@@ -9,33 +9,35 @@ import useBaseUrl from '@docusaurus/useBaseUrl';
This plugin parses docs in two ways: This plugin parses docs in two ways:
1. Parses all markdown files and replaces a specific pattern with a React 1. Parses all `*.mdx` files under `docs/` and replaces each pattern with an
component which supports a tooltip functionality (more information below) appropriate React component supporting a tooltip functionality (see below)
2. Parses all markdown files and generates a glossary page with all the 2. Generates a glossary with all terms corresponding to the `*.md` files under `docs/terms/`.
pattern terms found in the `.md` files
## Replace all patterns with tooltip information
When writing documentation, you can use the following syntax: 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:
``` ```
%%term_text|term_name%% %%term_text|term_name%%
``` ```
where: where:
- `term_text`: The terminology text you want it to be visible in the documentation - `term_text`: The terminology text you want it to be visible in the documentation
page page
- `term_name`: The filename of the term file, which resides under `./docs/terms` directory. - `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 inside `docs/*.mdx` files. After successfully running the script, the above occurrence
a React Component, which will render the `term_text` as a link, directing to will be replaced by a React component, which will render `term_text` as a link to the
the term page (which will be generated from the `term_name` attribute), and corresponding term page, which is in turn generated from the `term_name` attribute;
when the user *hovers* the `term_text` it will show a brief summary of the term. furthermore, *hovering* over `term_text` displays a term summary, as extracted from the
corresponding term page.
### Example usage ### Example usage
Say you want to reference a term that exists under the `./docs/terms/` directory, 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 e.g. `./docs/terms/party.md`. You can use the following syntax to reference
this term in your documentation page: this term in your documentation page:
``` ```
...@@ -54,7 +56,7 @@ which supports the functionality explained above. ...@@ -54,7 +56,7 @@ which supports the functionality explained above.
This plugin assumes that you follow the structure, as explained below: This plugin assumes that you follow the structure, as explained below:
Each term should have its own `.md` file, inside the `./docs/terms` directory, Each term should have its own `.md` file, inside the `./docs/terms` directory,
and it needs to consist of the following structure: and it needs to consist of the following structure:
```title="./docs/terms/term.md" ```title="./docs/terms/term.md"
...@@ -69,14 +71,14 @@ hoverText: This hover text will appear in the documentation page that you refere ...@@ -69,14 +71,14 @@ hoverText: This hover text will appear in the documentation page that you refere
content here content here
``` ```
> Pay attention to the `hoverText` attribute, as it's important to provide this > Pay attention to the `hoverText` attribute, as it's important to provide this
>attribute (along with the default docusaurus attributes), so the plugin can >attribute (along with the default docusaurus attributes), so the plugin can
>fetch the correct popup text to show when referencing a term. >fetch the correct popup text to show when referencing a term.
### Running the script ### Running the script
When you are finished referencing terms and generating term pages, you can test When you are finished referencing terms and have written corresponding term pages,
this locally by running the following command: you can test this locally by running the following command:
```.shell script ```.shell script
$ yarn parse $ yarn parse
...@@ -86,10 +88,10 @@ Replacing patterns with <Term /> ...@@ -86,10 +88,10 @@ Replacing patterns with <Term />
Done in 1.41s. Done in 1.41s.
``` ```
This will replace all `%%term_text|term_name%%` occurrences everywhere with the This will replace all `%%term_text|term_name%%` occurrences with the React component
React component to support the functionality above. supporting the required functionality.
Here's an example where the terms have been replaced. When the project is up 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: and running, you can visit the test example on the `/docs/replacement-test` page:
<img alt="replacement-test" src={useBaseUrl('images/replacement-test.png')}/> <img alt="replacement-test" src={useBaseUrl('images/replacement-test.png')}/>
...@@ -97,7 +99,7 @@ and running, you can visit the test example on the `/docs/replacement-test` page ...@@ -97,7 +99,7 @@ and running, you can visit the test example on the `/docs/replacement-test` page
## Generate the glossary page ## Generate the glossary page
If everything works well with the above procedure, you can then generate a If everything works well with the above procedure, you can then generate a
glossary page, by running the following command: glossary page, by running the following command:
```.shell script ```.shell script
...@@ -108,7 +110,7 @@ Alphabetical list of terms ...@@ -108,7 +110,7 @@ Alphabetical list of terms
Done in 1.53s. Done in 1.53s.
``` ```
This will generate a file in `./docs/glossary.md` where every term that has been 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. 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: When the project is up and running, you can visit the glossary on the `/docs/essif-lab-glossary` page:
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment