Document setting of params, etc from themes

[kaushalmodi]

gohugoio/hugo@e9c7b62

[kaushalmodi]

Example themes/foo/config.toml: https://github.com/gohugoio/hugo/blob/89d2cf49ac0cddfddfc579c143d6b59998553315/hugolib/config_test.go#L122-L176

My example: https://gitlab.com/kaushalmodi/hugo-theme-refined/blob/master/config.toml

[kaushalmodi]

@bep I am starting to add a rough outline of what you can and cannot do in the theme's config.toml. Please add/correct as needed.

Can Do

1. Define new mediaTypes."foo/bar" media types

2. Define new outputFormats.zoo custom Output formats

   Example:

   # Atom feed
   # https://gist.github.com/lpar/7ded35d8f52fef7490a5be92e6cd6937
   [mediaTypes."application/atom"]
     suffix = "xml"
   [outputFormats.Atom]
     # https://validator.w3.org/feed/docs/atom.html#whatIsAtom
     mediaType = "application/atom"
     baseName = "atom" # generated file = <baseName>.<mediaType."application/atom".suffix> = atom.xml
     isPlainText = false
   

3. Define new custom Params. Below will be accessible as .Site.Params.THEME.p1 or .Site.Params.p1 assuming that a param with the same name is not defined in the site config. If both site config and theme's site config have the same param defined, the site's config will take precedence. This can actually be a good way to set some default param values in the theme's config.toml which the user might choose to override in their site config.

   [params]
     p1 = "p1 theme"
   

Cannot Do in themes/foo/config.toml

1. Cannot have [mediaTypes] or [outputFormats] in either the site's config.toml or theme's config.toml. Both places can only do [mediaTypes."foo/bar"] or [outputFormats.zoo].

2. Cannot set frontmatter as that would be partially defining it.

   [frontmatter]
     expiryDate = ["date"]
   

3. Taxonomies

   [Taxonomies]
     category = "categories" # SINGULAR = "PLURAL"
     tag = "tags"
     series = "series"
   

[bep]

Define new custom Params. Below will be accessible as .Site.Params.THEME.p1 or .Site.Params.p1 assuming that a param with the same name is not defined in the site config.

Yes, that is correct. I had, however, a thought the other day that I have not followed up on. Not sure what it was, but it was related to the upcoming "theme merge" feature.

So, the motivation for the "theme params namespace" is to give the theme a place where he/she knows the theme settings will be.

But what is really the theme name? Today it is really the folder below /themes, which the theme author does not control ... Hmm...

[kaushalmodi]

But what is really the theme name?

Should be defined in theme's config.toml? And throw an error if that is not defined?

[kaushalmodi]

Also, should it be made a convention to not have users use [mediaTypes] in their site configs? Because otherwise, the theme won't be able to set [mediaTypes."foo/bar"].

[kaushalmodi]

Surprisingly, I was unable to set the whole Taxonomies map in the theme's config.toml. It would be nice for the theme to be able to set that, which the user can override if they want in their site's config.toml.

[bep]

Surprisingly, I was unable to set the whole Taxonomies map in the theme's config.toml. I

Why is that a surprise? My commit message is pretty clear on what is there.

[kaushalmodi]

Well, surprise not in that sense.. but in the manner that it makes more sense for a theme to be able to set those.. a theme could have custom layouts for series, etc. So it better to set the series taxonomy in the theme by default. But anyways, not a big deal.. I was just documenting the "can do" and "cannot do" for my sake as I was porting stuff from my site's config to that in my theme.

Now there's enough raw material here to start documenting this.

[bep]

Yea, I had to stop somewhere. I have been bitten before because I have rushed into things like these. Taxonomy is not obviously a theme concern.

[stale]

This issue has been automatically marked as stale because it has not had recent activity. The resources of the Hugo team are limited, and so we are asking for your help.
If you still think this is important, please tell us why.
This issue will automatically be closed in the near future if no further activity occurs. Thank you for all your contributions.

[jmooring]

This will be addressed with #1888