Add basic glossary handling #29
Draft
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Closes OWASP/mastg#3390
Summary
I’ve explored two possible approaches for adding the glossary:
1. One Markdown file per term
• Each term has its own dedicated page.
• Makes terms individually linkable and easier to maintain or expand with additional content (e.g., references, examples).
2. A single Markdown file with all terms
• All terms are collected in one place.
• Benefits include having a built-in table of contents and a single page for quick browsing.
After weighing the trade-offs, I’ve selected the first option (one Markdown file per term) to provide modularity, maintainability, and better deep-linking support.
The position of the Glossary has been decided to appear at the top level of the navigation structure, making it directly accessible without nesting under other sections.
Glossary list view
Single item view
We can optionally support cwe and NIST deeplinks via markdown headers:
References from other locations
We can deeplink terms with
@MAVTG-TERM-xxxx.md:Final thoughts
This section is intended as a glossary, not an index. However, cross-references can still be valuable. For each glossary entry, we can include pointers to where the term is used throughout the content. Feedback and suggestions on this approach are welcome.