5 ms·

AsciiDoc, Liquid and Jekyll

107 points by mattrighetti 4y ago

nicbou 4y ago
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.
ericholscher 4y ago
Great explanation! Useful and neat walkthrough of how it’s put together. Looks similar to https://sphinxcontribdatatemplates.readthedocs.io/en/latest/json.html https://sphinxcontribdatatemplates.readthedocs.io/en/latest/... 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.
danso 4y ago
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
amitu 4y ago
One of the reasons we built https://ftd.dev https://ftd.dev is this. Check out this example: https://fifthtry.github.io/bling/chat/ 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/ https://fifthtry.github.io/bling/quote/
- boundlessdreamz 4y ago
  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/ https://ftd.dev/docs/ doesn't link to the Installation, Getting started and Tutorial
  - amitu 4y ago
    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/ https://ftd.dev/expander/. And maybe join us on our Discord.
    - boundlessdreamz 4y ago
      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?
      - amitu 4y ago
        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.
2h 4y ago
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 https://github.com/asciidoctor/asciidoctor/issues/1087
- terrorOf 4y ago
  [dead]
- gouggoug 4y ago
  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.
  - matijsvzuijlen 4y ago
    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.
    - aidenn0 4y ago
      AsciiDoctor now has an unambiguous way to insert an asterisk. The original Python implementation does not.
      - aidenn0 4y ago
        I was on my phone when I posted the above, so couldn't easily look up the exact way it's: {asterisk}
  - recfab 4y ago
    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.
fwlr 4y ago
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.
sandGorgon 4y ago
i did NOT know jekyll supported asciidoc. does this work with Github Pages workflow ?
- timwis 4y ago
  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.
  - WorldMaker 4y ago
    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.
    - timwis 4y ago
      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.
      - WorldMaker 4y ago
        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.)
- mattrighetti 4y ago
  Yeah! I have it set up in my website GitHub repo [0] [0]: https://github.com/mattrighetti/mattrighetti.github.io/blob/master/.github/workflows/ci.yml https://github.com/mattrighetti/mattrighetti.github.io/blob/...
Annatar 4y ago
[dead]
pietroppeter 4y ago
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 https://github.com/nimib-org/nimibex/issues/11 [1]: https://github.com/pietroppeter/nimib https://github.com/pietroppeter/nimib

107 points by mattrighetti 4y ago

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.

ericholscher 4y ago

Great explanation! Useful and neat walkthrough of how it’s put together. Looks similar to https://sphinxcontribdatatemplates.readthedocs.io/en/latest/json.html https://sphinxcontribdatatemplates.readthedocs.io/en/latest/... 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.

danso 4y ago

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

amitu 4y ago

One of the reasons we built https://ftd.dev https://ftd.dev is this. Check out this example: https://fifthtry.github.io/bling/chat/ 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/ https://fifthtry.github.io/bling/quote/

boundlessdreamz 4y ago
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/ https://ftd.dev/docs/ doesn't link to the Installation, Getting started and Tutorial
- amitu 4y ago
  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/ https://ftd.dev/expander/. And maybe join us on our Discord.
  - boundlessdreamz 4y ago
    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?
    - amitu 4y ago
      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.

2h 4y ago

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 https://github.com/asciidoctor/asciidoctor/issues/1087

terrorOf 4y ago
[dead]
gouggoug 4y ago
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.
- matijsvzuijlen 4y ago
  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.
  - aidenn0 4y ago
    AsciiDoctor now has an unambiguous way to insert an asterisk. The original Python implementation does not.
    - aidenn0 4y ago
      I was on my phone when I posted the above, so couldn't easily look up the exact way it's: {asterisk}
- recfab 4y ago
  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.

fwlr 4y ago

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.

sandGorgon 4y ago

i did NOT know jekyll supported asciidoc. does this work with Github Pages workflow ?

timwis 4y ago
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.
- WorldMaker 4y ago
  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.
  - timwis 4y ago
    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.
    - WorldMaker 4y ago
      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.)
mattrighetti 4y ago
Yeah! I have it set up in my website GitHub repo [0] [0]: https://github.com/mattrighetti/mattrighetti.github.io/blob/master/.github/workflows/ci.yml https://github.com/mattrighetti/mattrighetti.github.io/blob/...

Annatar 4y ago

[dead]

pietroppeter 4y ago

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 https://github.com/nimib-org/nimibex/issues/11 [1]: https://github.com/pietroppeter/nimib https://github.com/pietroppeter/nimib