How to: Including/transcluding another docs block

Just wanted to share a small trick that I don’t see documented elsewhere. I’ve found it super helpful for keeping my docs DRY.

If you have a special note/item that you want to include in the documentation for multiple sources/models/columns/tests, you can create a separate docs block and reference it in the relevant description property in your schema.yml file.

For example, I want to put the same warning on all models that relate to Users in our main webapp.

  1. I’ll create a docs block with just the warning in it. (Lets call it user_related_model_warning.)
    • I like to put each of these in a separate file in the docs folder, and preface them with an underscore, to keep them sorted at the top and separate from the “regular” docs, but this is just a personal preference.
  2. I’ll create all of my regular docs. Let’s say I want to put this warning in front of the docs for the users_referral model, an users_auth model, and users_session model.
  3. Now, I can prepend or append the warning doc block to the regular doc, by adding it in the description property in my schema.yml file. My users_schema.yml file will look something like this:
  - name: users_referral
    description: >
      '{{ doc("user_related_model_warning") }}'
      '{{ doc("users_referral") }}'
  - name: users_auth
    description: >
      '{{ doc("user_related_model_warning") }}'
      '{{ doc("users_auth") }}'
  - name: users_session
    description: >
      '{{ doc("user_related_model_warning") }}'
      '{{ doc("users_session") }}'

The resulting generated docs will contain the content of the user_related_model_warning doc, then a newline, then the content of the regular doc.

As far as I can tell, there’s currently no way to include a docs block in the middle of another doc. You can only put one docs block before or after another one.

Curious to hear if anyone else has any other solutions, suggestions, etc! How do you handle this kind of thing?


This is awesome!
I was messing around with this and it seems you can also drop the outer single quotes and inject a message in between!

in your yml file description:
Screen Shot 2021-09-10 at 8.32.03 AM

docs generated:
Screen Shot 2021-09-10 at 8.32.27 AM

1 Like