Hacker News Reader

Comment by toastal | Hacker News Reader

If agents can generate text so easily, why would they be limited to Markdown instead of reStructuredText, AsciiDoc, or LaTeX which have rich features that help users understand text? I can understand developers refusing to adopt proper formats for documentation, but this seems odd for the bots. It doesn’t even generate the correct syntax block in Markdown using “bash” instead of “sh-session”.

View on HN

Markdown has the widest tool compatibility - GitHub renders it, so does VS Code and many other editors and file hosts.

I didn't know about sh-session, is that documented anywhere?

MS GitHub can not only render rST & AsciiDoc (albeit pretty poorly since they the CSS is bad), but it also is employing its own fork of Markdown that isn’t compatible with other forks. “Just Markdown”, like the base spec, is so feature poor that everyone has their own incompatible fork which don’t make it render properly.

console/shell-session/sh-session (parsers call them different names) are for shell sessions, terminal sessions. Bash syntax is for Bash scripts, & these aren’t scripts but something you run in your terminal session.

I'm not convinced Markdown's various flaws matter for the way I'm using it here.

I want a simple, widely-enough supported format for mixing text, code samples and images. The non-standard (because what even is a standard when Markdown is in play?) subset of Markdown I've picked for this project works fine for what I need in Showboat.

If it turns out to need more I can expand the format in the future - likely though embedding YAML in frontmatter but I could add sidecar JSON files instead if that proves to be more robust.

I dunno. I’ve written a bit of LaTeX but does it really shine in this context? IMO the real advantage it has is that it can allow the user to express more complicated intents than Markdown (weird phrasing—my natural instinct was to call LaTeX more precise than Markdown, but Markdown is pretty precise for describing the type of file that it is good at…).

Anyway LLMs don’t have underlying intent so maybe it is fine to just let them express what they can in Markdown?

I think its primarily because that is the most common formatting in every editor now? I could be wrong. Markdown has become the standard for README files for over a decade now.

Winning a popularity contest doesn’t mean it’s good. That is the worst part of about these things as they just generate the most common denominator type code/tooling while also repeating anti-patterns/mistakes like the bash vs. sh-session/console issue I pointed out. Garbage in has been so much garbage out unfortunately.

Never said it was good, just making an observation that Markdown is most likely to be available to render OOTB in more editors. I don't think Markdown is bad necessarily either. It's "good enough" for simple document.

Documentation isn’t as simple document. There are tons of rich elements missing from the spec specifically for documentation… which is why so many resort to adopting one of the many incompatible forks of Markdown to try to get features that were missing (but are a part of reStructuredText & AsciiDoc for instance). That has a real tradeoff since these forks are not going to be compatible & they aren’t going to be as well defined as the specs for these richer lightweight markup syntax choices.

Reply on news.ycombinator.com