Using Refs within Composable Tutorials

Refs are meant to be used as links in other parts of the content to a specific part of a page. Since composable tutorials are meant to be used as a single page, the refs should be unique within the composable tutorial. This means that the same ref should not be used in multiple selected contents.

You can define refs in composable tutorials for other parts of documentation. Since each selected content is referring to the same includes file, you would add a unique ref to the selected content.

In the following example, each selected content is refers to the same includes file, but we add a unique ref to the selected content to make the refs unique.

.. 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
       .. _atlas-standalone:
       .. include:: /includes/composable-tutorials/repeated-content.rst
   .. selected-content::
       :selections: self, standalone
       .. _self-standalone:
       .. include:: /includes/composable-tutorials/repeated-content.rst
   .. selected-content::
       :selections: atlas, repl
       .. _atlas-repl:
       .. include:: /includes/composable-tutorials/repeated-content.rst
   .. selected-content::
       :selections: self, repl
       .. _self-repl:
       .. include:: /includes/composable-tutorials/repeated-content.rst

with the includes file of:

.. _repeated-content:
Repeated Content
----------------
...

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.

You must use the refs in the selected content to refer to other content in the same document. :ref:This link to self-repl will refer to the content under the self, repl selection.

Do not use the ambiguously repeated reference of :ref: This is a link to repeated content <repeated-content> should not be used, as it is repeated in each selected content. This would result as such a link to repeated content, which link to the first occurrence of the ambiguous ref.

Back

Composable Tutorials

Headings and Sections