Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Custom output formats #365

Open
paulcmal opened this Issue Aug 7, 2018 · 9 comments

Comments

Projects
None yet
3 participants
@paulcmal
Copy link
Contributor

paulcmal commented Aug 7, 2018

Format-agnostic templating for pages and feeds. Here is a generic issue to address issues #311, #293 and potential others.

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

Use-cases

Two main use-cases come to mind:

  • static-file interoperability with other formats for external readers, crawlers, parsers: JSON Feed, Atom, RSS, ActivityStreams (to name a few ¹)
  • building custom read-only APIs, as suggested here

Implementation considerations

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.

Conclusion

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.

@piedoom piedoom referenced this issue Aug 7, 2018

Closed

Serving JSON #293

@Keats

This comment has been minimized.

Copy link
Collaborator

Keats commented Aug 8, 2018

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

@paulcmal

This comment has been minimized.

Copy link
Contributor Author

paulcmal commented Aug 9, 2018

Can you add a few more concrete use-cases?

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.

It can be examples of Hugo sites using it for example.

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.

How many people would use that feature?

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.

@piedoom

This comment has been minimized.

Copy link
Contributor

piedoom commented Aug 9, 2018

Adding to @paulcmal's examples, a JSON API could allow writing frontend stuff in Elm/React/Vue/etc. while only needing one index.html file and keeping the niceness and organization of static site generators. I believe Gatsby is similar (but the less of the JS stack I have to touch, the better my sanity... but still something like Elm/React capability would be in request when I start doing client work with Gutenberg - of course none of that would be included out of the box!).

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.

@Keats

This comment has been minimized.

Copy link
Collaborator

Keats commented Sep 2, 2018

Any chance you could collaborate on writing the documentation for that feature as it would appear in the gutenberg docs? I do that for new features and it forces me to think on how to explain them, whether the UX is good and what is possible with it.

@Keats Keats referenced this issue Sep 3, 2018

Closed

JSON Feed Option #311

@piedoom

This comment has been minimized.

Copy link
Contributor

piedoom commented Sep 4, 2018

I'm unsure as to whom your question is directed, but I can always help if it is wanted.

@Keats

This comment has been minimized.

Copy link
Collaborator

Keats commented Sep 4, 2018

That was for you and @paulcmal I should have been clearer!

@paulcmal

This comment has been minimized.

Copy link
Contributor Author

paulcmal commented Sep 5, 2018

@piedoom @Keats I just opened a pad for this purpose: https://lite1.infini.fr/p/gutenberg-cof

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:

HTML should not be treated differently (however panicking for a missing template seems a bit harsh to me). What do you think?

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 gutenberg serve would not crash but would print the error message and let you visually see that some (part of your) page is missing directly in the built site.

File extension in the content directory may be different than the one we want to produce in the site build

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.

@Keats

This comment has been minimized.

Copy link
Collaborator

Keats commented Nov 22, 2018

Can we move the discussion to the feature request section of https://zola.discourse.group/ ?

@paulcmal

This comment has been minimized.

Copy link
Contributor Author

paulcmal commented Mar 7, 2019

I took some time to work on the pad and opened a discussion on the forum here. We can continue the discussion over there!

ping @derpmarine168 from #311

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.