[Proposal] Custom Output Formats

Hi, following discussion on the bugtracker, i took a little time to explicit what custom output format support could look like in Zola.

It’s all taking place on a pad following cooperation guidelines proposed on the bugtracker ⁽¹⁾ (these can of course be question and amended).

If something on the pad is not clear please point it out. I intend this draft document to slowly evolve into the actual documentation page about this particular feature.

Feel free to provide constructive criticism and outrage if i missed some obvious issue :slight_smile:

⁽¹⁾ Sorry i can’t post more than two links in a post as my account is new so you’ll have to search the page for “those guidelines”.

1 Like

Now that 0.6 is out of the door we can look at that, I didn’t forget about it!

Ok I understand better custom output formats now.

It does make sense to support that I think if we can make it easy to do so and it looks easier to implement than I thought.

Does anyone know open-source projects using them a lot in Hugo or something similar to see some use in real life?

I guess this is a very common pattern of what you would do with it. Apart from this, i unfortunately don’t have any source to show interesting examples :-/

I don’t think it would be so much harder to implement from scratch. The main issue i see is the current codebase has hardcoded defaults for HTML/RSS output and so we need to come up with some more generic logic. Or am i missing something?

In my opinion, “content kinds” (i.e. page/section templates) are a very useful mental tool to make custom output formats easier to implement and to use for website admins, because usually you only change output formats for a different content kind (like adding iCal output for “events” content kinds) or site-wide (like for RSS, or Algolia in the previous example).

1 Like

Hello.

Apologies for bumping an ancient thread. However, I looked at the code for this and it would be very simple to implement in a reverse-compatible way, which I would be willing to submit as a PR if it is agreeable, since I find it personally quite useful.

  1. Add an option to the Config main section called template_extensions, with the type Vec<String> and a default value of vec!["*ml".to_string(), "md".to_string(), "txt".to_string()] (components/config/src/config/mod.rs).
  2. Update the template glob pattern to use this configuration value instead of the hardcoded extensions (components/templates/src/lib.rs).
  3. Update the Configuration doc page to reflect the added option (docs/content/documentation/getting-started/configuration.md).
  4. Add the filename frontmatter property as described in: Non-Standard Template Extensions | Template Extensions other than .html | Functionality akin to resources.ExecuteAsTemplate and resources.FromString in Hugo - #11 by sirinath (components/content/src/front_matter/page.rs)
  5. Handle the filename property when rendering (components/site/src/lib.rs)
  6. Describe the added frontmatter value in the docs (docs/content/documentation/content/page.md)

Since the configuration value default would have the existing hardcoded value, it would not change the behavior of existing websites on upgrade. This change would also be unobtrusive and local (doesn’t affect other existing functionality), with a nice value-add, in my opinion.

I’ve published the following branch with the above changes:

Let me know what you think.

(PS: The pad posted by OP is no longer accessible.)

I rebased the branch against next and after testing with a toy folder I’m running into a handful of issues that would need to be fixed for this to really be useful:

  1. Content from markdown is only available rendered in html, and the content’s markdown text, let alone the syntax tree of the content, is not available in the template. So unless you’re just rendering html that doesn’t use the filename html, you’re probably best off leaving the content empty then and putting whatever you want rendered into the frontmatter only.
  2. Even though a directory’s pages have in_search_index = false, the folder will still show up in the sitemap.xml. This might be an unrelated existing issue, or it could be a quirk of my own changes. Regardless, with the brief time I spent looking at sitemap generation, I didn’t really understand how it was working, so I would need to look more to figure out which is the case.

These changes could still be useful, but as it stands, probably shouldn’t be seen as a user-friendly path to rendering anything that isn’t basically html anyways.