Experimenting with docs navigation and tutorials

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.


The precise list of cards in the precise order.

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


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.

Version Directory
Version 3.x and current dev v3.x
Version 2.x v2.x
Version 1.x v1.x

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.

Table of contents