This is a test to explore alternative docs table formats.
Docs index options
Major version swizzle
Creates a dropdown at the top of the navigation which allows for selecting an older major version of the docs. Older versions would be nested beneath a version in the path. For example:
| Path | Version |
|---|---|
| 2.x, 3.x and dev | |
| v1 | 1.x and older |
Explicit indent and hidden pages.
In this case, the navigation is deliberately constrained to two levels of navigation, with section headings. 0 indicates a heading and x indicates a doc page which is not linked from the navigation but does appear in the docs tree.
| Level | Path | Navlink |
|---|---|---|
| 1 | Getting started | |
| 1 | install | Install |
| 2 | install/gke | GKE |
| 2 | install/aks | AKS |
| 2 | install/eks | EKS |
Tutorial pages with structure
Let’s make tutorials more like docs, in that they can have a navigation (and possibly even a major version dropdown). The key now is to be able to have a “set of tutorials” which appears as a set of cards inside the text document.
So the framing of tutorials is just docs with headings and tables and lists and images, but then you get a bank of cards by including a Tutorials set. This means that looking at a tutorials page is like looking at a docs page, it can have structure and provide guidance before, during and after each group of tutorial cards.
Tutorials
The precise list of cards in the precise order.
| Card |
|---|
| Get setup |
| Windows setup |
| How to connect to an application, without exposing it to the world |
| Linux setup |
The actual card title would come from the topic. The actual card URL would also come from the title. This is to deal with the same tutorial showing up in card form from multiple places.
XXX it is unclear what the link text (“MacOS Setup”) above does?
The tutorial pages can have multiple different sets of cards interspersed with headings and other content. So you can read a page naturally, and as you scroll down there are a set of tutorials, then more headings and text and images, and sets of tutorials. And all with navigation on the left if desired.
All of the actual content for the card comes from the topic, not the table. The only thing that comes from the table is the link to the topic. The card title is the topic title, and the card metadata is inside the topic.
Tutorial card inside the tutorial topic
A card that would be at the top of the tutorial topic and provide the metadata that goes into the index page. The index page would include only a link to the topic.
| Attribute | Content |
|---|---|
| Summary | Learn how to write a tutorials and have it published on this site, using simple text markup in the CommonMark format. |
| Difficulty | 3 |
| Author | jim@fleetwood.net |
Tutorial
Summary: A single sentence that explains what will be covered in the tutorial.
Difficulty: 3
Author: jim@fleetwood.net
Older ideas
Merged redirect with indents in the navlink
| Page | Redirect | Navlink |
|---|---|---|
| install | Install | |
| install/gke | - GKE | |
| install/aks | - AKS | |
| install/eks | - EKS | |
| config | x |
Major Versions or Eras
Sometimes we need to switch between major versions of documentation. For example, the docs for Juju 1.x, Juju 2.x and Juju 3.x are quite distinct. This requires a dropdown for the version, which maps to a subsidiary directory that hosts the actual cover page and navigation for that major version.
In this case the only content in the topic that is relevant is the version table, everything else is ignored because the page will actually be the version cover or a content page fro a specific version.
First one is the default. Going to the base url (/docs/) would redirect to the default (/docs/v3.x/) where the topic would be the cover+nav.