Skip to content

External YAML files

Including external YAML files is where this feature becomes really powerful:

  • Allows you to create large YAML sources, without cluttering up your mkdocs.yml.
  • Creates the possibility of single-sourcing content: for example, you could have a YAML file containing help text that you then display both in-app and in your docs.
  • And intriguing possibilities for rendering OpenAPI spec files . . .

The plugin docs have more information on Including external yaml files.

Example: Include a YAML file from your project

Code

# In mkdocs.yml
plugins:
  - macros:
      include_yaml:
        - _yaml/simple-example.yml

# In _yaml/simple-example.yml
simpleYamlOne: 1
simpleYamlTwo: two

# In your Markdown
* Simple YAML 1: {{ simpleYamlOne }}
* Simple YAML 2: {{ simpleYamlTwo }}

Output

  • Simple YAML 1: 1
  • Simple YAML 2: two

Example: Include a YAML file from an external URL

You can load YAML from files hosted outside your project using modules.

This example loads an OpenAPI example, petstore.yaml.

Code

Create a file, main.py, at the root of your project:

import requests, yaml

def define_env(env):
  url = 'https://raw.githubusercontent.com/OAI/OpenAPI-Specification/main/examples/v3.0/petstore.yaml'
  r = requests.get(url, allow_redirects=True)
  content = r.content.decode()
  open('_yaml/petstore.yaml', 'wt').write(content)
  with open('_yaml/petstore.yaml') as petstore:
    env.variables['petstore'] = yaml.safe_load(petstore)

Access the petstore YAML in your Markdown:

**Petstore version:**
{{ petstore.info.version }}

**Summary of the `/pets` endpoint `get` operation:**
{{ petstore.paths['/pets']['get'].summary }}

**Summary of the `/pets` endpoint `post` operation:**
{{ petstore.paths['/pets'].post.summary }}

Output

Petstore version:

1.0.0

Summary of the /pets endpoint get operation:

List all pets

Summary of the /pets endpoint post operation:

Create a pet

Special characters and keywords

You need to wrap your YAML keys in [''] if you YAML key:

  • Starts with a special character, such as /
  • Clashes with an operation, such as dict.get()