News for hackers. Stuff that matters.
Re:AsciiDoc, Liquid and Jekyll by 2h on Thursday February 23, 2023 @09:10PM (#34919822)
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

Re:AsciiDoc, Liquid and Jekyll by gouggoug on Friday February 24, 2023 @02:01AM (#34921729)
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.

Re:AsciiDoc, Liquid and Jekyll by matijsvzuijlen on Friday February 24, 2023 @05:37AM (#34923111)
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.

Re:AsciiDoc, Liquid and Jekyll by aidenn0 on Friday February 24, 2023 @08:57AM (#34924520)
AsciiDoctor now has an unambiguous way to insert an asterisk. The original Python implementation does not.
Re:AsciiDoc, Liquid and Jekyll by aidenn0 on Friday February 24, 2023 @11:26AM (#34926235)
I was on my phone when I posted the above, so couldn't easily look up the exact way it's:

  {asterisk}
Re:AsciiDoc, Liquid and Jekyll by recfab on Friday February 24, 2023 @06:39PM (#34931840)
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.

Re:AsciiDoc, Liquid and Jekyll by Symbiote on Friday February 24, 2023 @07:10AM (#34923686)
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.

Re:AsciiDoc, Liquid and Jekyll by 2h on Friday February 24, 2023 @05:51PM (#34931309)
> 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.

Re:AsciiDoc, Liquid and Jekyll by toastal on Friday February 24, 2023 @08:02AM (#34924035)
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.

Re:AsciiDoc, Liquid and Jekyll by 2h on Friday February 24, 2023 @05:53PM (#34931331)
> Asciidoctor is actively overhauling its output I believe

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