10 ms·
Markdown is holding you back
- nicoburns 11mo agoThis article doesnt consider Typst, which IMO ought to be the first port of call if Markdown isnt sufficient for your needs.
- perlgeek 11mo agoI've used typst for generating PDFs before, how good is its HTML output?
- undeveloper 11mo agoit looks like typst's html output is under construction [1]. 1: https://typst.app/docs/reference/html/ https://typst.app/docs/reference/html/
- tefkah 11mo agotypst 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 11mo agoTypst 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 11mo agoI guess we need to wait until Typst is natively supported by Github.
- WhyNotHugo 11mo agoI 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 11mo ago> 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?
- timpera 11mo agoIt's interesting to see how Markdown keeps getting more and more use, and even native Windows Notepad support!
- philipwhiuk 11mo ago> 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)
- deleted 11mo ago[deleted]
- dragonwriter 11mo ago> 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 11mo agoMany consider AsciiDoc being too complex.
- doublebind 11mo agoThe 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 11mo ago
- khaledh 11mo agoMarkdown won. Simplicity always wins. Markdown is now the de facto documentation format, for better or for worse.
- jimmar 11mo agoMarkdown 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 11mo agotypst 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 11mo agoI'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 11mo ago> 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 11mo agoI'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/ac57a31f06f41f67eb990d655f009e0e3277ee60/programs/zed.nix#L61-L67 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.
- neoCrimeLabs 11mo ago> 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 11mo agoYou 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 https://daringfireball.net/projects/markdown/syntax#html
- henrebotha 11mo agoThere 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 11mo agomdx does tho. you could just not define any components, then you can nest markdown inside html no problem
- vidarh 11mo agoWhile 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 11mo agoWhat are the trade-offs with AsciiDoc that would make you choose Markdown instead?
- catlifeonmars 11mo agoNot 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
- johnathandos 11mo agoIt’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 11mo agoThe 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 11mo agoWow! TIL!
- nrhrjrjrjtntbt 11mo agoIt 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 11mo ago> 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 11mo agoMarkdown can be used where HTML is not available, like in AI chatbots for omnichannel mediums (e.g. WhatsApp).
- dardeaup 11mo agoThis 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 11mo agoWhat 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.
- macintux 11mo agoYou 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 11mo agoThanks!
- WA 11mo agoYou 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 11mo agois this a poignant satire about programmers?
- hadlock 11mo agoI 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 11mo agoi think that specific turn off phrase is more of an indicator of llm usage then age imo
- Animats 11mo agoThe paper makes the point that people keep extending Markdown, badly and incompatibly.
- autogn0me 11mo agoI 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 https://github.com/jaredh159/asciidork
- sroerick 11mo agoOrg is pretty good.
- dandersch 11mo agoorg-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 11mo agoThe other options look like garbage tho
- jrm4 11mo agoFeels 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 11mo agoI 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 https://orgmode.org/worg/blorgit.html) and [lazyblorg](https://karl-voit.at/tags/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 11mo agoIf 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 11mo agoHmm, 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 11mo agoOrg 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 11mo agoBeen 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 11mo agoReally 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 https://github.com/sphinx-doc/sphinx/issues/8039 and linking issues)
- agoose77 11mo agoThanks for making this point! I'm chiming in just to add that the Jupyter Book project that builds MyST tooling is now using a new TypeScript stack instead of Sphinx, for any interested newcomers! But yes, ^this. We are building around a shareable AST precisely because structure really matters. (I'm a core developer from Jupyter Book, the team that builds the new MyST stack — see https://jupyterbook.org/stable/community/history/ https://jupyterbook.org/stable/community/history/ and https://mystmd.org/guide/background https://mystmd.org/guide/background)!
- ifh-hn 11mo agoI 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 11mo agoMarkdown is the McDonalds of writing
- random3 11mo agoThis 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 11mo agoThe 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.
- deleted 11mo ago[deleted]
- alganet 11mo ago> 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 11mo agoBy 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 11mo agoYa 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 11mo agoWow, 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 11mo agoI'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 11mo agoCertainly 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 11mo agoExample: 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 11mo agoWhat 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 11mo agoI 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…
- twelvedogs 11mo agoI'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 11mo ago> 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 11mo agoI 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 11mo agoI 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 11mo agoMarkdown 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 11mo agoWe found Markdown with directives[1] worked well enough for our use case. [1]: https://talk.commonmark.org/t/generic-directives-plugins-syntax/444 https://talk.commonmark.org/t/generic-directives-plugins-syn...
- timClicks 11mo agoAsciidoc corresponds directly to DocBook XML. They're two formats with exactly the same semantics.
- deleted 11mo ago[deleted]
- isodev 11mo agoI 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 11mo agoI'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 11mo agoThe 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 11mo agoYeah, 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...
- ohboyhereitgoes 11mo ago[dead]
- QQ00 11mo agoWhat sorts of limitations you have with Obsidian? for diagrams I use Mermaid and it's work flawlessly within Obsidian. For anything fancy, advanced and customized, I use Obsidian Canvas, it's a new feature they released recently. So far, I don't need anything outside Obsidian to do any kind of note taking/writing.
- ulrischa 11mo agoEven worse: social media postings. There are no semantics at all. People use emojis and so to structure the plain text
- evandrofisico 11mo agoPeople 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 11mo agoAs 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 11mo agoI've been meaning to see how close I can come to Markdown syntax using SGML's SHORTREF and perhaps architectural forms.
- tannhaeuser 11mo agoMarkdown 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.
- rssoconnor 11mo agoI've use archforms in my custom markup before: https://r6.ca/HtmlAsSgml.html https://r6.ca/HtmlAsSgml.html For example added an <nbsp> attribute to turn all spaces into non-breaking spaces, and used archforms to remove the attribute afterwards. But yeah, maybe for Makrdown you don't need archforms. On the other hand, perhaps there is some super clever way to use archforms to get your reference links working.
- flohofwoe 11mo agoEh, 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 11mo agoAs long as your unstructured hassle-free writing just happens to be in the same format accepted by the viewer.
- flohofwoe 11mo agoA generic ASCII capable text viewer is enough to read markdown, that's the point ;)
- ranger_danger 11mo agoonly if the markdown consists of 100% ASCII... unless you have a different definition of "view" than me
- deleted 11mo ago[deleted]
- IgorPartola 11mo agoI 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 https://en.wikipedia.org/wiki/TeX [2] https://www.preethamrn.com/posts/piver 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 11mo agoSome 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 11mo agoTypst 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_ 11mo agoNo, 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.
- blackhaj7 11mo agoMy 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)
- deleted 11mo ago[deleted]
- tapirl 11mo agoSo 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 https://tmd.tapirgames.com
- zelphirkalt 11mo agoThe 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 11mo ago> 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/ 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 11mo agoOh, 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/basics.html#tables https://www.sphinx-doc.org/en/master/usage/restructuredtext/...
- douglee650 11mo agoYou 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 11mo agoNot 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 11mo agoI'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 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 11mo agoIt 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 11mo agoMarkdown 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 11mo agoUhh 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 11mo agoI'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.
- adamwong246 11mo agoPandoc is great for resumes too. My static website turns my pandoc resume into pdf and html and they look great
- paradox460 11mo agoI 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/ https://pdx.su/blog/2025-06-28-writing-in-djot/
- scoofy 11mo agoWho 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 11mo agoReading 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 11mo agoThe 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 11mo agoBeing 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 11mo agoI 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
- bryanhogan 11mo agoI prefer writing Markdown for notes, e.g. in Obsidian, I think it fits very there. Because now you can easily take your notes to most other note-taking programs, and letting AI interact with these files also works great. If I needed more context / am writing a paper I'd choose something like Typst, but usually I don't need the additional overhead. (Btw: The author has a great name!)
- dwaltrip 11mo ago> Why semantic markup matters > ... > Web developers already went through all this with HTML. Prior to HTML5, you had <div> as a logical container. But HTML5 introduced <section>, <article>, <aside>, and many other elements that described the content. Isn't the semantic web super dead? As in dead, buried, and decorated with countless generations of moss and lichen growing on its gravestone? --- Edit: Huh, I guess it isn't as dead as I thought! https://claude.ai/share/b4622d93-2724-4310-9cdd-95c99693a007 https://claude.ai/share/b4622d93-2724-4310-9cdd-95c99693a007
- deleted 11mo ago[deleted]
- badbotty 11mo agoI find the semantic web stuff is really interesting but it seems to have more success where there are complex up-front data modeling and collaboration requirements, maybe between orgs. There is a Genome database out there for semantic web and I've heard of banks using it in complex fraud detection systems.
- tristor 11mo agoI have been using Markdown for decade(s) at this point, and I have never felt held back. I love Markdown, I use it daily, and I like that it can be instantly understood in its raw format by anyone and rendered cleaning to rich text easily.