[HN Gopher] Markdown Is Holding You Back
___________________________________________________________________
Markdown Is Holding You Back
Author : zdw
Score : 39 points
Date : 2025-11-22 20:03 UTC (2 hours ago)
(HTM) web link (newsletter.bphogan.com)
(TXT) w3m dump (newsletter.bphogan.com)
| timpera wrote:
| It's interesting to see how Markdown keeps getting more and more
| use, and even native Windows Notepad support!
| philipwhiuk wrote:
| > If you're writing a quick README or a short-lived doc, Markdown
| is fine. It's fast, approachable, and does the job. If you're
| building a developer documentation site that needs some
| structure, reStructuredText or AsciiDoc are better choices.
|
| This is dumb. If I'm writing developer documentation I'm not
| writing it for a machine. And if the aim here is to expose it to
| a LLM, then the LLM needs to get smarter about semantics, not
| force us back to formats that are more technically complex to
| write and maintain in order to re-create 'the semantic web' - a
| flawed concept that has failed to catch on.
|
| If the LLM needs context on content that humans don't need, the
| LLM needs fixing, not the content.
|
| > With Markdown as your source, you can't easily go to another
| format.
|
| File->Print->PDF.
|
| Was that hard? (I admit it's still bizarre that Chrome puts 'Save
| As PDF' under Print).
|
| (Apparently you can also go via LaTeX if you love a CLI)
| dragonwriter wrote:
| > If I'm writing developer documentation I'm not writing it for
| a machine. And if the aim here is to expose it to a LLM, then
| the LLM needs to get smarter about semantics, not force us back
| to formats that are more technically complex to write and
| maintain
|
| AsciiDoc is much better than Markdown for docs _intended for
| humans_ that are more than short, README type of documents. Any
| advantage it has for documents intended for LLMs is a side
| effect of that.
| zihotki wrote:
| Many consider AsciiDoc being too complex.
| khaledh wrote:
| Markdown won. Simplicity always wins. Markdown is now the de
| facto documentation format, for better or for worse.
| jimmar wrote:
| Markdown is the minimum viable product. It's easy to learn and
| still readable if not rendered in an alternate format. It's
| great.
|
| For making PDFs, I've recently moved from AsciiDoc to Typst. I
| couldn't find a good way to get AsciiDoc to make accessible PDFs,
| and I found myself struggling to control the output. Typst solves
| all of AsciiDoc's problems for me.
|
| But in the end, no markup language will make you write better.
| It's kind of like saying that ballpoint pens are limiting your
| writing, so you should switch to mechanical pencils.
| undeveloper wrote:
| typst looks interesting -- but how are you writing it? from
| what I looked at, it looks like theres an official web editor
| and a vscode plugin with limited support. this feels pretty
| limited, as someone who came in expecting something like
| obsidian.
| TRiG_Ireland wrote:
| I'm not aware of any limitations in the Tinymist plugin.
|
| And you can just write it in the plain text editor of your
| choice, and keep an eye on the PDF with typst watch.
| nicoburns wrote:
| This article doesnt consider Typst, which IMO ought to be the
| first port of call if Markdown isnt sufficient for your needs.
| perlgeek wrote:
| I've used typst for generating PDFs before, how good is its
| HTML output?
| undeveloper wrote:
| it looks like typst's html output is under construction [1].
|
| 1: https://typst.app/docs/reference/html/
| neoCrimeLabs wrote:
| > Markdown Lacks the Structure You Need
|
| I feel like this article makes a lot of valid observations, but
| then wraps them with a false dilemma.
|
| If it had tried to convince the reader of understanding what
| formatting needs are required before choosing a format, I would
| have entirely agreed with it.
|
| Instead I'm left feeling mildly offended, and disagree with it.
| dschuessler wrote:
| You can include arbitrary HTML tags in Markdown at any place you
| need them.[0] I am not aware of any Markdown tooling that does
| not support this.
|
| So, no, Markdown is not holding me back. It is perfectly capable
| of what the author claims it isn't.
|
| [0]: https://daringfireball.net/projects/markdown/syntax#html
| henrebotha wrote:
| There are real limitations to this: You can't arbitrarily mix
| and match HTML and Markdown. As soon as you introduce an HTML
| block, you're locked out of Markdown syntax.
|
| AsciiDoc lets you mix and match however you want. Or, put
| differently: AsciiDoc's superiority over Markdown extends even
| to being better at shelling out to HTML.
| tefkah wrote:
| mdx does tho. you could just not define any components, then
| you can nest markdown inside html no problem
| johnathandos wrote:
| It's good to spread awareness (or just remind folks) that
| alternatives to Markdown exist. The right tool for the job
| depends on your circumstances. If I were scaling a docset for a
| team of contributors primarily consisting of technical writers,
| .adoc or .rst would be my preference. If I were scaling internal
| docs-as-code infra for software engineers, I'd use Markdown.
| prmoustache wrote:
| The author seems to forget that markdown is just an extension of
| html. If markdown doesn't provide something that html does, you
| just write it in html and it will be rendered correctly.
|
| I'd also argue that the limitations of markdown allow me to focus
| on actual content and less on the presentation. I have little use
| of all the features of a markup language if I can't remember how
| to use them.
| dardeaup wrote:
| Wow! TIL!
| nrhrjrjrjtntbt wrote:
| It is not features but structure and undetstanding that is
| missing.
|
| That said I am not sure what the solution is to that since your
| docs may need structure my docs dont need. Therefore you cant
| solve the "semantic" outside of a "namespace" of what you agree
| in your organization.
|
| E.g. you may decide architecture diagrams are in Mermaid but
| that is by no means a stanfard and my org uses embeded svg.
|
| So to go full circle... you are right just use HTML. After all
| it's semantic isn't it ;-)
| dardeaup wrote:
| This is a timely topic for me. I'm just beginning the writing of
| a technical book. I plan to target epub/mobi. My research thus
| far has pointed to markdown -> html -> epub/mobi. If you were
| going to write a technical ebook would you use markdown or an
| alternative?
| codybontecou wrote:
| What about markdown do you feel limits you in your writing
| process?
|
| The beauty of markdown is that it's standardized. If you find
| your self midway through the book and feel a need to change
| formats, it's easy enough to parse and reformat.
| dardeaup wrote:
| Nothing! I was asking from the point of you that you don't
| know what you don't know.
| macintux wrote:
| You might look at DocBook. I haven't used it in ~25 years, and
| then only for short documents, and it is XML hence quite
| verbose.
|
| But it's explicitly targeted at technical documentation. If
| nothing else, searching for DocBook alternatives might give you
| some ideas.
| WA wrote:
| You need:
|
| - table of contents
|
| - automatic chapter and section numbering
|
| - cross references and automatic tracking of figures, tables
| etc.
|
| - different styles besides blockquotes such as info sections,
| warnings, tips
|
| Imho, cross-referencing chapters, pages, figures, tables and
| the lack thereof in Markdown is the first and most important
| thing to check how you would like this to be solved.
| nathias wrote:
| is this a poignant satire about programmers?
| Animats wrote:
| The paper makes the point that people keep extending Markdown,
| badly and incompatibly.
| autogn0me wrote:
| I would like to point out that asciidork provides ability to get
| AST representation of asciidoc. It's very nice package. Not the
| author but have used it.
|
| https://github.com/jaredh159/asciidork
| sroerick wrote:
| Org is pretty good.
| gbanfalvi wrote:
| The other options look like garbage tho
| jrm4 wrote:
| Feels like a great argument...for, I don't know, a bunch of
| moderately technical high-schoolers who were somehow raised on
| markdown instead of Microsoft Word and want more power?
|
| No, seriously, who is this for?
___________________________________________________________________
(page generated 2025-11-22 23:00 UTC)