Alternative input formats

Feature requests
1

Currently, Zola only supports CommonMark.

There have been some requests for Asciidoc and rst.

Adding an input format is a VERY significant amount of work, even assuming there is an existing parser for it in Rust which is a big assumption. Since I don’t personally need it, the implementation would need to come from a contributor.

The goal is not to support every format under the sun as it increases the burden considerably: any addition in the content like the shortcodes need to be replicated n times. Therefore I would prefer to have n <= 2, with my own preference going to Asciidoc for the alternative one.

Any alternative input format needs to support the same feature set as CommonMark:

  • shortcodes
  • automatic header link insertion
  • syntax highlighting
  • link checking
  • relative links
  • summary
2 Likes
2

I want to add a front end to zola, https://github.com/nyar-lang/notedown-rs

I thought of these two options

Built-in interaction

It seems I just need to implement the Page structure here:

The disadvantage of doing this is that there will be a large runtime, which is unfair to users who do not need this mode, and it is not flexible and requires synchronous modification.

Port interaction

Register file type notedown with Zola

When the notedown file changes, pass the file content to notedown_zola for processing, then zola serve reads the result and deserializes it.

The interface might look like this:

[frontend.notedown]
name = "notedown"
file_type = ["note", "notedown"]
preprocessor = "notedown_zola --page ${filepath}"
deserializes = "json"
3

I’d like to add org to the wishlist. There seems to be a working crate for that:

Also, it is a relatively feature-rich format, even when compared to CommonMark:

4

Hello, I would like to see support for asciidoc as well and I would be willing to help implement it but I don’t know where to start at all. I haven’t written a parser before but I consider myself fluent in Rust.
If you are willing to help and maybe guide me a bit I’d love to do this

5

To compare, Hugo has some level of Asciidoc support, which seems essentially to be that they run Asciidoctor on any .adoc file, via their external helper feature. I played around a bit with that in order to if it was feasible to include Asciidoc files into a Hugo-based documentation website.

The initial result was not that good and you do not get an option to pass additional options to asciidoctor. I have seen others work around this by setting up wrapper scripts around asciidoctor, so that Hugo executes the script, which in turn provides the options and additional plugins they wanted.

I had a look at pandoc also, but it does not support converting from asciidoc, only to asciidoc last time I checked.

Anyway, my guess is that something with a reasonable amount of effort would be something similar to how Hugo handles it, perhaps with an option to configure what the command-line to execute should look like.

6

I think using asciidoctor would be very doable and nice but wouldn’t it go against the “single binary with everything built-in” thing?

7

Yes, it certainly does.
Hugo has also had the “single binary for everything” approach for a long time as well but has diverged a bit from that.

An optional and explicit (more explicit than in Hugo) callout to an external tool would not change that approach for most people - if you use Markdown it will only be the same single binary as before. People that would like to use Asciidoc, ReStructuredText, or similar in combination with Zola would likely already have the primary tools of choice for these formats already.

8

I think I agree with you. I might do some experimentation once I find the time and see how well it would work in practice

9

I’m keen on not keeping the “everything in a binary” though. Adding some exceptions like “oh install X to do Y” for many cases just detracts from what Zola is meant to offer. If there was a binding/Rust rewrite of Asciidoc it would be much better.

2 Likes
10

I’m a little confused by what you wrote.
You said you are keen on not keeping the “everything in a binary” but adding these exceptions is not good.
So I’m not sure if you are giving the go ahead or not.

Though I do agree that Rust version of Asciidoctor would be nice and probably even ideal (if we ignore the amount of work it would take to make)

11

Ah sorry I mixed the other sentence I had in mind. I’m keen ON keeping “everything in a binary”

12

I see, that makes a lot more sense.
I might try to work some bindings up using rutie when I get the time but no promises

13

I’d like to propose support for an emerging input format called subtext:

https://github.com/subconsciousnetwork/subtext

https://subconscious.substack.com/p/self-organizing-ideas

It is the markup for Noosphere. Their flagship app is now in beta.

https://github.com/subconsciousnetwork/noosphere

The markup is still in draft mode so there’s ample time to evaluate its usefulness to Zola in the meantime. I am however very excited at the notion of supporting subtext, because together with Noosphere/Subconscious it is designed specifically for “garden writing”, which is how I approach my personal blog.

https://joelhooks.com/digital-garden