7 ms·
On why Markdown is not a good, or even a half-decent, markup language
- ggm 3y agoStrong agree on the lack of a decent definition list notation. Strong agree on roff. Moderately strong on most of his critique Pretty strong disagree that markdown is an abominably bad choice: it's problems are fixable. A single canonical reference and a little restraint and a dl definition would do it for me, regarding man page creation.
- deanebarker 3y ago>A single canonical reference https://commonmark.org/ https://commonmark.org/
- ggm 3y ago(2014 updated 2021) the original OpenBSD article is (2017) and there's still no good canonical DL instantiation -commonmark goes into "do it in HTML" which is .. FAIL in my book. So, a "standard" which has been continuously revised since 2014 and doesn't have definition lists except as "use HTML"
- apple4ever 3y agoThat was the best attempt to update it and improve upon it. Its mostly successful, but not entirely. Wish Gruber would just link to that instead of his old, bugger, out of date spec.
- agildehaus 3y agoIs it meant to be? The appeal of Markdown is that it's easy to remember, reasonably friendly to non-technical people, and it looks good as plain text.
- codetrotter 3y agoIt’s also fast and efficient to type on the keyboard. Plus it feels very natural. Much more natural than for example html or even bbcode, when you are typing out text.
- proser 3y agoMarkdown is an authoring language (it's easy to write) rather than a publishing language (like XML, which is mostly replaces, which sucks to write in).
- codetrotter 3y agoThat’s a perfect way to put it! :)
- stunpix 3y ago> It’s also fast and efficient to type on the keyboard. Plus it feels very natural. If you are solely an English writer then yes. Using md with some languages will quickly turn you into its hater. Certain formatting symbols aren’t easily accessible in some layouts, like backticks for code or ^ for superscript. Some symbols require extra keystrokes like ~ in german. Some layouts will require finger yoga exercises. Basically, any other text markups based on English (including LaTeX) are unfriendly to other languages. Thus an abnormal popularity of md across the apps makes them much less friendly for non-English users. Mobile typing pushes this pain to another level.
- codetrotter 3y agoYeah. My native language has some very awkward placements of certain symbols as well actually. But I chose to sacrifice the letters æ, ø, å years ago by switching to using US-based layouts on my computers. Sometimes I use Dvorak layouts (even have a custom one I made for my mechanical keyboard that I sometimes use). Most of the time I write on a computer in recent years has been using the keyboard on my MacBook Pro computers with just US QWERTY. I very rarely type anything in my native tongue on the computers. Mainly just on the phone. And I am 97% sure that the times I need æ ø å on my macOS laptops I can long-press or option click some of the related characters like a and o. For a while, when I originally switched away from my native language QWERTY variant, I would sometimes need æ ø å on the computer and I would Google aelig oslash and aring respectively and find the symbols for those letters that way :p
- kazinator 3y agoLikewise, asciiflow.com serves something that isn't a good, or even half-decent graphics package for diagramming. Yet, I had to crank out diagrams recently, and found every single program I knew had become enshittified to the point of not being usable. I got the job done with asciiflow box-and-arrow diagrams, pasted into a word processing document as monospaced-font paragraphs.
- anotherhue 3y agoI like https://mermaid.live https://mermaid.live if https://excalidraw.com/ https://excalidraw.com/ is not an option.
- jameshart 3y agoIt’s even more than that - it’s a codification of plain text formatting conventions. If you write a plain text document and you format it following markdown principles, you get a simple rich text version of your document for free. Your headings will be headings, your bullet points will be bullet points, and your code blocks will be code blocks. Now, you can also ‘game’ markdown, writing the minimum possible plaintext to ‘trick’ it into making a pretty document while leaving the plain text ugly. But in general, the idea of markdown is to start from ‘imagine I have a bunch of plain text files I’ve been formatting consistently for years. How can I make them look nice as rich text?’
- tombert 3y agoI was about to say; even before I knew markdown, I was using a lot of its conventions informally. I was using # to denote headers, and surrounding things with asterisks to emphasize them, using > to denote quotes. When I found out about markdown, it took me about ten minutes to learn because it was stuff I was largely already doing.
- wpietri 3y agoFor sure. I'd call it an excellent bad markup language. I use LogSeq daily and as a practical matter I much prefer Markdown to, say, Evernote's WYSIWYG approach, which was more of a pain to use and left me with notes so broken that they are impossible to fix. Or to this author's theoretically better system HTML, because it's more of a pain to write. Basically Markdown cares about formatting about as much as I do, which is barely. I'll note this tension has a long history in CS: https://en.wikipedia.org/wiki/Worse_is_better https://en.wikipedia.org/wiki/Worse_is_better And I think it has a lot to do with a very particular notion of good, which is something like "conceptually pleasing to someone who has mastered the space".
- deleted 3y ago[deleted]
- mmcclure 3y agoSo much this. I think I must be missing something here about the context here, but even then I think it's extremely hyperbolic for the author to make the leap from "I don't like Markdown for [x]" to "Markdown is objectively bad and should never be used in any context." Just look at some of these other examples the author lauds. I've been writing code for most of my life and I find roff's manpage to be absolutely inscrutable. I don't understand the context in which you'd need to pick between roff and Markdown, they seem like they're solving completely different problems for totally different audiences.
- wkdneidbwf 3y agoit’s obviously half-decent enough for most folks. /shrug
- gloryjulio 3y agoIt's great for taking notes. Store it in some repo and u get a globally accessable notebook with version control
- kamray23 3y agoI thought so as well, until I used it. And then I realised that I'd rather go back to OneNote than use markdown. It's just too limited without introducing HTML. Eventually settled on using ms instead of OneNote, gets me that local goodness and beautiful PDFs but also allows me to define things and make it a bit more domain-specific whenever needed. Used it for several documents at work, got compliments on how good they looked. Wild for a relatively limited system from the 70's.
- deleted 3y ago[deleted]
- codetrotter 3y ago> Eventually settled on using ms instead of OneNote This name is too short to Google, and Google thinks I am referring to Microsoft, or even OneNote, when I search for it. Do you have a link to this “ms” tool from the 1970s?
- gloryjulio 3y agoIt's good enough for me as I use an editor most of the time. If it's serious enough for me to write it down and revisit, it's time to use an editor.
- clnq 3y agoIt gets the job done in most cases it is used.
- drbig 3y agoIt is not a markup language, period. ...It's a great convention on how to do common stuff in plain text. Plain text. Let me repeat: plain text. (I'm accidentally doing "a different todo list approach" now due to it, and it is so surprisingly awesome; sorry, busy doing stuff off of my "weird todo list"!)
- jen729w 3y ago> It is not a markup language, period. The clue being right there in the name.
- dev_stdout 3y agoWow, my mind is kind of blown. How did I not notice that before?
- drbig 3y agoDon't worry, you're not alone. And I think we didn't notice because... there are no markup tags anywhere to be noticed!
- listenallyall 3y agoNotepad.exe does plain text. Markdown adds all kinds of extra.
- gavinhoward 3y agoHey, can you describe your surprisingly awesome approach? I am curious.
- drbig 3y agoInstead of thinking in terms of "list items" think in terms of... days. There is only so much that can be done in a day but it is very reassuring to see just at a glance what was actually done. Also, this makes never-ending lists pruning super easy and peaceful - "if this item has been carried over for a month and I haven't touched it then it means it's not needed". And all I use for this is gedit (which is notepad.exe with syntax highlight if you so desire) and have the .txt files sync to my Nextcloud instance. (Note: So far I use it only for personal projects mixed with day-to-day chores.)
- karmakaze 3y agoI never saw the attraction to Markdown. I especially despised the end a line with two or more invisible characters to insert a line break. If it wasn't for Github, I probably wouldn't be using it at all. There were so many Wiki markup dialects and a Wiki Creole that could serve as a base to make a more featured popular one.
- deanebarker 3y ago> I especially despised the end a line with two or more invisible characters to insert a line break. I love Markdown, but I also hate this. The only benefit is that is discourages people from messing with line breaks.
- zerocrates 3y agoIt's not my favorite feature by any means but linebreaks are almost always an issue: practically all Markdown-ish or wikitext-ish formats don't give significance to single line breaks to allow hard-wrapping the source without affecting its rendering, which doesn't leave you with many "nice" options for actually doing explicit linebreaks when you do want them. I've seen ones where you put something like a plus at the end of the line, the spaces from Markdown, or something like MediaWiki's format where you just can't do it without falling back to writing in some explicit HTML.
- JohnFen 3y agoMarkdown is fast and easy and covers the basics. For a lot of use cases, those qualities make it pretty good.
- mattdeboard 3y agoI primarily use Markdown in all my note-taking and blog-writing. It’s fine for it, for me. But lots of these criticisms of Markdown resonated with me. I know it’s a rough analogy, but I’m waiting for Markdown’s “TypeScript”, so to speak: A markup language that is a superset of Markdown, but adds a lot of value by addressing some (the more the better) of the usability and predictability deficiencies pointed out in this blog post.
- abathur 3y agoI came to the same conclusion while trying to work out a good documentation single-sourcing setup that could successfully target multiple formats like markdown, mdoc, be injected into code, etc. I still use markdown for what it does well, but I feel like virtually every other (lightweight) markup language misses the mark as well. Last year I started writing some posts that are about this in a very vague way (6 so far at https://t-ravis.com/room/doc/ https://t-ravis.com/room/doc/) to help order my own thinking and lay some groundwork for eventually demonstrating where a lot of them fall short. (Caveat: I'm not suggesting anyone stop using them for any given project that doesn't need to target multiple output formats. They aren't unusable. They just all have problems that make virtually all of them difficult to use as a single source.)
- ajross 3y agoThis article, and many of the comments here, seem to be written from the perspective of someone who would never think to read the "source code" for a document in the original text format and thinks that the transformed document is the only one they should be looking at. And for those folks, sure, markdown sucks. But some of us still view source code as primary and want to "use" the docs in the same context we use when "editing" the docs. Frankly I'm enough of a curmudgeon that I view the whole conceit of markdown (that it was a concession to the "pretty formatted docs" people that was acceptable to us README dinosaurs) as a step too far. Nothing short of writing docs in proprietary WYSIWYG editors will ever be enough for those folks, and we shouldn't have tried.
- Animats 3y ago"Markdown is pitifully weak and powerless" because it lacks (obscure feature author wants). If you want features, use a word processor, or LaTex, or something. Markdown is for documents that need only very basic formatting. The future of this is probably some AI-based system where you put in raw text and tell the system "make it look good ... no, make it look more like a Medium article...optimize for SEO..."
- peteradio 3y agoTo add on, can't you generally embed html where needed?
- fireflash38 3y agoThat's covered a bit in the article, but as a negative - in that to implement markdown you now need HTML parsing too.
- deleted 3y ago[deleted]
- geitir 3y agoLatex was invented to distract people who otherwise would overly complicate other things
- marcosdumay 3y agoI dunno if that what you meant, but it was pretty much designed so that the people that want to complicate everything go there complicating it, while the people that want to write something useful can just take complicators' work, use it, and raise their shoulders at every objection repeating "you are the one that designed it this way". The original TeX doesn't work this way. That's why people don't collaborate directly in it.
- BrandoElFollito 3y ago
- aarroyoc 3y agoI agree. I had the terrible idea to build a Markdown library in Prolog and I discovered how it's full of quirks. There's CommonMark which tries to be more precise but they have already published at least 25 versions of the spec (and still is not 1.0) and some things are just defined by an algorithm. While I was doing that, I found Djot, a language very similar to Markdown (a bit more verbose sometimes) but much better specified (and with some additional features). So I did a Djot library in Prolog too.
- t8sr 3y agoComparing Markdown and LaTex is silly. One is intended for intuitive plain text input, the other is, as the author points out, almost a full postscript style programming language. I don’t know what mdoc is optimizing for, but it’s sure not intuitive. This post feels like a rant by someone who’s just having a bad day. Not sure why it’s even on HN.
- brigleb 3y agoThis is kind of absurd. Markdown has very specific use cases. For example, using any number of free apps, you can maintain a folder of notes that are human-readable, machine-parsable, that will effectively be useful forever. You’re really gonna keep that folder of text files in “very good” LaTeX??
- 1letterunixname 3y agoAll the things are tools in the toolbox. Nits: Markdown is general purpose but limited. It's a big improvement on plain text files. Thank you Aaron Swartz (RIP) and John Gruber. I sure don't hand-code doc directly in PDF or PostScript formats, although people used to do the latter before TeX was ubiquitous.
- calderwoodra 3y agoMy only complaint with markdown is generally whoever is rendering it chooses terrible values for line heights. I'm not sure if this is part of the spec, but it looks terrible. Here [1] is an example. The dividers underneath headers should have less top padding, so that it's visually associated with the header and not ambiguously associated with either the body or header (or neither). [1] https://docs.github.com/assets/cb-55935/mw-1440/images/help/repository/readme-links.webp https://docs.github.com/assets/cb-55935/mw-1440/images/help/...
- Einenlum 3y agoAs far as I understand, Markdown only defines an HTML output. How it should look like is another story. While I agree with you about GitHub's dividers being too low, I think it's GitHub's problem. Not related to Markdown.
- scarface_74 3y agoIs everyone forgetting the original purpose of Markdown as described by its creator? https://daringfireball.net/projects/markdown/ https://daringfireball.net/projects/markdown/
- tedunangst 3y agoI think the people commenting that this isn't what markdown is for should take up their argument with the people who were saying that openbsd should rewrite all the man pages in markdown.
- thangalin 3y agoHere are a few Markdown documents I've typeset into PDF: * https://impacts.to/downloads/lowres/impacts.pdf https://impacts.to/downloads/lowres/impacts.pdf * https://pdfhost.io/v/4FeAGGasj_SepiSolar_Highlevel_Software_Design https://pdfhost.io/v/4FeAGGasj_SepiSolar_Highlevel_Software_... * https://dave.autonoma.ca/blog/2020/04/28/typesetting-markdown-part-8/jekyll-hyde.pdf https://dave.autonoma.ca/blog/2020/04/28/typesetting-markdow... My text editor, KeenWrite[1] (see tutorials[3] for details), converts from Markdown to XHTML. The XHTML is then typeset using the ConTeXt typesetting software to create a PDF. The PDF is stylized using a theme[2]. What Markdown is missing, in particular flexmark-java, is a standard CommonMark extension for cross-references and citations[4]. [1]: https://github.com/DaveJarvis/keenwrite https://github.com/DaveJarvis/keenwrite [2]: https://github.com/DaveJarvis/keenwrite-themes/tree/main/examples/the-mill-on-the-floss https://github.com/DaveJarvis/keenwrite-themes/tree/main/exa... [3]: https://www.youtube.com/playlist?list=PLB-WIt1cZYLm1MMx2FBG9KWzPIoWZMKu_ https://www.youtube.com/playlist?list=PLB-WIt1cZYLm1MMx2FBG9... [4]: https://talk.commonmark.org/t/cross-references-and-citations/4013 https://talk.commonmark.org/t/cross-references-and-citations...
- the-printer 3y agoI'd be interested in KeenWrite if it supported MacOS. Your pandoc/ConTeXt guide is top notch. ConTeXt is very underrated.
- thangalin 3y agoIt's written in Java. People have run it on MacOS. I don't have a .dmg file, though. https://github.com/DaveJarvis/keenwrite#other https://github.com/DaveJarvis/keenwrite#other If that doesn't work for you, please open an issue and describe what you'd like for MacOS.
- the-printer 3y agoI stand corrected. Thank you!
- abdullahkhalids 3y ago
- F3nd0 3y agoFor technical documentation? Sure, I see how the alternatives make more sense. But for more general use, like formatting shorter posts on forums and social media? Markdown seems quite adequate there, and dealing with any of the listed recommendations would be unbearable for many users. I’m not sure if the article was written for a very specific audience or expected to be read in a given context, or if the author overgeneralises their conclusion to all applications that a markup may have. (In the former case, it just doesn’t work as a standalone piece, in my opinion, so I don’t see much that could be said about it here.) On a side note, the text only glosses over TeXinfo, calling it officially dead based on an e-mail from 9 years ago, while it’s had many new releases since; I’m not sure what to make of that. Would anyone have more insight into that?
- thangalin 3y ago> For technical documentation? How's this? https://whitemagicsoftware.com/softcover/technical.pdf https://whitemagicsoftware.com/softcover/technical.pdf
- gorkish 3y agoThis advice does appear to be coming from someone who writes webpages using roff... The core argument simply seems to be that markdown lacks sufficient structure to build "documents," which I agree is absolutely true and essentially part of the design. IMO Markdown isn't intended to structure documents; it's intended to enhance plain text. If you find yourself constantly tweking at whitespace or special characters to provoke your markdown to behave, or if you are using so many features of md that you have to keep a reference handy, maybe you ought to use something different. As an aside, I have used Front Matter (essentially a YAML header on markdown) for cases when a bit of structure or metadata is needed alongside a blob of text, and I think it strikes a great balance between writability and structure. Markdown tables need to die in a fire though; what a wreck.
- hooverd 3y agoMarkdown isn't a good markup language compared to LaTeX. I wouldn't typeset a paper with it. However, I wouldn't write my notes or a blog with LaTeX.
- jakelazaroff 3y ago> So, the bottom line is: Do not use markdown. Do not use DocBook. Do not use Texinfo. Use mdoc(7) to maintain your source documents, and mandoc(1) to convert them when needed Cool, let’s see what mdoc looks like: > The following is a well-formed skeleton mdoc file for a utility "progname": .Dd $Mdocdate$ .Dt PROGNAME section .Os .Sh NAME .Nm progname .Nd one line about what it does … So, utterly incomprehensible. I’ll stick to Markdown, thanks!
- jaylittle 3y agoIt will never cease to amaze me how out of touch some technical people are... including the author of this markdown rant.
- devinprater 3y agoAnd the person that wanted to use PDF as web pages instead of HTML.
- apple4ever 3y agoAgreed! I think this is the main problem with Markdown: > The most official reference manual for markdown is the original one written by John Gruber in 2004. It is unmaintained since that time and leaves various ambiguities, such that different parsers tend to parse input somewhat differently in detail. Its ridiculous that it hasn't been updated, though there have been some attempts.
- draw_down 3y ago[dead]
- MattPalmer1086 3y agoYeah, I also looked at mdoc and came to almost the same conclusion. He's only saying if you want to write man docs use the syntax designed for it... Ok. It's horrible to read and write but it's probably the best thing to use. OTOH if you want to write simple plain text that humans can read and write with no difficulty at all, but can also make nice richer text if you want, markdown is great.
- cscheid 3y agoOn LaTeX: > Little context sensitivity ... this is close to a disqualifyingly wrong statement. (I literally work with Markdown on a daily basis as my actual day job. Markdown really does suck.) The only way in which (La)TeX is not context sensitive is that it's sensitive to the entire global TeX state at all times. There's no notion of grammar in TeX, _at all_. It's hard to trust the rest of the content in there after this.
- lapcat 3y agoThis submission title has been editorialized, contrary to the HN guidelines. The submitted URL appears to be the man page for a "mandoc" command.
- the-printer 3y agoThe author's website is designed to look like the OpenBSD manual's web page. This is a blogpost about mandoc/markdown in the form of a man page...for mandoc...very clever. http://schwarze.bsd.lv/mandoc.7 http://schwarze.bsd.lv/mandoc.7 Also apparently the submission title needs (2017).
- jaylittle 3y agoMy summary of this rant: Ivory Tower bullshit Markdown is phenomenal. It gives end users simple and easy to remember ways to perform the most common formatting operations but leaves the text in a state that it was be parsed by humans without an actual markdown renderer.
- frizlab 3y agoPersonally I highly prefer Asciidoc. It’s like md, but is (much) better defined. And it works on GitHub too! https://docs.asciidoctor.org/asciidoc/latest/asciidoc-vs-markdown/ https://docs.asciidoctor.org/asciidoc/latest/asciidoc-vs-mar...
- ssgodderidge 3y ago> "Abominable" The author refers to Markdown as "Abominable" at the end of the page. I am always skeptical when someone has this level of disdain for any technology. The overall argument that "Markdown is bad" would be stronger if they noted the pros of Markdown, and why the pros are less valuable in aggregate than pros of other languages.
- karaterobot 3y agoIt's not a good markup language, it really isn't. It's not good at semaphore either, or paving roads. I tried spackling a hole in my drywall with it, and it failed miserably. But when you want to write a document that is both human readable and machine interpretable, and you've only got 30 seconds to learn the syntax, nobody has ever been able to beat it. So I guess it depends on what you want.
- paulddraper 3y ago> [Markdown] allows embedding arbitrary HTML code, both at the block and at the flow level. That makes writing any parser for it very hard because you basically have to include a full HTML parser and then add context sensitive complications...You also have to worry about all the security caveats of HTML. For example, HTML allows embedding Javascript, so you get to implement a Javascript interpreter as well, and to secure it. Is it just me, or is a JavaScript interpreter irrelevant to a Markdown parser?
- klardotsh 3y agoIt is. I know of zero Markdown implementations off the top of my head that bother to parse JavaScript - if there's JS embedded in HTML embedded in Markdown, it gets passed through as a block element on the HTML side (which may or may not be parsed, either). TFA is drawing at straws to dunk on a format they don't like.
- OkayPhysicist 3y ago#Heading Here's why allowing arbitrary HTML and JS in your Markdown makes parsing painful <script> console.log("</script> is a closing tag for script blocks"); </script>
- gorkish 3y agoMarkdown "supports" embedded HTML but that does not mean that your chosen implementation must support it. Personally, I think it's a misfeature and wouldn't want to touch any markdown lib that tried to put too much emphasis on something like validating or sanitizing HTML and Javascript. That's a project with too much scope creep.
- vanjajaja1 3y agoi am not surprised that the owner of this linux.com website doesnt understand markdown and promotes latex as an alternative. its a type of guy
- jandrese 3y agoThe thing that frustrates me with Markdown is that there are about as many different flavors as there are implementations. Once you get beyond bold and _italics_ it is a trip out to some help page to figure out what the special snowflake syntax is this time. How do you make a link? Embed an image? Make billeted lists? Embed pre formatted code? Who knows?
- gabrielsroka 3y agoI love how your bold came out in italics. Maybe making your point for you. https://news.ycombinator.com/formatdoc https://news.ycombinator.com/formatdoc
- lockhouse 3y agoMy unicycle is not good, or even half decent at carrying groceries.
- klardotsh 3y agoI got to the bottom and saw that the author thinks TeX is not only a viable alternative to Markdown in the spaces Markdown is heavily used, but is their favorite such "alternative". And so anyway, despite nodding along with a few arguments above that point, I have concluded that the author and I are looking for extremely different things out of our text markup languages. I want just about as far from TeX as possible - at that point, I may as well just write README.txt's in plain text that resembles Markdown or GemText, but in a less formal manner. At least it'll look the same level of good/bad/whatever in vim as it will when dumped into an HTML file, or a PDF, or whatever. With TeX, I basically have to render the document for it to be readable.
- devonnull 3y agoMarkdown doesn't meet the author's needs. OK, that's fine. They shouldn't use it. But others find it useful, regardless of Markdown's limitations. Which is fine, too. The markup language you use (or don't use) doesn't determine or influence the quality of what you're writing. Use what works for you. That could be Markdown, vanilla HTML, LaTeX, DocBook, (x)roff, whatever. No need to justify your choices.
- russellbeattie 3y agoOh boy! Another thread about what a POS Markdown is! As someone who wrote a similar blog post which someone then posted to HN, I'm just going to sit back with some popcorn and enjoy watching the keyboard jockeys and pedants belittle and dismiss yet another voice of reason. Markdown is a 20+ year old hack which needs to be killed with prejudice. It's continued popularity is not just bewildering, it's just plain sad. I'll just repeat what I always say in these threads: We're in the second decade of the 21st century, and can send anyone on Earth a custom colored emoji in 8 shades of skin color, but bold, italics, bullets and headings are somehow an impossible technological hurdle. Why? Because all the geeks keep insisting that formatting text using random keyboard symbols is a great idea.
- Tao3300 3y ago> in some contexts, documentation authors are required by third-party policies to provide markdown versions of their documentation Well that's not markdown's fault.
- MilStdJunkie 3y agoWhen you have a certain kind of mind, you tend to see "simplicity" in a way that might not be recognizable to others. I think Mr. Schwarze might be one of those minds, seeing his history with Free/OpenBSD. Markdown's fantastic for generating pure HTML. However, if I had a print deliverable, or any complicated function like transclusion or conditionals, I'd maybe nudge the user to try out an alternative, Asciidoc or something else. Why do I say that when you can do so many cool things with Markdown? Well, "so many cool things" is sort of the problem. You build up a unique Mkdwn/Extension/<Insert_Framework_Of_Choice/> stack every time you do a "cool thing", until eventually you're writing docs for what is, in effect, a bespoke parser. Knock out one block of that - say, like, your company's InfoSec department decides that technical writers having NPM is a Very Bad Idea - and your cool thing gets scaled back or broken outright. It's much better for your docs' lifecycle to use just the core of the spec, and not be dependent on a flurry of extensions and dependencies for the business of making docs. I don't include edge uses, where extensions excel. To take one example, Mr. Rojas' excellent WireViz program (https://github.com/wireviz/WireViz https://github.com/wireviz/WireViz). If that gets knocked out, my document still builds into PDFs. The price you pay, of course, is a more niche ecosystem; Asciidoc tooling is maybe a tenth or a fiftieth of what's dedicated to the M*kd*n Multiverse. And of course, if you're writing simple docs that go straight to HTML without so much as thinking about a print layout, then Markdown is the easy choice.
- dredmorbius 3y agoMany moons ago after having long criticised shortcomings of a reasonably popular system,[1] I finally arrived at a moment of enlightenment: It is a simple tool, accessible to many, which is useful for simple tasks. The chief architect of the system didn't comment on the note, but did as he frequently did with various critiques of mine, indicate having seen it. Markdown fits this description, and really should be considered on those grounds. And it's suitable for documents of often surprising complexity. Manpages are a specific document type, which have co-evolved with a specific document processor. I've used that processor, and even, whilst at uni, wrote term papers using it. I've forgotten virtually all that knowledge: roff(1) and kin are obscure and complicated. They're also not especially human-readable, in ways that Markdown, other lightweight markup languages, HTML, LaTeX, and DocBook, say, are. See also: <https://www.dreamsongs.com/WorseIsBetter.html https://www.dreamsongs.com/WorseIsBetter.html> (HN discussion: <https://news.ycombinator.com/item?id=8449680 https://news.ycombinator.com/item?id=8449680>) ________________________________ Notes: 1. Google+, as it happens. Which had its own bastardised and painfully limited markup notation. And no, it didn't kill FB, but it was used extensively by tens of millions.
- its-summertime 3y ago> For example, it doesn't provide any syntax for definition lists I mean, it does, its called HTML: The key point of it was to dip into another language if you needed to express complex things, not, add everything to the main language
- Einenlum 3y agoMarkdown was never meant to be perfect. It was meant to be simple. It's actually so simple that I could teach my parents how to write a Markdown document in a few minutes. The fact that the author doesn't have to introduce what Markdown is, could give him a hint about why Markdown is not that bad. It's useable, super simple and stupid. It's so stupid that it's used. I don't think anyone wants to write the README in their GitHub repositories in LaTeX, or worse, in mdoc. I prefer a markup document I can learn in 3 min than a "perfect" markup language barely readable by humans, requiring people to read an obscure and painful documentation for days/weeks.
- jordanmorgan10 3y agoToday I learned opinions can be wrong
- jordanmorgan10 3y agoToday I learned opinions can be wrong.
- cirrus3 3y ago> I hereby offcially declare it the shittiest markup language i have seen so far. Basically, it hasn't any strong point whatsoever, but the downsides are numerous, scary, and cover practically every relevant aspect: Wow. No need to read this rant further.
- dwh452 3y agoI haven't seen anything new in this space and I just finished a project using a markdown format I invented called Tagged{Text}. I'm happy to present it here for your consideration. In creating my blog and static site I started using Markdown but couldn't get around the limitations. So I invented a simple file format for tagging text into a tree like structure. It has a formatting style modeled after LaTeX. It has served me well (two websites and two blogs). I call it an "agnostic markdown format" because no tags are defined ahead of time. The user defines everything and writes python filters to generate the output from the tags. I have lots of python code to parse and generate HTML. It has a macro processor, calculator, git date, and other useful tags. Here is an article about Tagged{Text}: https://etcutmp.com/taggedtext.html https://etcutmp.com/taggedtext.html Another website built using this format: https://etcutmp.com/evolve5 https://etcutmp.com/evolve5 Source Code: https://github.com/kjs452/tagged_text https://github.com/kjs452/tagged_text Source Code for the second website: https://github.com/kjs452/Evolve5Help https://github.com/kjs452/Evolve5Help The main python file is: taggedtext.py (the parser). All the other python code are filters to generate or transform the tagged text tree into something else. For example, tt_macros.tt implements the DEFINE{} tag.
- patmorgan23 3y agoDon't measure a fish by it's ability to climb a tree. The point of markdown is that it's dead simple, it lets you provide some basic structure and formatting but is still easily readable in plain text.
- invalidname 3y agoPretty much all of OPs complaints are answered by AsciiDoc. I've used it for my books, docs, etc. It's fantastic and has amazing toolchain support in IDEs, GitHub, etc. The big (good) publishers use it as their standard (O'Reilly, Manning, etc.).