Add a glossary of Rancher-specific terms #358
Description
Summary:
Rancher (and other SUSE projects/products) use some jargon that can be confusing for newbies.
Details:
Kubernetes already has some overhead in the form of jargon ("charts", "pods", etc.)
Rancher and other SUSE projects and products also come with their own jargon. It can sometimes be difficult to tell if something is a general Kubernetes term or if it's specific to Rancher or RKE.
Examples:
- Rancher using "project" for, roughly, "namespace" (I realize this is because projects predate namespaces)
- RKE 2 using "machine" for "node"
Let's compile a list of our jargon and put it in the docs as a glossary.
The glossary pages we added to the docset include a lot of HTML tags. This note was originally listed on the glossary page files, explaining why:
This page uses HTML definition list tags. dl indicates the start and end of a definition list. dt indicates the defined term, and dd the definition. These will stay in place until we upgrade to Docusaurus 3 and are able to add the remark-definition-list plugin for native Markdown syntax. We are currently blocked as the plugin requires a handler that isn't currently exposed. See facebook/docusaurus#8743 (comment) and facebook/docusaurus#9674
More context on this from #1125:
We (@martyav & @sunilarjun) looked into adding a plugin that would provide native Markdown syntax for definition lists. We landed on this page , which has instructions on adding remark-deflist (repo) to your Docusaurus instance, but the instructions didn't seem to work for our config. I tried remark-definition-list (repo), but that didn't work either. While looking for a solution, I ran across this facebook/docusaurus#8743 (reply in thread) an https://github.com/facebook/docusaurus/discussions/8743complaining that the instructions for adding Remark plugins needed improvement. It seems that the plugins need a remark-rehype handler to be configured. There was a https://github.com/facebook/docusaurus/pull/9674to add this functionality to the Docusaurus config file, but I don't think it's available yet on Docusaurus 2. We might need to upgrade to Docusaurus 3. In the meantime, the HTML tags are perfectly functional.