[HN Gopher] Markdown is holding you back
___________________________________________________________________
Markdown is holding you back
Author : zdw
Score : 204 points
Date : 2025-11-22 20:03 UTC (1 days 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.
| doublebind wrote:
| The history of tech is full of "X is better than Y. We should
| use X", only for X to die. It doesn't matter what is better;
| it matters what is used. For better or worse, Markdown is
| what is used.
| abathur wrote:
| This is the kind of dismissive sneer the HN guidelines advise
| against.
|
| You can write dev docs for humans and still want machine
| readability (without caring about whether some LLM can make
| sense of the docs).
|
| Machine readability is how you repurpose your own documentation
| in different contexts. If your documentation it isn't machine
| readable it might as well be in a .doc(x) file.
| 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.
| addaon wrote:
| > I'm not aware of any limitations in the Tinymist plugin.
|
| I looked into this a while ago, and couldn't find a
| workflow I could live with. Have things improved? What's
| the workflow like for working on an image in, say,
| OmniGraffle to include in the document? Does text search in
| embedded PDFs work these days? LinkBack so I can edit the
| images easily inline?
| MillironX wrote:
| I've started experimenting with Typst for a few documents,
| and here's my stack:
|
| - Zed editor with Typst plugin
|
| - Tinymist LSP settings turned on to render on save in Zed,
| see https://code.millironx.com/millironx/nix-
| dotfiles/src/commit...
|
| - Okular open to the output document. Okular refreshes the
| document when changed on disk.
|
| It's not as polished as say, LaTeX Workshop in VSCode, but it
| gets the job done.
| tcfhgj wrote:
| you can just install the typst compiler yourself and let it
| run in the cli typst watch file.typ //
| compiles automatically on file changes
| euroderf wrote:
| Typst really does look good. Can one get an editor with live
| PDF preview ? It would be useful mainly for immediate
| feedback on markup correctness; then an HTML output ought to
| be "close enough".
| eigenspace wrote:
| You can write Typst in any editor you like, and the Typst
| compiler is FOSS available.
|
| I write Typst code from emacs personally
| hobofan wrote:
| Yes, the author conflates two different use-cases.
|
| Markdown is the answer for "how do we enable people that don't
| want to invest a lot of time into producing content that's
| somewhat better than plain text?".
|
| It's not trying to solve the problem of "how do we enable
| people that are willing to invest time into learning to produce
| the best possible and most structured content possible?" and I
| doubt that there will be language that will serve both of those
| use-cases very well.
| swiftcoder wrote:
| One downside here is that as more and more tools focus on the
| first use-case, people start using those tools by default
| when they actually fall into the second use-case. And there's
| often a pretty high barrier to switching once you've produced
| a lot of content, so a bunch of projects are using the wrong
| one long-term.
| pas wrote:
| Arguably having a ton of hard to write, hard to maintain
| docs is waaay worse than Markdown that gets attention in
| PRs (MRs).
|
| Especially that the things in the article seem irrelevant
| compared to actually adding and handling non-text content
| IMHO. (Mermaid diagrams for example.)
|
| Sure a validator would be nice, but that's why a simple
| preview is available in most collaboration platforms.
| mangecoeur wrote:
| The problem in practice is that quickly one merges into the
| other. You start with a markdown readme, then you have
| markdown documentation for a small project. But then one day
| you need full documentation for your project with cross
| links, translations, accessibility. With Markdown you end up
| bolting these things on and each flavor does it a bit
| differently.
|
| Perhaps some of the blame can be laid with the poor UX of
| technically superior systems. restructuredtext (apart from
| the terrible name) built with Spinx can do impressive things
| but becomes a huge pain to configure. All the XML-based tools
| like DocBook are very complete but try to get started
| actually building something - apart from having to author
| them in XML (which is already a kind of punishment), then you
| have to figure out XSLT stylesheets, 2000s-era design Java
| tools for processing them. And just look at the DocBook
| landing page! AsciiDoc has improved their onboarding recently
| but does have the issue of feeling like a markdown-ish
| alternative that's just a bit different for no clear reason.
| thayne wrote:
| > does have the issue of feeling like a markdown-ish
| alternative that's just a bit different for no clear
| reason.
|
| Asciidoc is older than markdown. Kind of hard to be design
| something to be the same as something that isn't invented
| yet.
| eproxus wrote:
| Djot is another interesting alternative that tries to make
| Markdown more parsable and coherent:
| https://github.com/jgm/djot#rationale
| xigoi wrote:
| Unfortunately it doesn't seem to have a formal spec.
| thayne wrote:
| I hadn't heard of that before but it looks like it solves a
| lot of my complaints about markdown.
|
| I hope it gains more momentum.
| mettamage wrote:
| LaTeX made me write better because of commenting above every
| paragraph.
| f1shy wrote:
| What LaTeX helped me with was in taking more care of the
| content than the form/appearance.
| 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/
| tefkah wrote:
| typst is great, but there are many many steps between "markdown
| isn't sufficient" and reaching for typst.
|
| 1. typst only really has pdf output at the moment 2. so much
| less tooling available (linters, site builders, converters etc)
| 3. much less of a markup format, extremely tightly coupled to a
| specific tool (typst compiler)
|
| again, love typst, but it has (atm) so much fewer applications
| tcfhgj wrote:
| Typst has already experimental HTML output and it
| specifically has a markup mode (default mode).
|
| Conceptually Typst is a superset of a Markdown with a
| slightly different syntax (e.g. = instead of # for headers)
| lenkite wrote:
| I guess we need to wait until Typst is natively supported by
| Github.
| WhyNotHugo wrote:
| I think Typst looks really interesting for some scenarios, but
| inadequate for others.
|
| I like RST a lot for Python documentation, because of all the
| directives for types, admonitions, and lots of domain-specific
| stuff. I wouldn't use RST if I'm writing a book, or a research
| paper.
|
| In the same way, Typst looks like a great candidate for those
| last examples, but is likely unsuitable for documenting a
| library written in Python.
| tcfhgj wrote:
| > In the same way, Typst looks like a great candidate for
| those last examples, but is likely unsuitable for documenting
| a library written in Python.
|
| why though?
|
| Would you categorize Markdown as unsuitable as well? if so,
| why?
| 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
| vidarh wrote:
| While that's true, I'd take Markdown + extensions to allow
| inline HTML or custom tags over AsciiDoc any day, even at the
| cost of losing some compatibility - converting that to plain
| Markdown is usually easy enough.
| judahmeek wrote:
| What are the trade-offs with AsciiDoc that would make you
| choose Markdown instead?
| catlifeonmars wrote:
| Not op, but markdown is much more likely to render well
| in different contexts, without post processing. My editor
| understands markdown, GitHub understands markdown, the
| link preview renderer in <random collaborative tool>
| understands markdown. It's the lowest common denominator
| henrebotha wrote:
| That's true, and it's why we're all using it. But those
| different renderers all support different ill-defined
| interpretations of Markdown. You can forget about all of
| them accepting raw HTML.
| youngtaff wrote:
| O'Reilly's authoring system used to use AsciiDoc (may still
| do), made me hate AsciiDoc
| throwaway150 wrote:
| > You can include arbitrary HTML tags in Markdown at any place
| you need them.
|
| That is well known and I am sure the author is aware of it. The
| problem they are describing is not whether HTML is technically
| allowed inside Markdown. It's that when you are writing
| Markdown, you are writing Markdown, not HTML, and that comes
| with some problems.
|
| > It is perfectly capable of what the author claims it isn't.
|
| In theory, yes. In practice, using Markdown becomes much less
| appealing once you start dropping raw HTML all over the place.
| The whole point of choosing Markdown is that you do not want to
| spend your time typing <p>, <a>, <li> and the rest. You want to
| write in Markdown, with only occasional HTML when absolutely
| necessary.
|
| That is exactly where the author's complaints become relevant.
| If the solution to Markdown's limitations is routinely
| switching to HTML, then the argument becomes circular. If you
| are expected to write HTML to address the author's complaints,
| why bother with Markdown at all? If the answer is just "write
| HTML", then you may as well skip Markdown in the first place.
| vorpalhex wrote:
| Most markdown engines allow short tags to stand in for html,
| so for frequent features you can just use a short tag.
|
| Alternatively you can extend markdown. I wrote a simple text
| based game engine that was markdown based but I needed some
| arbitrary additions appropriate for a game.. so I just added
| a few elements.
| hysan wrote:
| The author addresses this too. Once you start down this
| path, you go down the road of non-standardization which
| means losing portability, etc. I don't see how this is a
| point against the author?
| bccdee wrote:
| None of the author's other suggestions are portable
| either. So what if pandoc markdown is only understood by
| pandoc's tooling? DocBook is only understood by DocBook
| tooling. The difference is that pandoc markdown is
| already 95% similar to every other flavour of markdown,
| so migrating to a new system (if necessary) would be
| relatively simple. Also, the difference is that XML is a
| pain to write and I'm not sure semantic tags matter all
| that much.
| hysan wrote:
| Maybe portable isn't the right word. I read portable as
| meaning the format's semantics are consistent across
| platforms. The way I read the author's complaint was that
| once you start tacking on extensions to markdown, you run
| into the problem of seeing if other markdown platforms
| being able to support your variant of markdown. Hence the
| part about CommonMark vs GitHub-Flavored Markdown vs etc.
| Having actually run into this before when working on
| CMSes in the past, I get why the author sees this as a
| problem. I don't think everyone will agree with the
| authors viewpoint, but I just happened to think that this
| thread is completely missing the point that the author is
| trying to make.
| bccdee wrote:
| > I read portable as meaning the format's semantics are
| consistent across platforms.
|
| By that definition, a format which is only implemented on
| one platform is 100% consistent. I agree Markdown is
| uniquely fragmented, but it's also uniquely widespread.
|
| Markdown is an extensible core for writing platform-
| specific languages. I think comparing markdown in general
| to something like DocBook is comparing apples to oranges.
| Instead compare (e.g.) Pandoc's specific markdown variant
| to DocBook.
| hysan wrote:
| > I think comparing markdown in general to something like
| DocBook is comparing apples to oranges.
|
| Hmm let me rephrase the issue I have with the comments in
| this thread. If your position is that markdown doesn't
| belong in the same category as the others, then yeah, I
| agree. But I also think that's basically rejecting the
| premise of the article and there isn't a discussion to be
| had. If you disagree with the core premise, then it
| doesn't matter what is said, there's no discussion to be
| had.
|
| However, the original parent comment is stating that the
| author's assertion is false because you can extend
| markdown. I don't see how that logic doesn't run into the
| semantics and "portability" problems that the author is
| writing about.
| euroderf wrote:
| > why bother with Markdown at all?
|
| Maybe it's an 80-20 thang ? Your page is mostly MD that's
| easy on the eyes, but with "shelling out" for semantics like
| section or aside ?
| Terretta wrote:
| > _The whole point of choosing Markdown is that you do not
| want to spend your time typing <p>, <a>, <li> and the rest.
| You want to write in Markdown, with only occasional HTML when
| absolutely necessary._
|
| Why is that a problem?
|
| > _If the solution to Markdown 's limitations is routinely
| switching to HTML, then..._
|
| Why would you do that, instead of only switching if you had
| to?
|
| Why would the alternative be "just HTML" and write all the
| nonsense you said one doesn't have to?
| hizanberg wrote:
| I also put interactive components in my markdown docs, I'm only
| using Markdown for content now.
| littlestymaar wrote:
| > I am not aware of any Markdown tooling that does not support
| this.
|
| Reddit surely doesn't, and I'd be very surprised if github did.
|
| In practice, in any place you want untrusted users writing
| markdown stuff for formatting, you cannot allow arbitrary HTML
| for security reasons.
| gen2brain wrote:
| I often use <img> with "width" on GitHub, so that I do not
| have the scrollbars on the main page, and one can click on
| the image to see the original size. It is ugly, but what is
| the alternative in Markdown? Several images instead of one?
| thayne wrote:
| Github has a very limited subset of html that is allowed.
|
| Slack doesn't allow html (although it also doesn't allow all
| markdown).
|
| If you are converting to something other than html, such as a
| manpage, using html tags generally doesn't work.
| a3w wrote:
| I also used pandoc and markdown, and never bothered going back
| to ascidoc, full HTML, or latex.
|
| Footnotes are the only not always included extension to
| mmarkdown I need for slides or argument flows that are not
| killed by sidenotes, and some sites and toolings support that
| in markdown.
|
| Even table of contents is not a problem, so what else is left?
| Formula setting? Buttons for UI vs function? Buttons plus
| Inline JS for step by step state modification?
|
| I am not programming, I want text and something to be easily
| pasted into Word-like rich text, which seems to be the default
| text editor for emails for 90% of the population.
| 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 ;-)
| locknitpicker wrote:
| > It is not features but structure and undetstanding that is
| missing.
|
| I don't think this belief is valid. The whole purpose of
| markdown is to serve as a easy to read format that is
| publishable as plaintext and has minimalist standardized
| formatting and styling. It's something for humans to read and
| write without requiring specialized tooling.
|
| For this purpose, "structure" is neither a requirement nor a
| valid concern.
|
| > E.g. you may decide architecture diagrams are in Mermaid
| but that is by no means a stanfard and my org uses embeded
| svg.
|
| That's a trait of your organization, not Markdown. Mermaid is
| ubiquitous, and used extensively in virtually everywhere in
| the internet. If you chose not use it that's a personal call
| you're making, and not related to Markdown at all.
| mycall wrote:
| Markdown can be used where HTML is not available, like in AI
| chatbots for omnichannel mediums (e.g. WhatsApp).
| 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.
| tasuki wrote:
| > The beauty of markdown is that it's standardized.
|
| It isn't standardized. And that's the main problem.
| 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.
| dardeaup wrote:
| Thanks!
| 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.
| ifh-hn wrote:
| Pandoc and pandoc-crossref. Or simply use quarto.
| dardeaup wrote:
| Thanks!
| ldng wrote:
| How about markdown -> PDF (with Typst) -> epub/mobi ?
| dardeaup wrote:
| Thanks! I'll look into that as an option.
| tedggh wrote:
| My stack is Markdown-Pandora-MiKTeX-PDF with Eisvogel for
| technical documentation and it works great for my use case.
| Eisvogel has a "book" typeset.
| autogn0me wrote:
| Asciidoc
| meonkeys wrote:
| I wouldn't use Markdown for that.
|
| You're right to start with your requirements. Try to get
| detailed, like the list @WA wrote out, then match it up with
| appropriate tech.
|
| I wrote a technical book and I also wanted multiple decent-
| looking outputs. In my case: HTML, EPUB/mobi, screen and print
| PDFs. I was struggling with Markdown+pandoc+custom
| scripts/styles, so I switched to Asciidoc. I wrote about that
| process here: https://adammonsen.com/post/2122/
|
| Most of the formats came out satisfactory, but there were some
| gotchas. https://github.com/meonkeys/shb/#%EF%B8%8F-book-
| formats lists some, and
| https://github.com/meonkeys/shb/blob/main/issues.adoc has more.
| Translating from English to German went OK with asciidoc, but
| it might have been better with docbook and standard translation
| tools for working with .po files.
|
| Here are two examples where the author used Markdown and the
| result was beautiful and successful (although layout for
| printed editions were done with extra/other tooling):
| http://gameprogrammingpatterns.com ,
| http://www.craftinginterpreters.com . I'm curious if Bob
| would/will use Markdown for his next book. My process is
| different than Bob's... I didn't need literate code and I
| didn't want to do _any_ layout/pre/post-processing, even for
| print. Asciidoctor worked for this, although there were some
| compromises (see my links above). Print-ready layout is a lot
| of work, however you do it.
|
| Is this your first book? Do you have a publisher? Will it be
| printed on paper? Do you have a developmental editor /
| proofreader / etc? Do you have a plan for what you'll do after
| you publish e.g. talks/promos/tour?
|
| Contact me if you want to chat. I'm happy to share my war
| stories. And good luck!
| nathias wrote:
| is this a poignant satire about programmers?
| hadlock wrote:
| I went to look up and see if this guy was in his early to mid
| 20s when I got to this point
|
| > That <Command> tag isn't Markdown at all; it's a React
| component.
|
| Turns out he's in his 40s, so he lived through ms word, front
| page and the JavaScript wars; this is almost certainly satire
| tefkah wrote:
| i think that specific turn off phrase is more of an indicator
| of llm usage then age imo
| 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.
| dandersch wrote:
| org-mode could have had a chance if they had provided tooling
| outside the emacs ecosystem. But now LLMs have chosen markdown,
| so it's destined to forever remain an obscurity.
| 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?
| amitav1 wrote:
| I use Org-mode w/ GNU Emacs for all of my blogging(shameless
| plug: amitav.net). I like Org-mode because it's easy enough to
| write, looks nice enough, can be exported in quite a few formats,
| and the code block handling is _chef 's kiss_. It supports quite
| a few languages and has a feature I've seen in no other editor
| before, where you can chain together code from different code
| blocks, and evaluate it, _inside of the document itself_. I tried
| out a few different blogging platforms with first class Org-mode
| support ([Blorgit](https://orgmode.org/worg/blorgit.html) and
| [lazyblorg](https://karl-voit.at/tags/lazyblorg/)), but they
| ended up taking up a bunch of time to set up, so my current
| process is just manually exporting my Org files to HTML, then
| using rsync to send them over to my server, then I have a Ruby
| script which just appends an index to the bottom of each file and
| serves it. I find Org-mode a lot more expressive and natural to
| write than my previous blogs which were in Markdown.
| Quothling wrote:
| If org-mode wasn't so tied to emacs I suspect it would be the
| "default" text formatting syntax for a lot more people.
| grep_name wrote:
| Hmm, have you checked out Ox-Hugo? It's a pretty great system
| for exporting to a hugo blog from a single org file. But then I
| guess your blog would have to be hugo-based
| myaccountonhn wrote:
| Org mode is unfortunately really tied to Emacs and so
| featureful that I imagine it's hard to port elsewhere. Maybe if
| an LSP gets built for it we'd start see it elsewhere.
| jppope wrote:
| Been constantly using it for ~10 years and it works great. I read
| the article and its not incorrect, but its also kind of arguing
| that markdown users have problems that they themselves would say
| they don't have. If you need something else, use something else.
| With all that said, great title, they convinced me to waste ~3-5
| min digging in.
| nickledave wrote:
| Really weird to see this person mention MyST as a form of
| Markdown, and then go on to talk about reStructuredText as their
| first example of a markup language "that gives you more control
| over structure than ... markdown".
|
| The whole point of MyST is to provide a markdown-like alternative
| to rST. It literally has directives, roles, structural semantics,
| etc. It just doesn't have the unlearnable syntax of rST and the
| so-called governance of docutils (the de facto rST parser) (see
| e.g. discussion on https://github.com/sphinx-
| doc/sphinx/issues/8039 and linking issues)
| ifh-hn wrote:
| I don't agree with this article. I mean sure there's no standard
| but there is pandoc, and quarto, both of which fill the gaps this
| article claims. And I also don't write content for LLMs so I
| don't care whether they can understand it.
| 0xbadcafebee wrote:
| Markdown is the McDonalds of writing
| random3 wrote:
| This is, personally, a controversial topic- I can take both sides
| of the debate in my head. I use markdown intensely and feel the
| deficiencies deeply, but wasn't able to see how there are real
| alternatives given the ecosystem (e.g. Obsidian).
|
| I do think things are ripe for changes in this space.
| somat wrote:
| The whole point of markdown, really it's whole value preposition
| is that it has nice looking plain text. And don't get me wrong
| that is a hell of a value to many people, myself included. Yes it
| is a terrible markup language, And I would encourage anyone doing
| serious document work to use a language that provides better
| semantic structure. But I would also argue that all projects that
| try to add these structures to markdown are missing the point and
| destroying it by making the plain text ugly.
| alganet wrote:
| > Markdown Lacks the Structure You Need
|
| The problem is, I always need more structure. Give me some YAML
| and time and I'll make hell (not a metaphor, I'll concoct hell
| itself on it).
|
| Markdown keeps me honest.
| starkparker wrote:
| By suggesting DITA as a valid alternative to Markdown, for any
| use, this has so completely lost the plot that it blows up
| whatever credibility Brian might have on the subject. It's
| disappointing, because I know of Brian and otherwise respect his
| work.
|
| Short of writing in raw Postscript, I can't think of a more
| completely different set of strengths, audiences, and
| applications. I had to get to a company with more than 5,000
| employees, 20 product lines, and 5 required i18n locales to find
| one where the overhead, god-awful ergonomics, and half-broken
| tooling of DITA were appropriate for the scale of the work _and
| also_ resourced enough to paper over every miserable facet of its
| implementation.
|
| If you're using Markdown today _at all_ for a task, DITA isn't
| appropriate for it. If DITA was appropriate for the task, you
| never would've picked Markdown to accomplish it to begin with.
| Don't waste your time with it either way.
| euroderf wrote:
| Ya don't often see this kind of vocal disappointment directed
| at DITA.
|
| Can you provide more info about how exactly DITA+tooling fell
| on its face ?
| getnormality wrote:
| Wow, I've never heard of DITA, so I was totally unprepared for
| how funny this was going to be.
|
| "Markdown is not great for writing complex documentation. Why
| not use XML instead?"
| adamretter wrote:
| I'm really surprised I didn't see any mention of LwDITA yet. It
| can be expressed in XML, HTML, or Markdown. For us it is the
| sweet spot between the too little provided by Markdown, and the
| too much provided by DITA or DocBook
| tedggh wrote:
| Certainly not holding me back. I can go from crappy notes on a
| notepad to a polished and branded PDF release including TOC,
| tables, images and formulas, info/warning boxes, lists, code
| snippets with syntax highlighting, header/footer, etc in
| literally minutes. What else do you need?
| Mikhail_Edoshin wrote:
| Example: I want to explain the role of various files in the
| development directory. I start with a couple files; then I
| describe a command that creates a third file. And then I do
| this several more times, filling up the directory.
|
| It wold be nice to show the starting list of files, a command,
| and the resulting list of files. It would also be nice to maybe
| color-code source and target files for each step, both in the
| command and in the listing. It may also help to typographically
| distinquish base files that are written by hand and generated
| ones. A few pictograms to tell apart files and directories
| would also be useful.
|
| And it would be nice to somehow keep this a single process so
| that a command references a source state and produces the
| target state and the list of files is computed automatically.
|
| (Doing this right now with XML and XSLT, targeting PDF via XSL-
| FO. Drew pictograms in SVG right in the XSLT. Haven't got to
| the automatic part yet, just got an idea that this is a natural
| way to go.)
| josephg wrote:
| What else?
|
| I want figures. I want linked references. I want custom styling
| for images, and for blocks of text (eg warnings, notes, etc). I
| want a TOC and numbered chapters and sections. Sometimes I want
| a bibliography. Or a table generated from data within a JSON
| file.
|
| You don't need this stuff for a readme file. But IMO markdown
| isn't powerful enough for blog posts, documentation or longer
| form content.
| sallveburrpi wrote:
| I use docusaurus as markdown renderer which adds most of what
| you need. Mermaid.js for figures. Never needed a data table
| from JSON but would be easy to add a custom component for
| this.
|
| So yes for me markdown is definitely powerful enough for
| blogging and complex technical writing - has been for the
| last 6 years- with a few small extensions and I'll eat my hat
| before I use anything xml based or reinvent html...
| MrWB wrote:
| Have you looked at Quarto?
| twelvedogs wrote:
| I've never struck any off these problems, and in order to use the
| tools he suggests I'd have to switch out the systems I use that
| just support markdown
|
| I sometimes make documents that require more complex formatting,
| so I use html after 20 minutes fucking around in word and getting
| angry
|
| Tried and trusted process
| novemp wrote:
| > Your content isn't just for human readers. Machines use it too.
| Your content gets indexed by search engines, and parsed by LLMs,
| and those things parse the well-formed HTML your systems publish.
|
| Sounds like I need to start using Markdown!
| procaryote wrote:
| I use markdown because it's easy to read without rendering. All
| of the alternatives in the article seem worse
|
| If I wanted more structure, I'd just write html; or mix html into
| the markdown.
|
| Pandoc lets me do things like generate libreoffice or microsoft
| word documents from the markdown, using a reference document for
| styling of headings etc. This also gives me good enough control
| to generate OK looking pdfs. It's not LaTeX levels of control,
| but it's much easier
|
| I don't want to do extra work to hypothetically make things
| easier for an LLM.
| stonecharioteer wrote:
| I love RestructuredText. My blog used to be on RST, because I
| hate markdown. I moved to Hugo and Markdown because I wanted to
| put out content, not fight the weird system that was Sphinx (My
| RST blog was running on it), and ablog, the Sphinx blogging
| framework didn't work with Furo, my favourite theme. I just use
| Hugo, and I use Claude to fix the css.
| gethly wrote:
| Markdown is meant for less technically skilled users and cases
| where you just want to type something with a bit of structure and
| not bother with full html. Making universal claims of it being
| bad ignores the proper user cases for it. Author can write HTML
| as much as he wants, but don't tell the world that MD is bad.
| cube00 wrote:
| We found Markdown with directives[1] worked well enough for our
| use case.
|
| [1]: https://talk.commonmark.org/t/generic-directives-plugins-
| syn...
| timClicks wrote:
| Asciidoc corresponds directly to DocBook XML. They're two formats
| with exactly the same semantics.
| isodev wrote:
| I love this post. While I don't mind markdown for quick notes
| which require basic formatting (headlines, bold, maybe a link),
| time and time again, I've found myself having to build parsing
| libraries and scripts for specific use cases just so the content
| can be interpreted correctly.
|
| Take for example my blog, which I've had since 2016. It has been
| rebuilt into various systems over time and every time I had to
| migrate, there was a manual step of going over all posts and
| making sure they're displayed and interpreted correctly. In my
| last and current iteration, I've designed the system so that
| content is also stored with some hierarchical information (from
| html) like <section>, <article>, <address> etc, only applying
| styling to it when rendered.
|
| I don't think we should stop using Markdown, but when something
| requires more than 200 lines of introductory text, more
| semantically enabled source feels necessary.
| childintime wrote:
| I'm working on a HTML replacement right now. If I am to believe
| the author, it would solve her issue (I don't think so). But I
| don't know if I want to "share". Can I patent it? Good luck with
| that.
|
| Going off-topic now, sort of.
|
| The Open Source I see just isn't serious. We lose the right to
| have an opinion about a technology, to steer it, as that right is
| mediated by money, and it just evaporates, unless you can set the
| norm by being a major user, like a tech titan.
|
| Markdown is special because we as developers are the users!
| Though tech titans dictate what we shall use. As developers we
| are seemingly in a concentration camp where others set the rules,
| and there is no escape, unless we surrender our work in the name
| of love, in the presence of those who absolutely don't,
| government included, and whose basic mode of operation is to make
| the profit on our work. It's just legalized demoralization, if
| not outright stealing.
|
| If you're from a developing country you know what I'm talking
| about. There is no way to be creative and get paid. You are a
| beggar, no matter your talents. The end result is that human
| creativity remains untapped. That is the price we as a community
| pay every day. Heil the rise of AI, so we don't need each other
| any longer, and the abuse can stop ;-
|
| There's crimes everyday, and we normalize them, if they are done
| by the trusted and verified, that talk about merit while they
| hire f*cks to do their bidding. As a community we are a harem,
| and they come to rape us, err, give us pleasure, whenever they
| feel like it, and expect us to love it. Well, don't you love your
| new toys? That is who we are. And we therefore tend to repeat the
| cycle in our homes, as "men".
|
| In the end the framing as a technical issue is what marks us.
| It's is the safe zone, where we can deny the real issue, and
| cope. If you're a member of Nation Procrasti-me, you know what
| I'm talking about. Nation Procrasti-Me, Where Life Is Denied. And
| rent-seeking is the truth.
|
| F*ck, how did we get so cooked? We shackled ourselves, duh. We
| are infants, or else outright dumb, dumb enough to give away our
| life force, for new toys to play. Worse, we dictate others do so
| too. That's when we stand on the side of the abuse, confidently
| like a toddler that just spread his shit all over the place and
| radiates "how good was that!".
| jillesvangurp wrote:
| The main point of Markdown is that it has a very important
| feature that other languages don't have: it's supported in a lot
| of places. Most of the alternatives mentioned in this thread or
| in the article are things that require custom tools, that can't
| be used in most of the places that currently do support markdown.
| It's common in a lot of places. Even Google Docs has a well
| hidden feature that allows you to paste markdown.
|
| It's one of those good enough things where the things it doesn't
| do are outweighed by the notion that you can just use it pretty
| much everywhere.
|
| It's a Betamax vs VHS type discussion (both are at this point
| obsolete and forgotten). HTML used to be pretty limited as well
| compared to things like SGML or any of the wonderful things
| people used for structured documentation in the eighties. Most of
| which are long forgotten. It still is pretty limited compared to
| those probably. But the point with HTML is that that's what
| browsers supported and not other formats. Many of the limitations
| were addressed over time.
|
| Markdown could be improved in a similar way over time. We have
| ambiguous standardization, lack of features, mutually
| incompatible implementations, etc. The whole thing actually
| resembles HTML4 before people started addressing such concerns.
| Evolving Markdown seems like the easier path than replacing it
| with something else.
| zdc1 wrote:
| Yeah, I don't see the point of this article: Markdown has
| already won.
|
| I have some clients where I will send docs in MS Word/PDF
| format, but that kind of proves the point: the recipient sets
| the format. They may not explicitly say anything, but I'm not
| going to send something if there's a risk of receiving a "how
| do I open this?"
|
| Also, code blocks are the worst example of it's limitations:
| just use backticks. Sometimes I want to have a big table or
| diagram and find that Markdown (/Obsidian) doesn't quite
| scratch my itch, but then there's always HTML...
| zelphirkalt wrote:
| While it is true, that Markdown is available in more places, it
| is also true, that it as well "requires custom tools". Just
| that those tools already got put in place by people developing
| things. There is no technical reason keeping developers from
| supporting other languages as well. It's more of a social
| issue, that they don't.
|
| I also doubt, that Markdown will be able to be extended with
| the same "ease" HTML has been extended. Markdown does not have
| a systematic syntax like HTML does. It is not parser and
| machine friendly. It may be human friendly, but that doesn't
| make it easy to extend. In HTML on the other hand, one could,
| theoretically, just come up with a new tag name and introduce a
| new tag. Mind, we are talking about using both formats for
| writing a document. Of course Markdown doesn't have the same
| burden of already being the workhorse of the web and being
| directly interpreted by browser rendering engines. That however
| is an aspect that resides outside of the actual format
| considerations.
|
| We already got tons of Markdown dialects and most of them don't
| gain particularly much traction, because they are only
| supported in niche tools. The only one of them that could be
| considered standard is maybe common mark, with its extensive
| test suite. Specialized ones like Pandoc Markdown for writing
| papers exist, but will most likely never leave their niche.
|
| What I could imagine is, that maybe the changes from dialect to
| dialect could be outsourced into "extensions" and then one
| would need to pick "syntax conflict free" extensions. But since
| the format itself is kind of ad-hoc, and not systematic like
| HTML with its tags, it seems also unlikely, that such an
| extension system would work well.
| coffeefirst wrote:
| The other major feature is anyone can learn it in 5 minutes and
| fit all the instructions on an index card.
|
| Many years ago I introduced it at a newspaper full of OG
| reporters who were a little nostalgic for the clatter of
| typewriters and the kid who would run the drafts around the
| newsroom.
|
| On the first day they thought it was weird. On the second--and
| I'm not exaggerating, it was 24 hours--they loved it, because
| unlike MS Word/most WYSIWYG junkers, it did _exactly_ what they
| told it to, without fussy formatting or invisible characters.
|
| I've done this several times since, with all kinds of non-
| technical users who would never, ever tolerate something like
| LaTeX.
| hinkley wrote:
| The whole point is to dumb a problem down so that people can
| focus on substance instead of form. It's typesetting for
| people who aren't technical and to lower the barrier for
| technical people for documentation of what they're working on
| so far that you can ridicule people who still refuse to
| document their shit.
|
| Any time you can make a developer chose between belligerence
| or stupidity to explain their behavior, they will either
| change the behavior or go with belligerence because they'd
| rather be dead than thought stupid. In either case you have
| maneuvered them out of being able to continue to be
| obstructive to team dynamics.
|
| So you "solve" social problems with technical solutions not
| by making the solution better, but by making it the dumbest
| thing ever so only an idiot wouldn't understand it.
| ivanjermakov wrote:
| Important and often underlooked feature of markdown is that
| it's very readable as plain text. A lot easier to read than say
| latex or html.
|
| I like to think of markdown as a high level markup language
| that gets compiled down to html. There is always a fallback to
| write html directly in markdown.
| thayne wrote:
| > Markdown could be improved in a similar way over time
|
| I think that is unlikely to happen any time soon.
|
| The problem is there isn't any kind of authority that can
| improve it. The closest we have is commonmark, which is more of
| a deacriptive specification rather than prescriptive.
| ulrischa wrote:
| Even worse: social media postings. There are no semantics at all.
| People use emojis and so to structure the plain text
| evandrofisico wrote:
| People keep reinventing LaTeX, but poorly. Most of the issues
| described have already been solved by it at least 20 years ago,
| especially the semantics part. The tooling is mature, well
| understood and supported on all operating systems.
| tannhaeuser wrote:
| As far as custom shortforms for fully tagged angle-bracket
| markup is concerned, people are reinventing SGML which can
| handle markdown and other custom syntaxes since 1986.
| rssoconnor wrote:
| I've been meaning to see how close I can come to Markdown
| syntax using SGML's SHORTREF and perhaps architectural forms.
| tannhaeuser wrote:
| Markdown inline syntax is straightforward to capture using
| SGML SHORTREF. What's more difficult (impossible) are
| things such as reference links where a markdown processor
| is supposed to pull text (the title of a link) from
| wherever it's defined before or after its usage.
|
| Haven't heard about archforms in a while ;) but it's not a
| technique for custom syntax, and since markdown is
| specified as a Wiki syntax with canonical mapping to HTML,
| there's no need for the kind of simplistic element and
| token renaming possible with archforms.
| flohofwoe wrote:
| Eh, we had plenty of such structured document formats in the
| past. Markdown has won simply because it's much less hassle to
| write while still being readable without a specialized viewer.
| Markdown is exactly at the right sweetspot.
| immibis wrote:
| As long as your unstructured hassle-free writing just happens
| to be in the same format accepted by the viewer.
| flohofwoe wrote:
| A generic ASCII capable text viewer is enough to read
| markdown, that's the point ;)
| ranger_danger wrote:
| only if the markdown consists of 100% ASCII... unless you
| have a different definition of "view" than me
| IgorPartola wrote:
| I am surprised TeX [1] and LaTeX (pronounced tech and lay-tech)
| are not mentioned in this post. When I was a physics undergrad it
| was required that we wrote our senior thesis in it as well as any
| studies we meant to publish. Interestingly, my lab worked closely
| with a lab from the chemistry department and apparently their
| standard was MS Word docs. I was given to understand that this
| setup was fairly universal for both disciplines.
|
| Latex seemed arcane coming from the background of HTML but it was
| pretty easy to pick up and is human readable.
|
| Aside from the markup language itself, what is cool about TeX is
| its versioning. Since the idea is that at some point it does meet
| all of its goals it is essentially approximating its own perfect
| form. As a result as it gets closer to that goal its version
| approaches the value of Pi [2]. The current version is
| 3.141592653.
|
| Tex has been around for 47 years so if you are looking for
| stability, look no further.
|
| [1] https://en.wikipedia.org/wiki/TeX
|
| [2] https://www.preethamrn.com/posts/piver
|
| P.S.: manpage format is also quite simple to learn and it is
| always a really good addition to any CLI tool.
| eigenspace wrote:
| Some someone who learned document editing and drafting through
| LaTeX in my undergrad, I gotta say I'm not sure I'd recommend
| it anymore to people looking for a new tool.
|
| To me, Typst is the 'weirdly missing' option here. I really see
| it as the most promising successor to LaTeX, which is not
| something I say lightly given that I spent years scoffing at
| the idea of Typst ever displacing LaTeX in my life.
| gyomu wrote:
| Typst seems to be a cloud based solution with monthly fees?
| How's that even relevant to the discussion of open source,
| free, local tools like latex/markdown?
| Analemma_ wrote:
| No, Typst the typesetting software is FOSS (Apache
| license), as is a bunch of the surrounding ecosystem (e.g.
| the LSP for editor support). The people making it also
| ofter paid SASS stuff for features enterprises like, but
| there is no need to use them.
| thoroughburro wrote:
| > Typst seems to be a cloud based solution with monthly
| fees?
|
| In the exact same way that git is: it isn't, but one easy
| way to use it is.
| eigenspace wrote:
| Absolutely not, no. At least not any more than LaTeX is a
| cloud based solution with monthly fees (Overleaf)
|
| The language, ecosystem, and compiler are FOSS. There is a
| cloud editor / collaboration platform that is paid, but
| nothing about the language requires that you use it (I use
| it almost exclusively through emacs)
| ashton314 wrote:
| I watched Typst from afar for many years. I finally took it
| out for a spin about a month ago after version 0.14 dropped.
|
| In less than an hour I reproduced my resume--complete with
| fancy functions to typeset employment entries on a grid
| system. In under 24 hours I was tinkering with the Typst
| source code.
|
| Typst is amazing. Syntax is clean and consistent. The
| compiler is so so fast. Docs are excellent. And it is very
| close to TeX when it comes to typesetting quality. There are
| a few tiny rough edges that any \usepackage{microtype}
| enjoyer will miss, but stuff is improving rapidly.
|
| (Also, XKCD disclaimer: this was not an LLM--I just use em-
| dashes a lot because TeX made them easy to type and I got
| used to having them.)
| raron wrote:
| At a quick glance Typst seems to be very limited compared to
| LaTeX, especially for more unusual languages.
| Analemma_ wrote:
| Getting people to write documentation is already an uphill
| battle, the reality is it needs to be made as frictionless as
| possible or they won't do it. IMO this rules out (La)TeX
| entirely: it's just too much work that nobody wants to deal
| with.
|
| I also have a philosophical issue with writing documentation in
| TeX: TeX is a typesetting program, i.e. it's a presentation
| format meant to look a certain way on a page, while
| documentation should be agnostic to appearance as much as
| possible. But that's more a personal objection.
| anal_reactor wrote:
| I was the only student who did the thesis in MS Word because
| why the fuck not. Of course I had to use a LaTeX font, and
| there was a bug with PDF export, but other than that, it was
| fine.
|
| Long ago I've read a study somewhere that people using LaTeX
| take more time and effort to accomplish same tasks compared to
| MS Word, but they are more happy about the process. Seems to
| match my impression that LaTeX is "by tinkerers, for
| tinkerers".
| blackhaj7 wrote:
| My biggest problem with Markdown is that I hate writing in it. I
| find messing around with the syntax interrupts my flow.
|
| Are others writing raw markdown/mdx or is there a CMS/Vscode
| plugin I should be using? (I have a few plugins already but find
| the writing experience pretty rubbish still)
| tapirl wrote:
| So I designed TapirMD [1], a new markup language which is still
| readable but more powerful, to help me (a tech writer) create web
| content.
|
| [1]: https://tmd.tapirgames.com
| zelphirkalt wrote:
| The problem with reStructuredText at least is, that there seems
| to be only one canonical parser, that defines the format. Markup
| formats in my opinion need to be defined in terms of a proper
| grammar, so that we can easily adapt that grammar in any
| programming language to build a parser and have support for that
| format in another language. The Org format in Emacs also suffered
| from this, but now there is an effort to make a grammar for it, I
| believe.
|
| That said, I have used reStructuredText for writing a technical
| master thesis, and for that it worked wonderfully. If you buy
| into the ecosystem or use Pandoc to convert to LaTeX/TeX, and
| build a PDF or whatever you need, it will work well. But if you
| want to use it as a basis for HTML pages from other languages,
| which don't have a parser for reStructuredText, then you are in
| for trouble.
| otterley wrote:
| > The problem with reStructuredText at least is, that there
| seems to be only one canonical parser, that defines the format.
|
| The same is true of Markdown (the canonical parser being John
| Gruber's at https://daringfireball.net/projects/markdown/) but
| that didn't stop third parties from extending it in their own
| implementations. For example, canonical Markdown doesn't
| support tables at all, but GitHub added custom markup for
| tables to their parser ("GitHub-flavored Markdown") and it
| became a de facto standard.
| zelphirkalt wrote:
| Oh, I am surprised the original didn't include tables. Guess
| it has been too long, since I looked at his page.
|
| reStructuredText of course has support for tables[1].
|
| I think writing a grammar for reStructuredText is a larger
| effort of course than writing one for Markdown, which is not
| to be underestimated.
|
| Though extending reStructuredText is way less necessary,
| because it already includes a concept for custom "directives"
| (iirc that is what they are called). For example I have once
| made a custom directive to link to other documents, so that I
| have a local "wiki" like structure made out of files and
| folders. In Markdown no specific syntax exists for things to
| be implemented as extensions. Customization authors need to
| include special things in their parser instead, or come up
| with an extensibility concept themselves.
|
| I think the point you are trying to make is, that there seems
| to be something else making the difference in adoption of the
| formats. Do I interpret your comment correctly?
|
| [1]: https://www.sphinx-
| doc.org/en/master/usage/restructuredtext/...
| douglee650 wrote:
| You lost me at, "XML is not that bad if you are already doing
| <x>". Verbosity is insane, attribute vs element freedom induces
| crowd madness. But I do love the data-visiting parts, why can't
| they somehow get that into Markdown.
| rurban wrote:
| Not at all. I use to maintain myriad of packages with
| restructured text, asciidoc, XML, perl pod and tex, but markdown
| all supercede it.
|
| I could easily represent the long word spec for the DWG format in
| markdown with gh tables, rendering it to pdf, and it's even
| better than the original word. Just to represent our diffs.
|
| I could easily produce C++ technical reports in markdown,
| rendering to pdf and HTML, which was perfect.
|
| The rST docs are much easier to maintain in markdown than in rST.
| KronisLV wrote:
| I'd rather use Markdown for writing and even user submitted
| content whenever possible instead of _gag_ HTML or some other
| overcomplicated markup language. Sure, there 's various different
| flavors of Markdown, but on average it's better than
| overcomplicated attribute ridden XML or even XSS prone HTML
| (where nobody even knows what section is and everything ends up
| being a div).
|
| Just give me a good enough baseline, that's it. Markdown is close
| enough to that for now. I don't need that much semantic meaning
| in the text. Something like mdbook (https://github.com/rust-
| lang/mdBook) is more than enough for my needs, compared to
| shipping docs in _once again, gag_ DOCX files and PDFs.
|
| Good that there are solutions for more advanced use cases,
| though, but be careful with that complexity where you don't need
| it.
| pessimizer wrote:
| It really is terrible. I've hated it ever since it was
| introduced, but it "won" before anyone ever adopted it, because
| there were webprogramming Apple/DaringFireball fanatics that
| pushed it everywhere they possibly could, and demanded that you
| acknowledge it as an ideal outcome.
|
| The Apple/DaringFireball fanatics have gone, and the web
| programmers learned how to really program because they had node
| as an option, but we've been stuck with this ugly, limited non-
| standardized format.
|
| I'm an AsciiDoc partisan. I think we should just standardize a
| subset of AsciiDoc that does everything that markdown does and
| let people just implement that subset if they want. AsciiDoc gets
| a bit hairy when you get into the weeds, but if there were some
| sort of graduated standard that layered on features, you could
| learn as slowly as you wanted, and only by necessity. AsciiDoc
| gives you what you need as a base to automate typesetting
| basically everthing, as far as semantics go.
|
| edit: I have to admit that I do not like AsciiDoctor, but it's
| just because I hate introducing Ruby dependencies. The people
| behind AsciiDoctor seem really great.
| knallfrosch wrote:
| Markdown is easy to get started with, that's the main selling
| point.
|
| It's often the choice between Markdown or no documentation at
| all.
| spopejoy wrote:
| Uhh isn't the main strength of md that it's human-friendly to
| write? Same for yaml. In both cases, dramatically worse for
| processing, strictly weaker for semantics and rich formatting...
| And also doesn't make you want to kill yourself when you're
| editing it by hand.
| ctenb wrote:
| I'm surprised Pandoc markdown is not mentioned. You can make that
| semi structured quite easily, and write your own transformations
| using lua. It's powerful enough to write math papers and export
| into both pdf and html.
| paradox460 wrote:
| I recently moved my personal writing to John MacFarlane's djot.
| It's a markup language that grew out of his markdown improvements
| blogpost, where he explored the issues, and possible fixes, he
| discovered while creating the common mark standard.
|
| I've no regrets since then
|
| https://pdx.su/blog/2025-06-28-writing-in-djot/
| scoofy wrote:
| Who is this for? I use markdown when I'm getting text from
| humans. *This* is just 10x easier than <i>this</i>, because I'm
| typing on my phone.
| lanstin wrote:
| Reading all these debates about document structure and formatting
| and so on is so wearying. I predict as long as we have text
| written by people the debates will continue. Truly a case of the
| taste of the writers and producers being a key variable that no
| one system will uniformly satisfy.
| GuestFAUniverse wrote:
| The tenor of the article is more like: Markdown is holding LLMs
| back. And it assumes the semantic enrichment comes for free.
| While I agree that other formats allow for that and it's nice to
| see the solid options: nope, nobody in our team has the time to
| do such a chore and we are fine with the information we leave for
| each other.
|
| It's analogous to the whining of the semantic web folks. The
| semantic web hasn't happened as a whole. Same problem there: who
| would curate all the data?
| jabberwhookie wrote:
| Being held back is the point.. WYSIWYM is a better ideal than
| more fonts, but it still tends towards trouble. It is hard enough
| to get engineers to write and maintain small amounts of correct
| comments without adding boilerplate metadata. I think everyone on
| this site is familiar with gripes against Jira but they are
| supposed to take a brain holiday when evaluating documentation
| mediums? Who is going to make sure previous and next topic are
| correct after the addition of a new topic? The great thing about
| absent fields is that they don't end up with bad content.
| chaidhat wrote:
| I believe that Markdown shines because it is literally human
| language. It's the equivalent of tearing a paper sheet from a
| notebook and writing stuff down. If I wanted formatted, semantic
| writing, I'd use LaTeX
___________________________________________________________________
(page generated 2025-11-23 23:01 UTC)