Allow themes to define output formats, media types and params

[Shadow53]

I thought I had put in a request for this before, but I can't seem to find it.

I'd like to be able to define my own custom output formats in my theme to make it easier for users to get certain functionality. The main use case I have in mind is to generate a Netlify _headers file that gets populated with secure default settings, including a CSP containing only those domains being used for site content, e.g. scripts. I may also use this feature to define a "search index" output format so that I can use the JSON output for something else.

The goal here is to make it so users don't have to copy/paste lines of configurations into their config files just to get a theme feature.

[bep]

We have (or had) a general issue about letting the theme set Params. Letting the theme set the "full config.toml" (merged with project) will not be an option (for security reasons, and it would make for some odd surprises).

But I guess:

• Params
• Outputformats
• Probably some others in a whitelist would be OK and obviously useful

[bep]

That said; having a Netlify specific _headers configured in a theme does not sound like a good general use case for this. Only users of Netlify would want this, so that makes it a good "copy and paste" candidate.

[budparr]

I think a good way to approach this is to direct users to a repo of a fully formed site (like a demo) that users can clone to start, instead of adding the theme to a fresh install. You can just point to that in your theme's instructions.

I don't mean to sound condescending as I imagine you've thought through this: Be super careful with CSPs. They can be a real minefield. One approach may be to set it for "notify only" and have a config setting to switch it to active if it's working in the production site.

[Shadow53]

Apologies for the long mess below - lack of sleep makes thinking clearly hard :p

But I guess:

• Params
• Outputformats
• Probably some others in a whitelist would be OK and obviously useful

That's what I was thinking. It would also be useful to be able to enable certain output formats, i.e. home += ["JSON"] when someone enables the search feature (my theme uses Lunr.js and generates a search index as the JSON output of the home page), but creating custom output formats is the more important issue for me. I can call errorf and tell users to add the output format to home pretty easily.

That said; having a Netlify specific _headers configured in a theme does not sound like a good general use case for this. Only users of Netlify would want this, so that makes it a good "copy and paste" candidate.

I'm not sure if we're talking about the same thing here. I want to avoid having users copy this (or something like it - I haven't tested) into their configuration files:

[outputFormats.Netlify]
mediaType = "text/plain"
baseName = "_headers"
isPlainText = true
notAlternative = true

Users would still have to add home = ["HTML", ..., "Netlify"] to their configurations in order to enable the feature, so people not using Netlify wouldn't have to deal with it. This should be all they have to do, though, while the theme has a file somewhere that contains the above definition.

Reading your comment, I get the sense that you understood me as saying that themes should be able to add an existing "Netlify" output format to home. Forgive me if that was incorrect.

---

As a user with multiple sites on Netlify, I got annoyed earlier with having to manually modify multiple _headers files because I had changed the domain of my Piwik/Matomo server when, with this feature, the theme could have done it for me behind the scenes. Similarly, if I decide to disable search on one of my sites, it would automatically remove the host of the Lunr.js scripts from the CSP configuration.

---

I think a good way to approach this is to direct users to a repo of a fully formed site (like a demo) that users can clone to start, instead of adding the theme to a fresh install. You can just point to that in your theme's instructions.

I have a full documentation site for my theme, with links to example configuration files. That is the recommended way to set up a site with my theme, but I've learned to not expect users to read the documentation. I also expect that most users will probably use the hugo new site command and use that config.toml instead of using the one I provide. I may take your advice on that new site repo, but again, I don't expect all users to do that.

(Note to self - make a summarized "Quick Start" guide and link to the repo there)

I don't mean to sound condescending as I imagine you've thought through this: Be super careful with CSPs. They can be a real minefield. One approach may be to set it for "notify only" and have a config setting to switch it to active if it's working in the production site.

I've been caught in that minefield a couple times already. I'm not sure what you mean regarding "notify only" vs "switch it to active", though.

[budparr]

https://developers.google.com/web/fundamentals/security/csp/#report-only

[bep]

@Shadow53 You are right, I thought about outputs and not outputFormats (which makes perfectly sense)

[github-actions]

This issue has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs.