Glossary Enhancements - Githubissues

sddevelopment-be / penguin-pragmatic-patterns

A learning and development repository, aimed to share knowledge with other (technical) professionals.

https://patterns.sddevelopment.be

European Union Public License 1.2

4 stars 3 forks source link

Glossary Enhancements #43

Open stijn-dejongh opened 11 months ago

stijn-dejongh commented 11 months ago

Similar to docsify, adding links from content pages towards the glossary would make the reading experience more enjoyable.

Context

We want to encourage underatanding and clarity. To do so, jargon used in the knowledge base should eiher be explained in it's immediate context, or be added to the glossary.

For potential future integrations, it would make sense to include alternate content access methods for the glossary terms, such as XML, or JSON. This would encourage re-use by other people.

Acceptance criteria

[ ] terminology used in text refers to glossary definition
[ ] the glossary page itself is exempt from this logic
[ ] add an XML rendering of the glossary terms, including an XSD schema file

Implementation Caveats

avoid client-side scripting if possible
consider writing a custom Hugo preprocessor to add links to textual pages
make sure the links to glossary definitions is subtle, but readable (e.g. a thin, dashed line, and a cursor change to the info pointer). Will require a custom terminology link css class.

stijn-dejongh commented 10 months ago

Update: As a first iteration, consider porting the docsify-glossary javascript utility to the knowledge base. While it implies client-side processing, it would get the implementation done much quicker.

To be checked: page render time impact (especially on slow internet connections).

stijn-dejongh commented 3 months ago

Update: possible implementation

We can rework the generation of content pages by adapting the way HTML pages are generated. Concretely, the ReplaceRe and RelRef functions in HUGO can be used to create a custom content pipe, similar to markdownify. This can then be applied to selected sections, and replace occurrences of Glossary-included terminology and abbreviations with links to the glossary.

Update: Additional feature

Include permalinks to each of the glossary's elements. Consider adding a UUID to each element, to make sure the links act as true permalinks and do not break when the content/name of entries is modified.