Skip to content

Reuse

I'm demonstrating variables and content references that could apply at various levels of the document (local) or organization documents (suite or global).

I'm using the mkdocs-macros plugin. This plugin enables several reuse use cases.

Product Name (Singular)

I'll make up a product. I'll call it, pbjStand.

pbjStand makes delicious sandwiches.

Did you know that I've been using a variable for pbjStand? I'll show you.

In the case of a situation where you only have to talk about a single product, you can define the product name variable in your mkdocs.yml and then insert throughout your documentation.

Example

Definition of the variable in the mkdocs.yml.

extra:
  productName: pbjStand

Use of the variable on this page.

I'll make up a product. I'll call it, {{ productName }}.

Check My Work

Click the at the top of the page ⬆️

Product Names (Multiple)

Now, I have two (or more) products. I'll call them:

  • {{ productName1 }}
  • {{ productName2 }}

Instead of packing potentially dozens of product names into the mkdocs.yml, I can create a variable library, product_names.yaml. Externalizing variables into a library file helps keep your mkdocs.yml tight while having a one-stop for variables. I could also create more library files for other kinds of variables such as approved terminology or organization variables. Depending on the complexity of your docs, you might even have these libraries external to your doc repo and you pull them into your CI/CD workflows.

Example

Definition of the variables in the variable library.

#product_names.yaml

productName1: "Carrot Cake Donut"
productName2: "Cheesecake Donut"

Pointing the configuration (mkdocs.yml) to the content library.

plugins:
  - macros:
      include_yaml:
        - product_names.yaml

Use of the variable on this page.

Now, I have two (or more) products. I'll call them:

- {{ productName1 }}
- {{ productName2 }}

Check My Work

Click the at the top of the page ⬆️

Embed Content

I want the concept of a content reference or a reusable chunk of content that appears in multiple parts of my document. The use cases are myriad. Perhaps I want to repeat how to generate a token many times throughout my dev docs instead of creating a lot of links. Perhaps I have a great tutorial that I want to reuse. Or maybe I just want to have a consistent copyright statement or legal disclaimer across my docs.

Example

Pointing the configuration (mkdocs.yml) to a directory with reusable content.

plugins:
  - macros:
      include_dir: include

Content of the include directory.

.
├─ include/
│  └─ embed_content.md
└─ mkdocs.yml

Adding the content reference inline.

{% include 'embed_content.md' %}

Check My Work

Click the at the top of the page ⬆️

Reuse Content from Another Repo

This is not magic. In my GitHub workflow file, I pull in the content from another repo and copy it into the contents of my main repo build process so that all relevant content is available during the site build.

Example

In this case, I'm pulling in all the content from my content_lib repo.

The content_lib repo contains a variable library file (var_lib.yaml). The var_lib.yaml file contains two variable key-value pairs.

#var_lib.yaml

productName3: "PBJ's Writing Service"
productName4: "PBJ's Bike Shop"

Below 👇, I have two variables that are NOT defined in the contained repo, project_mkdocs_material. Again, these variables are defined in the content_lib repo.

PBJ's Writing Service

PBJ's Bike Shop

Check My Work

Click the at the top of the page ⬆️

Conditions

Perhaps you want to show or hide content in certain contexts like for certain user types or deployment types.

Audience

This is user content.

{% if audience == "user" %}
This is user content.
{% elif audience == "dev" %}
This is developer content.
{% endif %}

Check My Work

Click the at the top of the page ⬆️