Exclude/ Include content files based on front matter value

Hi there,

I am using the Docsy Hugo theme and I am trying to find a way to exclude certain folders and files from the rendered content based on values that I set in the front matter.

For example, this is a sample file structure:

about/index.md
about/overview.md
about/architecture.md

I want to now build two versions of the doc:

  1. with about/index.md + about/overview.md
  2. with about/index.md + about/architecture.md

I would ideally like to add some value to the front matter of each page and then specify the value that I want to build in the config.toml file. So that depending on what value I set in the toml file, I will get these two different outputs.

I looked into the includeFiles/ excludeFiles feature, but it seems like I need to know the file name or pieces of it in order to use it.

Is something like that possible?

Thank you so much for your help!

Use different environments along with cascade and _build options.

config/
β”œβ”€β”€ _default/
β”‚   └── config.toml
β”œβ”€β”€ exclude_architecture/
β”‚   └── config.toml
└── exclude_overview/
    └── config.toml

config/_default/config.toml

baseURL = 'https://example.org/'
languageCode = 'en-US'
title = 'Something'

config/exclude_architecture/config.toml

[[cascade]]

[cascade._build]
list = 'never'
render = 'never'

[cascade._target]
path = '/about/architecture.md'

config/exclude_overview/config.toml

[[cascade]]

[cascade._build]
list = 'never'
render = 'never'

[cascade._target]
path = '/about/overview.md'

Then build your site with either of these:

hugo -e exclude_overview
hugo -e exclude_architecture

Also, I assume your content looks like:

content/
β”œβ”€β”€ about/
β”‚   β”œβ”€β”€ _index.md        <-- not "index.md"
β”‚   β”œβ”€β”€ architecture.md
β”‚   └── overview.md
└── _index.md

I forgot that we added an environment option to the target options, so you can do this with just one config file.

config.toml

baseURL = 'https://example.org/'
languageCode = 'en-US'
title = 'Something'

[[cascade]]

[cascade._build]
list = 'never'
render = 'never'

[cascade._target]
environment = 'exclude_architecture'
path = '/about/architecture.md'

[[cascade]]

[cascade._build]
list = 'never'
render = 'never'

[cascade._target]
environment = 'exclude_overview'
path = '/about/overview.md'

Hey @jmooring ,

thank you so much for your reply. Instead of specifying the path to the file directly in the cascade block, is there an option to do the same logic but based on a value that I set in the front matter? My overall goal is to build different versions of my doc set. And I would like to be able to β€œtag” a page for a specific version and then tell hugo to build only the pages that have that tag, and to ignore the pages that do not have the tag.

So in my example above, I could do something like this

content/
β”œβ”€β”€ about/
β”‚ β”œβ”€β”€ _index.md (tagged for version 1 and 2)
β”‚ β”œβ”€β”€ architecture.md (tagged for version 1)
β”‚ └── overview.md (tagged for version 2)
└── _index.md (tagged for version 1 and 2)

And then I would like to run Hugo for version 1 and only build the pages that have version 1 in the front matter.

Thanks so much for your help.

No.

Wouldn’t that require something like this for pages that don’t change over time?

versions = ['v0.101.0','v0.102.0','v0.103.0','v0.104.0','v0.105.0','v0.106.0','v0.107.0','v0.108.0','v0.109.0']

It seems like versioning your docs repository would be a simpler approach less prone to error.

Yes, I would essentially like to set a version tag on a content file and then build only the files for a specific version. The content file and folder structure is generally the same between versions and we also only support a handful of versions at a time. Usually changes to the folder/ file structure will be backported to all other versions, but in some rare cases they are not.

We are already able to build output for different versions when both versions use the same file and the content in the file is just slightly different (we use shortcodes for that). But now I am just missing the piece that I can hide an entire page if this page belongs only to a specific version.

I was looking into reusing the tags and categories for this case. But I also could not figure out how to build only files with certain tags/ categories.

Can you think of another way to accomplish this? If not, I will play around with the cascade option that you described earlier and then basically list the files that we do not want to build separately. That should definitely work I think. It will just be a little more manual. But given that this is a rare use case, it might not be too bad actually.

Thank you!

I would encourage you to future-proof your content model. Cases that are rare today may not be so rare in the future.

No, I cannot.

Thank you! I tried out the cascade option and I think this will work pretty well with what we want to accomplish.

Thank you so much for your help and support!

1 Like