Join GitHub today
GitHub is home to over 31 million developers working together to host and review code, manage projects, and build software together.Sign up
Custom output formats #365
Currently, from what i gathered, gutenberg only builds content to HTML format, and a specific piece of code generates exactly one RSS feed for the whole site following a themable template (rss.xml). It would be really nice to allow for custom output formats, that is user-definable (in a theme or in the site) templates for formats other than HTML, such as JSON.
TL;DR: How to allow RSS & other feed types for your blog, and enable publishing the content in even more obscure formats for your very niche use-cases x_x
Two main use-cases come to mind:
All content files should be outputtable in different formats : all feeds (sections, taxonomies) and pages. If a template is not available in a format that should be enabled for that content, should we panic or just print a warning? I think this behaviour could be consistent across formats and HTML should not be treated differently (however panicking for a missing template seems a bit harsh to me). What do you think?
Enabling output formats should take place in config.toml for the whole site, but additional section-specific formats should be possible to implement, and would go along really well with the per-section theme feature proposed in #159. So that for instance your blog may be published as HTML/JSONFeed/RSS but another section should be just HTML because an RSS of it wouldn't make sense.
File extension in the content directory may be different than the one we want to produce in the site build, for whatever reason (mimetypes concerns on a caching proxy, webdev laziness of not having to configure syntax highlighting for many different extensions, etc). The syntax could support for instance building content following template.atom.xml to content.atom (or the other way around) by just providing a couple of strings for each format (the extension to look for in templates, and the extension to replace it with) ← Am i overthinking it?
Hugo also supports a such feature, see their docs about it.
Does everyone agree this is an interesting feature? Is there gutenberg-specific implementation concerns i haven't thought of? Or performance considerations to study? Let's work it out :)
⁽¹⁾ I did not cite AMP as it does not bring anything over raw and lightweight HTML/CSS (without JS) in my opinion. But of course you could build AMP pages with custom output formats.
Can you add a few more concrete use-cases? It can be examples of Hugo sites using it for example.
How many people would use that feature? I don't think I would myself (hell, not sure I really understand it after looking at the Hugo docs) so I need a few motivated persons to explain in details what this would allow them to do
A concrete example pet project i have is making a theme for local non-profit libraries/infoshops to have all their collection publicly available as read-only HTML pages. I would like RSS feeds as well so people can subscribe to an infoshop's newest additions, or to a mere category/tag.
But i would also like to consume the data as JSON in an Android application where i can subscribe to several libraries and have aggregate newest entries, including by feed. ActivityStreams is W3C-standard extensible JSON-LD schemes for such use-cases that supports collections, authorship, pagination…
So I would like the same content pages to render feeds as HTML/RSS/ActivityStreams, and the pages to render as HTML/ActivityStreams.
Sorry i don't know any complex live setup. However all hugo websites generating RSS feeds do it using Custom Output Formats, because all feeds render by default to HTML & RSS, while simple pages only render to HTML.
Combined with hugo's theme composition feature, that allows you to maintain themes for different formats separately. For example, you just add a JSON Feed theme to your theme composition and voila, your site supports JSON Feed. That means theme-independant one-click setup for JSON Feeds.
Many people build public read-only APIs for content that doesn't get updated too often, with JSON or XML as format. They usually do this in PHP/NodeJS/whatever which is far from optimal. Achieving the same with a static-site generator is both simpler, easier to maintain in the long run, easier to backup (simple folder), and more ecological (no need to regenerate the site on every request). Here's a tutorial on how to achieve this with hugo's custom output formats.
Adding to @paulcmal's examples, a JSON API could allow writing frontend stuff in Elm/React/Vue/etc. while only needing one
I do have one critique of paul's examples in that the page/section format is less ideal for an arbitrary data API. I can understand it for e.g. company blog posts, even maybe a product inventory - but other than "page-like" items, it might be better to go with something else. That's not to say a JSON format wouldn't be useful, just that it wouldn't be a good idea to replace every use case. Though I'm sure that's not really what you were saying :)
Being said, having a static-data-api generator project thing would be really neat! I don't know if such a thing exists... but it'd be neat.
If that's okay with you, I'd propose to limit most changes to adding information and simple rephrasing. Reworking a paragraph fully should be done right underneath preceded by a symbol (leaving the two visible for comparison). Reworking the whole text when need be should be done further down the page, with a clearly visible separator. The rest (deciding between versions of paragraphs) can be discussed in the pad chat (bottom-right window) by people interested in this feature.
Are those guidelines okay by you?
PS: In my original post I asked a couple design questions which are fundamental to the end-user-experience. I'd like your opinion (and others') on these:
In retrospect, pretending the site built just fine is not a good option either. Would a sane middle ground be to return 1 (so tests fail) and output fancy warnings, but still produce the whole build without interrupting it (producing an empty output for missing templates)? This way CI-style builds would not build the site and warn about a missing template, but
This i still have no concrete idea about. As a source of inspiration, hugo's Custom Output Formats are very complex and have long docs.