AsciiDoc, Liquid and Jekyll | Hacker News Reader

AsciiDoc, Liquid and Jekyll

mattrighetti.com

107 pointsmattrighetti26 comments

One of the reasons we built https://ftd.dev is this. Check out this example: https://fifthtry.github.io/bling/chat/

Unlike what you did, here you can create new component in ftd itself, so there is no limit to how many such components you can create while authoring content.

Maybe you are tired of single quote block: https://fifthtry.github.io/bling/quote/

This looks great. This is the first I have heard of ftd. It wasn't clear how to use it though. https://ftd.dev/docs/ doesn't link to the Installation, Getting started and Tutorial

Yeah, docs are pretty lacking. The language is in very early stage and has gone through some changes rendering existing docs out of date. Jan we created a 0.3 version of our syntax after 2 years or so of development and we feel good about it and have started updating the docs now.

You can checkout a video course: https://ftd.dev/expander/. And maybe join us on our Discord.

This seems to be part of an ecosystem. But I'm not sure what are the advantages. What does ftd do better than markdoc and what can it do that markdoc can't?

The key difference is that ftd is a single full stack language. You can make api calls, write custom functions, build components, use components etc etc.

A language designed for authoring. But still powerful enough (one day, it’s work in progress) that you can build most UI in it.

The current tech zeitgeist (generative AI) is moving bewilderingly fast and has changed writing and programming in ways unimaginable 5 years ago, but it still warms my heart to see HN posts about the latest in plaintext formats and static site generation

Nice writeup

I faced the exact same problem, and came up with roughly the same solution, except with Markdown, Jinja, and my own static site generator.

I needed to include calculators such as {% include "blocks/tableOfContents.html" %}, as well as constants like {{ MEDIAN_INCOME }}. These are inside the content, not at its edges.

Python-Markdown's approach is to store these tags somewhere, replace them with a placeholder, parse the content, then put the tags back, untouched. So the Markdown gets converted to HTML, but the Jinja blocks are untouched. The Jinja parser then renders those into the final template.

Great explanation! Useful and neat walkthrough of how it’s put together.

Might have some neat ideas on how to make it an abstraction, and expose it as a standard interface.

I like the name “data templates” for this, though Hugo and many other tools have this built in, as I understand it. Though I haven’t used those much.

The author mentions near the end that “…only issue that I have right now is that the content of the block is not getting parsed since I’m just putting it into a string variable and spitting it out in the HTML variable as-is”. It might be as simple as calling the top-level AsciiDoc render function on the content.

very nice, will definitely try to replicate this with my nim project nimib, my guess it should be much more straightforward to create a nice api.

[0]: https://github.com/nimib-org/nimibex/issues/11 [1]: https://github.com/pietroppeter/nimib

i did NOT know jekyll supported asciidoc.

does this work with Github Pages workflow ?

Not sure if this is in the list of allowed plugins, but…While the “deploy the GH-pages branch” workflow is still around, you can now just go to the settings of your repo and switch to actions mode, and it will generate an actions workflow that does it for you, and supports any plug-in.

Though, of course, at that point where you are building your own actions workflow for GH pages deploy, you may wish to consider an SSG with deeper Asciidoc native support rather than using Jekyll with plugins.

Fair point, but one minor correction is that technically it’s an out of the box action from a template, officially provided by GitHub. Not a huge difference, but you don’t really lose anything that you’d have from the traditional deployment method. It’s more like running ‘eject’ on a create-react-app app.

Sure, just pointing out that once you've got a workflow yaml, adding a plugin and swapping a tool out entirely are similar amounts of yaml effort by that point. (Depending of course on your yaml fluency and familiarity with GitHub actions.)

Yeah! I have it set up in my website GitHub repo [0]

[0]: https://github.com/mattrighetti/mattrighetti.github.io/blob/...

I would caution anyone against using AsciiDoc. I really want to like AsciiDoc, but it has glaring issues for many years, that the developers seem to have no interest in fixing:

https://github.com/asciidoctor/asciidoctor/issues/1087

What other glaring issues can you think of up the top of your head that you caution against using asciidoc? The one GitHub issue linked seems like quite a nitpick.

Been using it for years, and I haven’t run into any issue thy would make me want to use anything else.

The format itself has several warts, like the ancestor list continuation syntax, or whether or not to add a backslash if you want a literal asterisk.

The implementation lacks checking, so for example if you have some text between square brackets, it will often just get dropped even if the contents is not valid as an attribute list.

AsciiDoctor now has an unambiguous way to insert an asterisk. The original Python implementation does not.

I was on my phone when I posted the above, so couldn't easily look up the exact way it's:

  {asterisk}

I'm not sure I would caution against AsciiDoc, but I stopped using it personally due to lack of support, and Markdown (of various flavors) being good enough for the use cases I cared about at the time.

There isn't much tooling. The community is small. The spec effort seems to have stagnated. AsciiDoctor and related projects seem to move at the speed of what Dan Allen decides is most worth his time.

That said, I've been wanting to do more long form writing, and AsciiDoc is lovely for that, so I may pick it up again for that.

At work I have about 500k words of AsciiDoctor source, and everyone (developers + document authors) is pleased with it.

That looks like a minor issue in GitHub's stylesheet, not really an AsciiDoctor problem.

> That looks like a minor issue in GitHub's stylesheet, not really an AsciiDoctor problem.

AsciiDoctor is adding p elements in places where it should not. GitHub could work around this error with CSS, but they have not done so, nor should they. It's a simple issue to fix, just emit the bare li elements.

https://github.com/jirutka/asciidoctor-html5s

The HTML alternate back-end fixes a lot of these issues and chooses semantic elements for a more modern age (while Asciidoctor is actively overhauling its output I believe).

The issue visually can be solved with CSS as-is (remove the padding or margin from li > p:only-child), but Microsoft GitHub treats its AsciiDoc rendering as a second-class citizen despite it objectively having more/better features for documentation than Markdown. The negligence becomes apparent when you look at the way GitHub syntax fork (“flavor”) handles admonitions; not only does it overload, overcomplicate, and ruin the semantics of the blockquote, but the CSS styling that makes them look nice was never ported to admonitions for reStructuredText and AsciiDoc despite these formats having the feature natively to the syntax (no fork required) since forever.

> Asciidoctor is actively overhauling its output I believe

It's been 9 years. That is not actively by any definition of the word.

Reply on news.ycombinator.com