DocCardList is a Docusaurus-native component that achieves the same
goal as our custom `remark-toc` plugin, but with Docusaurus APIs instead
of file system lookups. Replace `(!toc!)` mentions so we can remove
`remark-toc`.
Use Docusaurus syntax for admonitions so the docs engine does not need
to replace these. This is one step toward removing the
`remark-update-tags` plugin. See: gravitational/docs-website#94
Relevant commands are included below to make reproducing this work
easier.
1. Replace all `Notice` tags with `Admonition` tags.
2. Add `type="info"` if an Admonition is missing a type.
To find instances:
```
find docs/pages -name "*.mdx" -exec awk '
BEGIN{a=0}
a==0 && /<Admonition/{ a = 1 }
a==1 && /type/{t = 1}
a==1 && />/{ a = 0; if(t == 0) print FILENAME ":" FNR }' {} \;
```
3. Replace `type="notice"` with `type="note"`.
To find instances:
```
find docs/pages -name "*.mdx" -exec awk '
BEGIN{a=0}
a==0 && /<Admonition/{ a = 1 }
a==1 && /type="notice"/{t = 1}
a==1 && />/{ a = 0; if(t == 1) print FILENAME ":" FNR }' {} \;
```
These docs have been incorrect since we introduced an NFS-friendly
audit log directory structure in #1549.
Note: our audit log is very much NOT NFS-friendly, despite the intent
of that old PR.
Closes#44532
Ensure that all docs pages include an introductory paragraph, which
spells out the scope of a page and indicates to a reader whether the
page is appropriate for their needs.
In some pages, the "How it works" section functions like an introductory
paragraph. In these cases, turn the "How it works" section into an
introductory paragraph and add a new "How it works" section.
Other pages already include an introductory paragraph with the H2
"Introduction". Standardize the docs on not including a heading before
the introductory paragraph.
Docusaurus [sidebar
generation](https://docusaurus.io/docs/next/sidebar/autogenerated)
expects category index pages to have one of three file path conventions:
- `section/index.mdx`
- `section/README.mdx`
- `section/section.mdx`
This change standardizes category index paths on the third convention so
Docusaurus sidebar generation succeeds. We can then add checks to the
current docs site to prevent additional menu pages from violating this
convention.
This change also adds redirects to the new category index pages, and
updates internal links to pages that were moved.
Note that this change does not move all relevant menu pages. We still
need to reorganize the `reference/terraform-provider` section. Since
this section is automatically generated, we need another approach to
restructuring it.
Provide a less overwhelming documentation experience for users by
condensing sidebar sections into five, organized loosely around
different audiences of the documentation:
- **Get Started:** new Teleport users, as well as users of all levels
who want to quickly look up key, frequently changing information, such
as the changelog and upcoming release information.
- **Admin Guides:** intermediate users completing a specific task. This
includes all how-to guides in the docs except those in "Get Started"
and "Enroll Resources".
- **Enroll Resources:** Admin Guides, but for our extensive library of
how-to guides for protecting infrastructure resources with Teleport.
- **References:** Advanced users looking for comprehensive reference
information and architecture guides. This includes all reference
guides in the docs.
- **User Guides:** Guides for end users looking to access resources.
Related changes:
- **Move Helm reference partials**. Use the `docs/pages/includes`
directory so we can generate the sidebar from `docs/pages/reference`.
- **Move the Architecture sidebar section** into "References", and move
architecture guides across the documentation into "Architecture".
- **Remove "Documentation Overview"** as this is out of date. Now, top-level
sidebar sections are more self explanatory.
- **Remove "Choose an Edition"**, since we want to elevate Teleport
Enterprise (Cloud), making Teleport Enterprise (Self-Hosted) available
for certain use cases.
- **Add an infrastructure as code section** to Admin Guides.
Paul Gottschling