Composable Tutorials

Use the composable tutorials directive composable-tutorials to organize information into a single page using a combination of selectable options.

The options are displayed in a dropdown menu and the selected content is displayed in the main content area.

These options have a preset definition, but can be overridden by the contents of snooty.toml.

Composable Tutorial Guidelines

When you create composable tutorials, use the following guidelines:

For composable tutorials, use the :options: option to specify the options that the user can select.
For visible content, use the .. selected-content:: directive to specify the content that will be displayed when the user selects an option.
The order of the selected content's :selections: options must match the order of composable tutorial's :options: option.
Do not use the same refs (ie. in includes or sharedinclude) in multiple selected content. Rather, use a uniquely-named ref definition in the selected content.
Use only one composable tutorial per page. This is to ensure that the user can be lead to one composable tutorial per page, with a sticky dropdown menu.

Basic Composable Tutorial

The following example shows the syntax for a composable tutorial:

.. composable-tutorial::
   :options: deployment-type, cluster-topology
   :defaults: atlas, standalone
   How to Create a Composable Tutorial
   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
   .. include:: /includes/composable-tutorials/subtitle.rst
   .. selected-content::
       :selections: atlas, standalone
       This is the content for the atlas, standalone option.
       =====================================================
       .. include:: /includes/composable-tutorials/repeated-content.rst
   .. selected-content::
       :selections: self, standalone
       This is the content for the self, standalone option.
       ====================================================
       .. include:: /includes/composable-tutorials/repeated-content.rst
   .. selected-content::
       :selections: atlas, repl
       This is the content for the atlas, repl option.
       ===============================================
       .. include:: /includes/composable-tutorials/repeated-content.rst
   .. selected-content::
       :selections: self, repl
       This is the content for the self, repl option.
       ==============================================
       .. include:: /includes/composable-tutorials/repeated-content.rst

This will render the following content:

Deployment Type

Cluster Topology

How to Create a Composable Tutorial

This is an included subtitle under the composable tutorial title.

Predefining Custom Options for Composable Tutorials

To see the list of all predefined options that you can use in composable tutorials, go to the Snooty configuration file. You can also add your own options to the predefined set, or override the predefined options by adding the following to your snooty.toml file:

[[composables]]
 id = "interface-atlas-only"
 title = "Interface"
 default = "driver"
 dependencies = [{deployment-type = "atlas"}]
 options = [
     {id = "atlas-ui", title = "Atlas UI"},
     {id = "driver", title = "Driver"},
     {id = "mongosh", title = "MongoDB Shell"},
 ]

Properties of Custom Composable Tutorials

Custom composable tutorials have the following properties:

id: the id of the composable tutorial.
title: the displayed title of the composable tutorial.
default: the default option of the composable tutorial.
dependencies (optional): the dependencies of the composable tutorial. This is used to display the selectable option only if the dependencies are met.
options: the options of the composable tutorial. These also require an id and title property.

Back

Table Directives

Using Refs within Composable Tutorials