Things Markdown got wrong(swyx.io)

https://www.swyx.io/writing/markdown-mistakes/

193 comments

I wish that markdown formatted bold and italics like this:

  _italic_

  *bold*

instead of:

  _italic_

  *italic*

  __bold__

  **bold**

because stars around a word make it look like it's glowing, sort of like bold does, and underlining a word means to make it italic. Does no one remember this?

In English class, before computers, our teacher told us that certain words are always underlined: book titles, ship names, etc.

In Typing class, our teacher told us that if you submitted a typewritten manuscript to a publisher, what you underlined with your typewriter would be converted to italics in a typeset book. Underlining meant italics. And sure enough, nowadays when everyone has a computer instead of a typewriter, and can make real italics, they tell us that book titles, ship names, etc., ought to be in italics (the same things that my teacher used to tell us should be underlined) https://www.purchase.edu/editorial-style-guide/general-style...

I get kind of why Gruber did it his way. He was caught up in the Semantic Web, where you don't use and , you use and , and means only more so. So by that logic

  *this*

is emphatic, and

  **this**

is strongly emphatic.

samatman6 anni fa

I'm enamored of the org-mode textual formatting convention: •bold︎•, /italic/, _underline_, =literal=, and ~strikethrough~. Although `literal` a la Markdown is arguably better, I prefer the other choices.

Especially because org-mode lets you italicize //Face/Off// by adding more slashes, and so on for the others, like ==e = mc^2==.

Incidentally, I have no idea how you're typing literal asterisks, I gave up and am kinda jealous.

SyrupThinker6 anni fa

A small nitpick,

its actually ~code~ and +strikethrough+ .

[Official documentation](https://orgmode.org/org.html#Emphasis-and-Monospace)

joshspankit6 anni fa

/italic/ is also how it used to be done way back in the early BBS/MUD/MUSH days (along with _underline_)

ksec6 anni fa

Yes I think this makes much more sense to me since the / operators align with how the characters in italic looks once it is applied ( Slightly tilted )

And underline.

I dont understand why they aren't used that way any more.

bumbledraven6 anni fa

Judging from the indenting, the poster used HN’s codeblock/verbatim formatting for the asterisks. https://news.ycombinator.com/formatdoc

adrusi6 anni fa

I really dislike /italic/. Relative to the slashes, the letters look like they're skewed in the wrong direction. Surely it should be \italic\. If unifying underlines and italics doesn't suit you.

ScottFree6 anni fa

Is this a localization thing? In this image here[0], the italicized word clearly leans to the right.

Funny thing happened when I tried to type that out: typing /italics/ caused libre office to automatically italicize the word.

[0]: https://imgur.com/cq7BMex

adrusi6 anni fa

When I read /italic/ or \italic\, I end up mentally transforming the text so that the slashes are vertical lines. When you do that with forward slashes, you get text with a negative slope (the wrong way).

Demonstration: https://codepen.io/adrusi/full/poJXRgy

ScottFree6 anni fa

Huh. That's pretty damned interesting. Thanks for explaining!

ksec6 anni fa

Same question, not sure what your parents meant at all. Unless there are languages italicised that leans to the left ( That would be very interesting )

samatman6 anni fa

I grew up on Usenet so I'm used to it.

Always thought the idea was that the first slash pushes the letters over, and the second one keeps them from falling down completely.

The unification of underline and italic is an artifact of the limited technology of the typewriter, and I see no reason to preserve that.

kazinator6 anni fa

Moreover, the convention that you advocate is more or less an established practice in Usenet and mailing lists, long preceding markdown. This design decision in markdown is uninformed.

Vinnl6 anni fa

Two minor notes:

1. "Semantic web" refers to data being linked and having meaning. You're referring to semantic HTML.

2. I don't think meant but more so - as I understood it, meant text that had to stand out from the rest, whereas meant that text was emphasised. Though I might be confusing it now with the retro-actively applied "semantics" of and .

Totally agree with the overall point btw, and I do tend to use them in the way you described.

combatentropy6 anni fa

> I don't think meant but more so

I guess it was an HTML 4 thing, the standard at the time of Markdown, https://www.w3.org/TR/html401/struct/text.html#h-9.2.1

: emphasis.

: stronger emphasis.

I see that HTML 5 has tweaked their descriptions, https://html.spec.whatwg.org/multipage/text-level-semantics....

: stress emphasis

: strong importance, seriousness, or urgency

cornishpixels6 anni fa

HTML 4 was not the standard at the time of Markdown. XHTML was.

Vinnl6 anni fa

Huh, I guess it was.

Anyway, it was all a whole lot of "semantics-washing" anyway; it's lot like people strictly adhere to strong rules of when text should appear bold or in italics anyway.

adrianhel6 anni fa

Agree. It's really missing the point of how this has been used in reality for the sake of promoting semantics in an area where semantics rarely matter.

kstenerud6 anni fa

It's actually surprisingly difficult to get this kind of thing right. It seems perfectly obvious in hindsight, but while you're designing, little details like this get missed.

When I started writing a spec for Concise Text Encoding [1], I figured it would take about 6 months to nail it down (yeah, right). Even now, 2 years later, I'm still making amendments to it because of various things I missed or got wrong. It's either something I happen to notice in one of my many, many re-reads, or something that another person notices after a few minutes reading it over, or something that comes up while I'm writing the reference implementation. Getting a spec right is a marathon affair.

[1] https://github.com/kstenerud/concise-encoding/blob/master/ct...

funcDropShadow6 anni fa

It seems to be an instance of Wadler's Law.

> In any language design, the total time spent discussing > a feature in this list is proportional to two raised to > the power of its position. > 0. Semantics > 1. Syntax > 2. Lexical syntax > 3. Lexical syntax of comments

https://wiki.haskell.org/Wadler's_Law

Sniffnoy6 anni fa

Agree in general, but don't like the underline/italic thing. Most word processors have underline as separate from underline. Hence the alternative old email/Usenet convention: underscores for underline, slashes for italic.

combatentropy6 anni fa

Professional typesetters have an aversion to underlining text. It's ugly. The line interferes with descending letters: f, g, j, p, q, y. The underline is as thick as the stroke of a character, so decorative marks compete with signal marks. It's just too strong. That's why you see text underlined in homemade flyers but almost never in books, magazines, newspapers, or other things designed by pros. The recent addition to CSS to specify that underlines go behind the descenders is a welcome change.

Professional web designers have the same aversion that print designers have, they are birds of a feather. But now they have another reason to hate it. Underlining has come to mean hyperlink. Because of their original aversion, they will often use CSS to remove that default underline, maybe bringing it back only when you hover over a link. But because it is still a widespread convention throughout the web, and probably always will be, they would never, ever emphasize something by underlining (they use border-bottom ;).

Since you should underline something only if it is a link, which has its own markdown, and since underlining is ugly anyway, and since bold and italics are enough ammunition for all your emphasizing needs, and since it is an established convention from the old days that underlining meant eventual italics when it went to press, it's okay in my book to repurpose _underscores_ for italics.

Slashes instead on both sides like /this/ --- hmm, it's not bad. I'm undecided.

JadeNB6 anni fa

> Most word processors have underline as separate from underline.

One of those words isn't supposed to be 'underline', right?

eyegor6 anni fa

Probably meant italic and underline

Sniffnoy6 anni fa

Oops, yes, I did.

nabla96 anni fa

  //italic//
  __underline__ 
  **bold**

hamstergene6 anni fa

This. Using doubles for markup removes the need for backslash escaping when those symbols naturally appear in text,

gmac6 anni fa

Textile got this right: https://movabletype.org/documentation/author/textile-2-synta...

Optimal_Persona6 anni fa

You beat me to it, I always thought Textile was the Betamax to Markdown's VHS - technically superior but for whatever reason (actually John Gruber's visibility and GitHub's adoption of Markdown), Textile didn't really gain traction with users.

akkartik6 anni fa

Slack and WhatsApp seem to be adding to your case, and they drive lots of usage.

omnimus6 anni fa

Because calling it italic and bold is WYSIWYG all over again something Markdown tried to cure.

The proper way to think about is s emphasis and strong emphasis. As user you shouldn't be concerned by how it looks. Thats job of overall design and that might change depending where you publish / who designed it. You shouldn't make that decision because you don't have the required context.

Italic will probably be the emphasis (although other designs are possible like change of color). Underline can be used for strong emphasis if it doesn't colide with links. Bold might be too jarring or not possible to use so designer might decide to not use it.

There are also other ways to emphesise like small caps or inline background colors.

DougWebb6 anni fa

As user you shouldn't be concerned by how it looks. Thats job of overall design and that might change depending where you publish / who designed it. You shouldn't make that decision because you don't have the required context.

As the writer of Markdown content, you're often both the user of the content and the publisher of the content, so you do care about how it looks. Even if you're just the user, your intention when writing is to communicate something, and the eventual appearance of your content impacts how it is interpreted by the reader. So you still care about how your writing will look, which forces you to care about how the publishing process interprets the markdown syntax.

omnimus6 anni fa

I am not saying you can't be both user and publisher. I am saying that these are two different processes often made by different people.

When you publish book you have mostly zero power over how it will be designed. And honesty you should have zero power over it because there are people editors/designers/typesetters who dedicate their lives to exactly that. Better to let them handle it. Same goes for the web.

dkarl6 anni fa

You have to choose one or the other, semantics or formatting. There's a standard way to format a book title: italics. You have to be able to say "format this with italics" or "this is a book title."

A system that prefers semantic tags such as "emphasis" and bans direct formatting such as "italics" only works if you can import or define a semantic tag for "book title" that you know will be formatted correctly. It doesn't make sense to tag a book title with "emphasis," because there are a lot of different ways to express emphasis, and only one of them works (quite coincidentally) for a book title.

omnimus6 anni fa

Yes but i think we would both agree that in html/markdown it should be "this is book title" because medium allows it. "format this with italics" makes as little sense as "format this with emphasis" they are both wrong. Interestingly "format this with italics" is right solution in print because we encode that meaning in aesthetics and conventions and i guess thats why people think it is also right solution in web. But even in typesetting program that book title will have class .book-title and same italic in footnotes will be .footnote.book-title

combatentropy6 anni fa

Everything you say is true. I started making web pages 20 years ago. When I got a real job doing it in the mid-2000s, it was at the height of the push for semantic markup. Over the years I've come to think it is overwrought.

First, I think they could have repurposed the old tags. can stand for "important," with a default style of italic, and could mean "bold" in the sense of "strong" or "outstanding", https://www.etymonline.com/word/bold, with a default style of boldface type. You can still restyle them to your heart's content.

Second, italic doesn't always mean emphatic. Like I said, it is also a formal convention for: titles (books, movies, magazines), ships, foreign words, legal cases, etc. (Only of large works. For articles and other small works, you quote them. So for example, The New York Times should be in italics, but any particular article, like "Chiefs Win Superbowl", should be in quotes.)

Third, the tags are longer, especially instead of . It's noisy. A quibble, you might say. But so is this whole topic. And there is a line where coding goes from fun to tedious.

Fourth, an asterisk looks stronger than an underscore anyway:

  *this*

calls out more than

  _this_

So you could say underscores are emphasis and asterisks are stronger emphasis, even with just one on each side.

omnimus6 anni fa

I am very aware of the formal conventions in print but thats not the problem here. Especially in html those cases should be marked differently (like with span.class) so that can be understood by machine or screenreader.

There can any number things set in italic on page and none of them have to use .

"italic doesn't always mean emphatic" is exactly the reason why i say think of it as emphasis not as italic.

Also emphasis/strong in html is mainly for general emphasis in paragraphs of text. It works pretty much like h1 and h2. The difference is that you have only two levels.

BurningFrog6 anni fa

> As user you shouldn't be concerned by how it looks

I'm a user and I care a lot about how my documents look.

omnimus6 anni fa

Yes and often times how they look will be out of your hands. You publish in magazine and their editor+designer will change your underlines to italic and your italics to bold because thats how it makes sense in their publication.

Of course you are both writer and publisher you are also in control of the design. But when you are writing you shouldn't be thinking about how to present the text. These are almost always different processes (except rarer things like poetry or experimental prose that rely on whitespace). Write > edit > present/design.

holman6 anni fa

> I'm not sure who invented [fenced code blocks], but I definitely know that it is widely used because GitHub Flavored Markdown made it so and I am grateful for that.

I’m pretty sure Vicent Martí (@vmg) was the originator of them. I remember we spent a number of weeks internally at GitHub debating the syntax, since no one really fell in love with any of the proposals for various reasons. Eventually the triple tick won out and that’s worked out fairly well, I think.

rapsey6 anni fa

Man I hate those ticks. I have no idea what arcane key combination on my keyboard I need to do to get them. Maybe it's easier on a US keyboard.

adrianN6 anni fa

My biggest problem with the ticks is that they're dead keys if you want to be able to write accented characters easily. I write à code sample` way too often.

Freak_NL6 anni fa

You could consider using the compose key instead of dead keys. Diacritic characters take a three-key chord instead of two ([compose ` a] instead of [` a]), but all programming characters type as-is. The right alt is usually chosen as compose key.

AlchemistCamp6 anni fa

I'm not in the US and there's a single key that corresponds to a back-tick. In fact, it hasn't yet been an issue for me on keyboard layouts for four different languages (from three separate language families, no less)!

Where is your keyboard from?

jeromegv6 anni fa

French Canadian keyboard definitely doesn’t make it easy.

CodesInChaos6 anni fa

German keyboards have both accent directions as a dead-key. So you have to press press shift+´ then space to get `. And that assumes you can remember which direction markdown wants.

chrizel6 anni fa

It’s very easy on the US keyboard: the key for ticks is under the escape key, no shift needed, just hit this single key.

I’m German myself, but I use the US keyboard layout for more than 15 years now, because it is so much easier to type things like this... especially in tech. (And also keys for [, ], { and } are much better placed in the US layout)

encom6 anni fa

Dane here. The danish keyboard is arguably retarded, but I've used it my entire life, and on purpose have not tried other layouts, because as soon as I use a computer that isn't my own, I'd revert back to hunt and peck mode. It's the same reason why I never bother changing software defaults, except in rare cases.

loeg6 anni fa

Do most Germans use QWERTZ?

chrizel6 anni fa

Yes, most people learn and use QWERTZ. In your typical electronics store, you will only find QWERTZ keyboards and notebooks. If you want QWERTY, you have only one option, you have to buy it on the internet. But even on the internet the typical Logitech keyboard for example is hard to find in US-QWERTY in Germany/Europe, because most merchants don‘t have them on stock. In the past, I‘ve even imported US keyboards from the US, because they were and are hard to find here.

It gets even more difficult for notebooks: Any notebook you can buy here in Germany has QWERTZ. Want a notebook with US layout, because you are a developer? Your only options are BTO options from Apple or Lenovo. But even there, you have to be cautious: Dell for example will sell you „English“ keyboard layout notebooks as BTO option, but you won‘t get the real US layout (with a wide return and wide left shift key), but some kind of „International English“ ISO layout with a tall return key and a short left shift key... Lenovo has an „English“ option and thankfully you will get a keyboard layout that really resembles the US layout (but with an Euro key).

Only Apple really gives you „US“ as BTO option, and you really get the real US layout. Funny story, I wrote an e-mail to Apple, over ten years ago, when they didn‘t have US layouts as BTO option in Germany... I think it changed something, because one or two years later, Apple changed it, and you will get real US layouts ever since on their online store.

j_46 anni fa

>in Germany/Europe

Wow, I honestly didn't know how widespread non-QWERTY keyboards are in Europe. Wikipedia has a nice map.

https://en.wikipedia.org/wiki/QWERTZ

I live in Poland and we pretty much exclusively have QWERTY. QWERTZ is a historal artifact. Not sure if that's still the case but at least until recently, it was installed by default on Windows as an alternative layout, seemingly mostly to confuse non-technical people when they accidentally press the Ctrl+Shift combination to swap.

chrizel6 anni fa

Interesting. But we have to be clear here: It‘s not only about QWERTZ vs QWERTY. Many countries still have ISO keyboard layout: a tall return key and the left shift key is short (according to https://en.wikipedia.org/wiki/QWERTY). The US keyboard is different: the return key is wide and not tall, and the left shift key is also wider. If you once got used to the US layout, it‘s annoying to use an ISO layout, because your pinkies have to move a little larger distance to hit return and left shift, if you know what I mean. :-)

j_46 anni fa

Oh! That's true. I think you have it a bit mixed up though.

- ANSI is the same thing as US, it's the one with a long left Shift and single row Return

- ISO is the one with a short left Shift, two row Return, and the [| \] key in two places

I've certainly used both throghout my life, it seems both are common enough that I never paid it much mind after first learning how to handle a computer during early childhood.

I just checked and out of the 5 keyboards in my home right now, 4 (laptops) are ANSI and 1 (standalone, my daily driver) is ISO.

chrizel6 anni fa

Oh sorry, you are right - I‘ve mixed up ANSI with ISO... thanks for the correction!

cornishpixels6 anni fa

Honestly, this misses the worst part of the ISO layout. PUT MY \| BACK WHERE IT BELONGS!

brnt6 anni fa

No need to import from the US, in your friendly western neighbor (Netherlands) US qwerty keyboards are the default.

Also, when I lived in France, it was a matter of a phonecall to Dell to get a US qwerty keyboard instead of azerty. No problem at all. I think a colleague asked for an 'English' keyboard and got a UK qwerty, that's the only thing to be wary of.

chrizel6 anni fa

Really? So it‘s real US and not some kind of ISO English?

Yeah, I‘ve seen that Dell for example sells US BTO options in the Netherlands, but in the past (when I considered an XPS 13), dell.nl didn‘t ship to Germany. But obviously the times have changed, and it‘s much easier today to get US keyboards than 10 or 20 years ago.

Freak_NL6 anni fa

As far as I know Dutch keyboards have your basic US layout plus the € sign as a third glyph printed on the [% / 5] key. I've bought my US layout DasKeyboards from a German retailer online though.

Real Dutch keyboard layouts never took off unlike what happened in France and Germany. We're not that dependant on our diacritic characters (although I am a stickler for correct usage).

Personally, I prefer the standard US layout, because I use more than one language. For Dutch („éëè€”), English (“—”), and German („ßöüä”) the compose key does everything I need and more. For Japanese there is a dedicated IME (Anthy).

frosted-flakes6 anni fa

I wish Windows and MacOS included a Compose key by default. It's so simple that everyone could easily learn it, and we wouldn't have to deal with arcane Numpad key combinations on Windows or MacOS's super unintuitive and inconsistent symbol shortcuts.

On Windows, I use WinCompose[1], which works decently well.

[1] https://github.com/samhocevar/wincompose (Trivia: WinCompose was originally written in AutoHotkey!)

Freak_NL6 anni fa

Even on GNU/Linux distribution it is a settings that must be enabled first, but at least it tends to be present as a first-class option right from the start.

I can't stand those weird alt-codes Windows users end up memorizing. You only know those characters for which you've learned the codes. With the compose-key, you can guess anything that is diacritic character, and lots more besides¹.

I showed a colleague on a Windows computer WinCompose when she got wanted to be able to easily type a number of special characters (like en- and em-dash) without having to hunt for them in a character map or remember arcane alt-codes. She's not a developer, but it clicked instantly. Just think of a logical sequence, and get the character you want (for en- and em-dash its [compose - - .] and [compose - - -], respectively).

1: Like superscript numbers. Once you know that [compose ^ 1] yields ¹, you know ²³⁴⁵⁶⁷⁸⁹⁰ too.

cornishpixels6 anni fa

I honestly prefer just using right alt as a AltGr. Even have a custom Windows layout to re-create (parts of) the "US International (with dead keys)" layout from Linux/X/GNOME/wherever it comes from.

Instead of having to type <Compose ' o> for a ó, I just type <AltGr+o> (or alternatively, <AltGr+' o>, and similarly <AltGr+` o> for a ò)

mbeex6 anni fa

I have been using US keyboard layouts for more than 20 years. You can get them relatively easily from German online retailers, even for notebooks. I've been working with Lenovo/Thinkpad hardware for 15 years now and eventually found the US variant for each model (also because Lenovo gives exact part numbers for each variant). I also own several external Thinkpad keyboards with this layout. The only problem is that you often can't configure them when you first buy the main unit. Therefore I have a stack of German keyboards lying around here :)

cornishpixels6 anni fa

> some kind of „International English“ ISO layout with a tall return key and a short left shift key

Those exist here in the US too. They're just a lot less common. I've had the misfortune of having one, in the past. Needed a new keyboard, went to the store, got the cheapest one, came home to... "what is this layout?!"

jamil76 anni fa

From my experience working in Germany, yes but a lot of German programmers will use a US layout as it's very hard to reach the necessary brackets and symbols easily on a German keyboard.

zeeZ6 anni fa

Considering it's the default, even standard (DIN 2137:2018-12), I'd say yes most do.

SkySkimmer6 anni fa

I always use triple tilde instead, ie ~~~language code ~~~ is the same as ```language code ``` (at least on github)

Depending on your keyboard it might be easier to type.

loeg6 anni fa

Very easy on a US keyboard. It's just the top-left key, directly adjacent to '1' and below Escape. No modifiers (shift, whatever) required.

1wd6 anni fa

Wiki Creole in 2006 standardized many wiki engines on {{{ }}} code blocks. {{{#!python ...}}} for language or other extensions. All of OP's other points were also solved, at least in the most common implementation. Unfortunately people forgot about this IMO huge improvement.

tomp6 anni fa

The single biggest one-time leveling up I did as a programmer, was switching to a US keyboard. All the various symbols are just so much easier to type (except, of course, numbers should probably be shift-typed). You can still use your local keyboard for text...

ProZsolt6 anni fa

I created my own keyboard. It based on the ISO English keyboard, but when I want to type Hungarian characters I just hit the Caps Lock (or alt if I only need one character), but every other character stays in the same space. I also moved the zero before one because I needed the space for the 9 extra characters.

Coding on the Hungarian keyboard is a nightmare, I don't know how others can do it.

dirkt6 anni fa

Same for me. I have a German physical keyboard using the US layout, but with left-alt + the keys where the normally umlauts are allowing me to type äüöÄÜÖß and additionally „“‚‘ quickly.

But I've grown up learning programming on US-layout keyboards.

Carpetsmoker6 anni fa

> numbers should probably be shift-typed

I tried this for a week several years ago; it was not a success. Aside from all the muscle memory re-learning, I also found that I used the number more often than I had thought.

What I do these days just make Vim abbreviations; for example 1= becomes !=, ;= becomes :=, etc.

godelski6 anni fa

There's always these "Markdown got X wrong posts" and they seem to be very browser centric.

You know how I use Markdown 99% of the time? Vim. I LOVE that it is simple and easy to read in a text editor. I spend a lot of my time in the terminal and that's WHY I use Markdown. If I wanted fancy things that display better in a browser, I'll use something else. I look at Markdown as great because they kept it simple. I can read it easily in vim and I can have some nice features in a browser (i.e. my GitHub repos don't look like they're from 1995. But they also don't look like a Geocities nightmare).

I use Markdown to document code. I use it to keep notes. I use it to track tasks. Etc. It is my digital pen and paper BECAUSE it is simple, because I can read it in the terminal just as easily as I can read it on the web.

Keep Markdown simple.

swyx6 anni fa

I think your mental accounting of saying you use Markdown 99% of the time in Vim is primarily when you alone are concerned.

But consider also that you are "using" Markdown when you read Markdown written by others, on documentation, in a browser. A wholistic accounting would probably move Markdown higher than 1% of your time!

godelski6 anni fa

If it wasn't clear, let me be. Absurdly high numbers typically indicate exaggerations.

loeg6 anni fa

I also mostly edit Markdown in vim.

I hate that I have no idea how it will render on Github or wherever without actually pushing a test commit out, or using Github's interactive UI + copypaste to preview.

There's a bunch of command line tools and libraries implementing a variety of incompatible supersets of markdown.

Anyway, you can write Markdown-style plaintext documents without trying to conform to Markdown. The point of markdown is to be able to render those straightforward documents as pretty web pages without the degree of uglifying and boilerplate markup that HTML requires.

godelski6 anni fa

> I hate that I have no idea how it will render on Github or wherever without actually pushing a test commit out, or using Github's interactive UI + copypaste to preview.

I used to do this a lot, until I discovered Markdown Preview https://github.com/iamcco/markdown-preview.nvim

brianzelip6 anni fa

You can preview .md content using a plugin! I use this in VS Code, https://marketplace.visualstudio.com/items?itemName=bierner....

zimpenfish6 anni fa

> I hate that I have no idea how it will render on Github or wherever

Stick to PDF then since otherwise you have little to no idea how something else will render on the end user's device.

thayne6 anni fa

I also use markdown in vim a lot, and some of these "things it got wrong" make it worse, because you end up having to use html to do things like tables. or numbered lists aren't actually numbered in order, etc.

I'm actually surprised the absence of tables didn't make this list.

godelski6 anni fa

This is how I make tables

|column 1| column 2|

|:----:|:---:|

| 1 | 2 |

antoineMoPa6 anni fa

Same here, but `sed "s/vim/emacs/g"`

ddevault6 anni fa

What this fails to capture is the original motivation behind the design of Markdown. It was based on things people were already doing to add "markup" to plaintext things like emails. It was designed to just werk to convert your normal email-esque writing style into HTML. This article considers Markdown from the opposite perspective for which it was designed.

In other words, Markdown is not designed to be a simplified markup language for HTML. It's designed to make HTML a frontend for plaintext. The numbered lists with *., for example, would be totally unreadable in plaintext without context.

swyx6 anni fa

[author here] wow I didn't expect this to shoot up so quickly! Obviously I love Markdown and use it every day. But like with everything you live with every day, you notice the little things.

I @'ed John Gruber on my original tweet and readers might enjoy his response: https://twitter.com/gruber/status/1240888155307495426

juped6 anni fa

Org is a way better naturalistic markup format, with way better tooling, but it's hampered by being emacs-only and having weird devotees who like to sell it as some kind of task planning tool when really it's a naturalistic markup format.

I've never liked emacs, but I keep it around for Org, which I use most often as a LaTeX generator without all the ceremony of actual LaTeX.

lmilcin6 anni fa

I also love org but it is no replacement for Markdown exactly for the reason you mentioned. Emacs as a way of life is a no go for most developers.

I may love Emacs but I want to be able to edit my project with something else if need be (IntelliJ IDEA?) and I definitely don't want to force my users to any particular IDE. Making my project only really accessible to Emacs users just to be able to work with document files seems like a very good idea if I want to discourage them from ever looking at it.

globular-toast6 anni fa

There's nothing at all tying the org-mode format to emacs. It's a plain text format which any editor supports and syntax highlighting would be just as simple as for markdown.

loeg6 anni fa

Does any editor other than emacs support it in practice? And does the tooling around it run outside of elisp?

arh686 anni fa

There is a Sublime Text plug-in [1], but it's been a while since I used it. I think it's in Python, not elisp.

If you're just looking to edit Org files, Emacs is hard to beat. I don't use Org files so much anymore, more OmniFocus & Markdown/Sublime.

[1] https://github.com/danielmagnussons/orgmode

zimpenfish6 anni fa

I'm a ludicrously casual user of orgmode but https://github.com/jceb/vim-orgmode works for me in conjunction with the beorg iOS app.

dpbriggs6 anni fa

In practice I am not sure how true that is. There is a phenomenal ecosystem around org-mode that will require an amazing amount of work to recreate in other editors.

I haven't seem other editors get close to the convenience and integration org-mode has in emacs. For example, org-babel lets me dynamically generate entire sections of a README on github[0]:

    #+BEGIN_SRC python :results output raw :format org :exports results
    ... elided python to generate org mode ...
    #+END_SRC

Not to mention org-capture, org-agenda, or the various org-export-* functions. The deep hackiness of emacs lets this stuff just work naturally. And the quality of org-export is just amazing, especially when compared to say pandoc. I have done all of my university assignments in org-mode, augmenting with latex where required, and it just works. Same concept with my website, I have a tiny function to turn org-mode buffers into live html rendering experience with basic elisp:

    (defun make-blogging-mode ()
      (interactive)
      (toggle-word-wrap)
      (toggle-truncate-lines)
      (flycheck-mode)
      (flycheck-vale-toggle-enabled)
      (add-hook 'after-save-hook 'org-mode-export-hook)
      )

And a file hook (at the top of the org mode file so it runs automatically for me)

    # -*- find-file-hook: make-blogging-mode -*-

This isn't just a simple, context-free grammar that any other editor can emulate. It's an entire ecosystem that needs to be translated, and many have tried and failed.

Edit: Forgot to mention tables and the spreadsheet feature. Another hurdle a text editor will need to implement to recreate the experience

[0] https://github.com/dpbriggs/redis-oxide/blob/master/README.o...

lmilcin6 anni fa

For starters, org-mode is only fantastic as long as you use it with the org-mode. While there are some basic integrations with other editors none provide what is so fantastic about org-mode, which is extensibility with your own code.

Once you leave Emacs you are left with pretty standard file format with bunch of peculiarities that don't make much sense outside of their intended use.

russellbeattie6 anni fa

My firm belief is that if Markdown had never been adopted, we would have a standard way of formatting text by now supporting these 10 basic formatting types: headings, paragraphs, bold, italic, strike-through, monospace, bullets, links, images and horizontal rules. That's it. Just 10 basic formatting options.

There's no reason why, in 2020, these aren't available everywhere. Just like every text editor can understand emojis (with colors even!), these simple formatting rules should be baked into every platform by now, and easily used on everything from PCs to phones to TVs, in every editor from Vim in a terminal to email to iMessage to Wikipedia's text entry box. Just like emojis are. It's truly insane we haven't standardized this yet. How old is RTF or PDF? Doing this basic formatting in ascii text is just mind-numbingly stupid.

jhanschoo6 anni fa

At the time when Markdown was created, there were a hundred or two wiki and CMS systems each accepting a different syntax.

It seems to me that md won out because SO and reddit were using it.

I remember that I was partial to Creole when I was looking at lightweight markup languages.

If you're interested in a md-like language with more features have a look at pandoc's markdown.

clktmr6 anni fa

> Doing this basic formatting in ascii text is just mind-numbingly stupid.

Nope, ascii more or less represents your keyboard. Using ascii as user input has zero dependencies. Are you really suggesting some binary encoding for formatting, that is only possible with the respective tooling? I see only disadvantages in that.

slx266 anni fa

I tend to agree with your line of reasoning and wanted to write a blogpost about it eventually.

I implemented a "markdown-like" parser, and I noticed the biggest problem is that the edge cases are a mess, the notation is a mess, and doing efficient single-pass parsing is unnecessarily complicated (urls are also an unnecessarily complicated element that hits a parser of this kind, but that's a story for another day).

I generally agree that making special unicode characters to represent these things could go a long way into making everything easier to understand, parse, disambiguate.

To be fair, this could be tested without insane effort: unicode has a range of characters reserved for private use. Adapt a font and make a simple online editor where holding some key will make javascript generate the appropriate unicode character. We should just try it and see if it's really better.

If the concept works out well, same as we have modifier keys for alt, shift, ctrl, etc., we could use that and integrate in keyboards without much trouble. Of course, it's a big change, but I think it's being proved that there's a common set of markup needs that most platforms should handle.

And many might say: well, it's not like everyone needs to implement markdown, we can have a single implementation and re-use it. It's not such a big deal. Well, I'd argue that the right approach is make things as simple as they can be. This kind of markup is necessary, but we can make it much simpler (now someone might say that pushing more things into unicode is not a good idea, as unicode is far from as simple as possible and perfect, but that shall be discussed another day too).

echelon6 anni fa

> Doing this basic formatting in ascii text is just mind-numbingly stupid.

People have been typesetting research papers in LaTeX for awhile, and that's not much different. The beauty of plaintext is that it is easy to both read and author, and almost any tool can do the job.

> Doing this basic formatting in ascii text is just mind-numbingly stupid.

We write programs in text, and they're capable of exhibiting an unlimited assortment of behaviors.

Using a wysiwyg tool is burdensome, inaccessible, hard to automate, and doesn't integrate with the myriad of other tools we have available.

madhadron6 anni fa

Windows and macOS do carry italics, strike-throughs, and the like through copy and paste. I think it's the tyranny of the teletype emulator that keeps us doing this. After all, why shouldn't we issue textual commands to a computer in a more sane environment?

swiley6 anni fa

Unicode already has this.

ilammy6 anni fa

> Windows and macOS do carry italics, strike-throughs, and the like through copy and paste.

There is no magic, they do it by literally exchanging HTML on the clipboard. Applications use it as a lingua franca and convert the text into whatever form they use internally.

orthoxerox6 anni fa

HTML? Not RTF?

ilammy6 anni fa

I'm not that sure about macOS, but on Windows that seems to be way more prevalent in my experience (had to deal with it when worked on clipboard redirection via RDP). The format also has some additional metadata embedded into it [1]. After all, Windows applications kinda pioneered "rich text" exchange via clipboard.

[1]: https://docs.microsoft.com/en-us/windows/win32/dataxchg/html...

The format is actually negotiated by the communicating applications so it quite can be RTF too, depending on what formats the applications can produce and understand and the priorities they give to them.

jackpirate6 anni fa

Markdown supports all of those things and is the standard. So I don't understand what you mean by "if Markdown had never been adopted, we would have a standard..."

loeg6 anni fa

(As does HTML. HTML5, XHTML, HTML4.x, HTML3, ...)

slantyyz6 anni fa

> Doing this basic formatting in ascii text is just mind-numbingly stupid.

It might be today, but many of us who are older used Markdown-like formatting even before Markdown was even a thing, because on BBSes and other applications, everything in those days was plain text.

I don't know Gruber's intentions when he created Markdown, but my guess is he created it for himself first, and then other people adopted it because they think similarly.

Carpetsmoker6 anni fa

Emojis are fundamentally different, as they're essentially just codepoints being displayed. That's fairly easy to implement, as every system has been doing that for years. What you're proposing would require massive rewrites of a lot of software.

I'm also not sure it would even be better; I've never encountered a graphical editor that didn't make me want to throw my computer out the window; stuff like text becoming bold when I don't want it, adding to a list (especially with copy/paste), etc. all tends to be quite annoying and stuff I need to think about. With Markdown, I don't really need to think about the formatting, not more than regular typographic formatting anyway (paragraphs, punctuation, etc.)

marcinzm6 anni fa

Engineers like code and dislike fuzzy things with hidden edge cases. When Slack tried to switch from markdown to a UI engineers complained loudly. There's no reason to believe it'd have been any different had one of the fifty other formats that existed won out.

From a practical point of view, markdown you can diff, you can copy it around without edge cases, etc. There's a reason people use Latex rather than Word which is evident the first time you have to spend 30 minutes fighting Word's formatting edge cases.

lenkite6 anni fa

Prefer Asciidoc over Markdown. Easier to remember syntax, richer set of controls and more importantly - better tables. Tables in Markdown are a nightmare. Asiidoc is a lifesaver for tables. For big tables, columns can be specified as rows leading to sane reading.

swiley6 anni fa

I like asciidoc because latex math is part of the standard and not something you may or may not get like with markdown. There are a couple of other nice things (like tables) too.

I think the complexity of asciidoc is probably why there are only a couple implementations though, which is a real bummer.

rambojazz6 anni fa

IMO Asciidoc tables can get messy quite soon, to the point that at that point I'll just use HTML.

zimpenfish6 anni fa

Multimarkdown tables are fairly straightforward, no? From a blog post about the linear typewriters last year, a simple table (unformatted because I'm lazy.)

    input file | my score | article score | ratio
    -----------|----------|---------------|------
    stripped.txt | 5262321 | 5499341 | 95.7%
    s2.txt | 5510008 | 5499341 | 100.2%

    .Table Scores
    |===
    | input file | my score | article score | ratio

    | stripped.txt
    | 5262321
    | 5499341
    | 95.7%

    | s2.txt
    | 5510008
    | 5499341
    | 100.2%
    |===

And that's just two lines of four columns - I've got blog posts with 20 lines of 5 columns. It would be heartbreaking to type that in.

phlyingpenguin6 anni fa

I vastly prefer adoc's tables because I don't need to concern myself with aligning anything to figure out what's what.

zimpenfish6 anni fa

A fair concern. For me it doesn't work because the table headers aren't laid out the same way as the rows and that's just two ways of confusion.

sandGorgon6 anni fa

prefer asciidoc because its a well defined standard and is just as simple to use as markdown.

and yes - tables are much nicer in asciidoc

gerikson6 anni fa

I just ”shell out” to HTML for tables.

Carpetsmoker6 anni fa

HTML tables are hard to write, read, and edit though. If you want to make the document easily readable both as HTML and Markdown (quite useful for a README, I think) then it's not a very good option.

gerikson6 anni fa

I agree, I've resorted to writing Perl to generate the tables in some cases.

swiley6 anni fa

How do you make PDFs? When I’ve used html features I’ve resorted to weird tricks with WebKit but that’s really not great.

gerikson6 anni fa

> How do you make PDFs?

I don't :D

swiley6 anni fa

I wish I had that luxury.

gerikson6 anni fa

I mean, when I did have to make them I used dvips ... but that was a long time ago. And tables in LaTeX are no joke either.

cornishpixels6 anni fa

Honestly, the single biggest problem with Markdown is that it's been implemented in so many different ways by so many different people. This is largely because a lot of corner cases were simply not defined.

When a website uses Markdown for input, it's extremely tough to be sure of how to format certain things, especially when multiple different syntaxes combine. (I'm thinking of things like list+code block; or bold+italics, or list+line break, etc.)

hodgesrm6 anni fa

Markdown has similarities with CSV which is also underspecified and has varying implementations. Even simple things like quoting don't work consistently across applications.

That has not stopped countless applications from using CSV because it's so useful to have a simple transfer format. CSV corner cases usually don't hurt too badly because you can usually rule them out based on the source or sink of the data.

BerislavLopac6 anni fa

And one thing that this article gets very wrong about Markdown: It was not designed to be a structured markup syntax of any sort. The syntax, in fact, was never actually designed as such.

Markdown originated as, basically, one guy's attempt to convert instances of unofficial text-formatting convention, commonly used in text-only communication such as emails and Usenet, into HTML that can be presented on the Web. In order to do that he had to enforce some standards, while still leaving some flexibility (which is why the top levels of headings have more than one forms; both were commonly used to designate the same thing).

It was only after companies like Stack Exchange and GitHub started using Markdown as, ironically, a markup language, that there were any attempts to enforce a standard. I clearly remember a whole online "war", for the lack of better term, arguing pros and cons of standardisation.

vortico6 anni fa

About the header slugs: I don't think the content of the header should be the anchor ID. Readers will link to it, the author will fix a spelling issue or whatever, and the link will break and other readers will arrive at the top of the page when the browser doesn't find the old ID.

My solution that works with most Markdown variants is to use inline HTML to define an anchor directly before (or after) the header.

  <a id="stuff"></a>
  ### Things about stuff

But of course this isn't much cleaner than just using inline HTML for the header itself.

  <h3 id="stuff">Things about stuff</h3>

chrismorgan6 anni fa

Some tools are now allowing you to manually specify the ID in this way:

  ### Things about stuff {#stuff}

Hugo works that way by default, and I copied that syntax for Zola in https://github.com/getzola/zola/pull/685 last year.

swyx6 anni fa

as an author i'd say its rare to change headers, while its easy for the user to guess the right link if the id is broken.

careful not to penalize the 99% usecase for a slightly better 1% usecase.

ashton3146 anni fa

Shameless plug: I do 99.98% of my work in a terminal, and I'd much rather read markdown like a man page. I created a little utility to display Markdown (actually, any kind of file that `pandoc` can read) and displays it nicely formatted. You can see it here:

https://github.com/ashton314/marked-man

Hope someone might find it useful. :)

stragies6 anni fa

I use a variation of the shell-pipeline you use in your `mm` script. I don't know how to do code blocks here, so I'm pasting the un-commented one-liner

mdv () { pandoc -s -t man ${1:-"-"} |groff -T utf8 -man | sed 1,4d | head -n -4 |${PAGER:-$(DN=/dev/null; which less &>$DN && { echo "less -FRSEX"; }|| which more 2>$DN || echo cat)} ; }

from my answer here: https://stackoverflow.com/a/61029131/5208540

This is a shell function to add to your environment

mnarayan016 anni fa

> Code Blocks probably aren't necessary

When you're reading raw markdown they're extremely useful for short snippets since they save you two wasted lines per block.

Grue36 anni fa

But these short snippets are useless because you can't easily copy paste them, especially with some programming languages that are whitespace-significant (looking at you, Python). And I don't understand how triple ticks are wasted lines, because you need to surround a code block with empty lines anyway while triple ticks work straight after line break.

recursive6 anni fa

If you're using your clipboard, it's invariably going to be at the wrong level of indentation regardless. What's the correct level of indentation? 0? 1? more? There's no generally correct answer, so you're going to have to use the block indent feature on your editor anyway.

mmcnl6 anni fa

Why do these articles always pretend to be so know-it-all? I really don't like the explicit statement that "Markdown got it wrong", leaving no room for debate. For everything that Gruber supposedly "got wrong", a lot of arguments can be made for why Gruber got it "right", the author often explains that himself. That means that a lot of this is subjective. Let's keep the facts and opinion separate.

slantyyz6 anni fa

> Markdown got it wrong

You're right. The problem with the statement is that there's a presumption Markdown was created for the world at large, and I think it was originally designed for one "customer", who also happened to be the creator. Which means Markdown got it right.

coffeefirst6 anni fa

It's also weird to say "this is wrong" about missing features that there are widely-used extensions for.

greggman36 anni fa

Hmmm,

* Markdown in HTML. NO!!! That would drive me crazy. I use HTML all the time for diagrams. If I had to be aware of every tiny place where my content in the diagram was going to get munged by the markdown parser I'd tear my hair out.

* * vs - I've used * my entire life for lists, decades before markdown existed. Never heard of using - for lists until yaml

* auto numbered lists. NO!

The problem is it's nearly impossible to keep your formatting right if you have a long item lists. I often write answers on s.o. where it's like "You have 3 issues. 1. several paragraphs 2. several more paragraphs and code samples. It would be absolute hell to have to figure out the formatting to make sure auto numbered item 2 stayed 2 and didn't become 1 in a new list

* code block indentation - agreed that code fences are generally better. Worse most places I enter markdown (stackoverflow) don't have any indenting/outdenting editor controls which makes it really painful. Either I had to manually indent 5 to 50 lines or else edit outside stack overflow and paste in. I know stackoverflow has Ctrl-K but it doesn't work once you take in account the list indentation issues.

* no syntax for adding classes

I don't mind that. It kind of feels like part of the point. If I need a class I use embedded html although that's another place to rant. Inline HTML uses markdown where as self contained HTML does not. I'd prefer they both didn't. In other words. If you put

    The big <span style="color: red">*bear*</span>

you'll get a italic red 'bear' but if you put

    <div>The big <span style="color: red">*bear*</span></div>

You'll get red '<asterisk>bear</asterisk>'

Ok, I give up. no idea how to put an asterisk on HN. >:(

As mentioned above I'd have preferred no markdown in HTML as it's bitten me quite often trying to color code variables in a math description that uses * and having the * get eaten by being parsed.

* Ids - The id thing does bug me too. Markdown generates ids based on headlines but that's way too brittle. Edit the headline and your ids break. I also wish auto-numbered footnotes were a standard feature that worked by id so I could do something like [-fn-](#someid) and later #fn-someid paragraph a it would insert [<num>] at the top and link to #fn-someid at the bottom.

NobodyNada6 anni fa

> * auto numbered lists. NO!

> The problem is it's nearly impossible to keep your formatting right if you have a long item lists. I often write answers on s.o. where it's like "You have 3 issues. 1. several paragraphs 2. several more paragraphs and code samples. It would be absolute hell to have to figure out the formatting to make sure auto numbered item 2 stayed 2 and didn't become 1 in a new list

I think you and the author agree on this point: Markdown does have auto-numbered lists, and the author of the blog post believes that was a design mistake. If you write a Stack Overflow post with a list numbered 3, 2, 1, it will be rendered as 3, 4, 5.

scelerat6 anni fa

Markdown drew its influences from predecessor structured text languages whose goal was minimum formatting of ASCII text in a structured way such that it could be parsed and re-rendered into any other format.

The goal was simplicity and readability in plain-text email and Usenet posts so I'm not surprised that fifteen years from its inception, and thirty or more years on from some its antecedents, we're using text and thinking about how we use text differently. One of Markdown's pivots from setext was the addition of code blocks. In the environment that setext was created, a code block would simply be rendered much like everything else: in the plain and probably fixed-width display that your email was also displayed in. By 2004, email had rich formatting, Usenet was on the wane, and people still needed a lightweight text format to share. Markdown filled that need, as did a number of other similar alternatives, though I forget their names.

My first exposure to such lightly-formatted ASCII was setext [1] which was the format chosen for the Mac- and Apple-oriented TidBITS email newsletter [2]. As a contributor to that newsletter, Gruber would have been intimately aware of the format.

Twenty years ago, I used setext in code projects basically the same way as nearly everyone uses Markdown now. I like OP's suggestions though I've always liked the 'lazy' approach to ordered lists.

[1] setext: https://en.wikipedia.org/wiki/Setext

[2] TidBITS: https://tidbits.com

foolfoolz6 anni fa

i actually disagreed with a lot of these. markdown is opinionated. the feature set is limited. the output looks almost all about the same. this is the goal.

no one wants the myspace outcome of simplifying messages. you usually don’t need much styling but the tools that markdown includes are good enough. if you need more you probably want to ask why you’re writing in a place that only accepts markdown

slantyyz6 anni fa

> markdown is opinionated.

This. If I were to guess, Gruber made Markdown to make writing for his blog easier. Then he made it available for whoever wanted to use it too, which was very nice of him.

Given how there are already multiple flavors of Markdown available that address various shortcomings, I don't know if there's a point to critiquing Gruber's original version of Markdown since it was likely created to satisfy his writing requirements first and foremost.

boublepop6 anni fa

So are you saying that you disagree with the current “hmtl as superset” version of markdown? Or are you saying that it’s good that he didn’t go all the way and support markdown-in-html-in-markdown because the halfway point makes it perfectly half usable for the point of having html in the first place?

Markdown is great but there are some minor points where it fails spectacularly with only minor tweaks needed to improve it tremendously. Also code ticks at its point to most are just considered part of “standard” markdown.

okapii6 anni fa

You create empty lines by adding two spaces at the end of lines. MD has invisible syntax. To me this without doubt is the worst thing about MD.

SeriousM6 anni fa

Things it did right: It was the right tool at the right time. Everyone knows it and can use it. It's like Javascript for documentation.

wackget6 anni fa

There's also no way to create vertical tables with headers on the left:

https://stackoverflow.com/questions/60995936/vertical-table-...

brianzelip6 anni fa

> There's nothing I hate more than reading a good article with headers, wanting to link someone directly to the section relevant to them, and then not having an id to use to send them straight there.

Lots of other things I hate more than this, but dagnabit this drives me nuts too!

Already__Taken6 anni fa

The second you want to do code and images on a page I just spend all my time fighting whatever markdown workflow is in place. Which would be fine if it added anything but they never just work, you still need to do your own image optimisation and aligning images or custom layout sections is terrible or not possible.

Markdown is harder to work with in the long term than just wiring HTML with Emmet. That's my opinion a few years ago and these days I'd double down on it as editors are so good.

Tables suck in everything so we should standardise a json and/or csv import language to drop tables in a built time anyway.

Markdown is good for notes. Even mermaid diagrams are kind of unpleasant to write.

jdeisenberg6 anni fa

Yes. At times I would like to be able to use italics in a code block to emphasize some portion of the code, and that seems very difficult, if not impossible, to do.

I realize this would conflict with automatic syntax highlighting, which is probably why it is not allowed.

KKPMW6 anni fa

Some of those things are addressed in my favourite markdown variant - multimarkdown https://fletcher.github.io/MultiMarkdown-6/MMD_Users_Guide.h...

The author has found a sweet spot between being very conservative with the original declarations and adding the missing functionality. It also comes with an amazing lightweight implementation written in C that behaves correctly: gets input from stdin or a file and passes it to stdout, without the -o flags that (e.g.) pandoc is using.

suref6 anni fa

I'm currently working on a markdown system where I wanted to extend codeblocks to be able to incorporate more information. The `js:title=example.js` just doesn't cut it. Want I landed on was some sort of yaml-ish format:

    ```
    ***
    property1: ...
    property2: ...
    ***
    code
    ```

This way multiline properties are supported and I can also incorporate markdown inside the properties themselves.

pm906 anni fa

I was turned on to ReST by a coworker and prefer it over Markdown. Aesthetically ReST code seems easier to read in raw form; and it’s somewhat more predictable in what works and what doesn’t because bad reST code breaks.

jesse_m6 anni fa

I can't stand the invisible syntax like double trailing space.

chrismorgan6 anni fa

reStructuredText on these, for anyone that’s curious or thinking about it:

1. If you use “5.”, it’ll give you a five. If you want auto-numbering, use “#.” as your prefix. (While I’m thinking of it: I hate that using actual Unicode bullets like “•” doesn’t work in Markdown, and that in https://talk.commonmark.org/t/unicode-character-bullet-u-202... it’s been actively rejected for CommonMark.)

2. Code blocks are by indentation only, no fencing, but avoids confusion about indentation levels by defining all of that stuff properly and having it match visual usage, rather than Markdown’s crazy “four spaces, but in certain situations we’ll let you get by with 3, 2, 1 or even 0—but if you then seek to nest, remember to bump it up to eight rather than just N+4”. Code blocks are indicated by `::` at the end of or as the entire previous paragraph, which is esoteric, but also fits in very well with its directive syntax, which is how you can attach extra metadata to code blocks. It’s definitely not as simple as the newer Markdown fencing approach, though it fits into the rest of reStructuredText in a sane and principled way so that it’s not at all hard. Still, I think that a new version of reStructuredText would quite possibly include fencing in some form—or maybe directives would be resyntaxed to be able to be fenced rather than indented, though achieving that while still allowing nesting would take care.

3. Markdown in HTML in Markdown? That Markdown extends HTML is the real problem here, and is both its greatest strength and help in adoption, and its catastrophic weakness. reStructuredText is a language of its own that doesn’t extend anything, so that style of HTML output is typically done by defining new directives, which can then contain reStructuredText. It’s strictly less powerful, but it composes way better. As a workaround, the `raw` directive lets you put in arbitrary HTML (or LaTeX, &c.).

4. By deliberately not being HTML, reStructuredText handles this sort of thing much better. Each node in the document can have classes (which will end up as class="…" in HTML, something else in LaTeX, &c.). You can do things like `.. class:: …` to apply a class to the next block (heading, paragraph, list, &c.). Most directives support a :class: option. You can define new roles so that :classname:`…` will do what you desire. And none of this is then tied to HTML.

5. reStructuredText lets you define anchors at any place in the document (which can also be used for index entries when writing books or things like that). `.. _anchor-name:` above the heading will do it thus. This protects you against the anchor changing (and thus breaking links) if you change the text of the heading. Any form of automatic heading ID generation is left to the software to decide, e.g. Sphinx generates IDs by default.

6. Field lists. A field list at the start of the document is treated as document bibliographic data, and you can put anything in there you like.

I myself prefer reStructuredText in almost all regards, but I scarcely use it any more other than for a couple of types of personal documents, because of the ubiquity of Markdown. It was similar with Mercurial and Git.

1wd6 anni fa

Agree. reStructuredText has much stronger concepts. Composable. A standard way to extend semantics without requiring new syntax. Not tied to HTML. It has some slightly more superficial weaknesses that made it the loser I guess: ugly / awkward / inconvenient syntax; no atx headers; not every document is "valid"; HTML is less integrated... worse-is-better strikes again.

jurip6 anni fa

It's weird how both ReST and Markdown stumbled on that indentation thing. And ReST has the awkward header underlines, too. Both of those are annoying at the best of times and basically unusable with proportional fonts (and we're dealing with prose here, where there should be no reason to force people to use monospaced fonts if they don't want to.)

If I'm ever involved in designing a syntax like that, the first hard and fast rule will be that the user should never have to count anything, especially in relation to anything else.

chrismorgan6 anni fa

reStructuredText is very committed to the plain text visually matching the formatted. For headings, visual underlining makes sense in that context. And code is conventionally indented, so it also makes a lot of sense. (Blockquotes are indented as well, differing from code blocks by the absence of `::` at the end of the preceding paragraph; indentation again matches conventional appearance. But that’s a place where I get where Markdown’s coming from, using > indentation like in emails.)

In more recent times, convenience of writing has become a more important concern to people, because these formats have shifted from niche use by dedicated people in real text editors that would like what they see to match the end result fairly well, to mainstream use in textareas and similar, and sometimes even WYSIWYG editors. That’s what’s driven people to prefer the convenience of code fencing, because indenting each line in a textarea is a pain. Ditto on headings. If reStructuredText were being redone now, I think it’s fair to say that prefix rather than underlined headers would be at least an option. It would just remain to be seen whether they went with `###` meaning level 3 even if there was no `##` or `#`, or whether they’d boost it up to level 1 or title, as appropriate.

wmu6 anni fa

A thing for people not familiar with reST: check out ASCII-art tables - https://docutils.sourceforge.io/docs/user/rst/quickref.html#... :)

jesse_m6 anni fa

I can't stand the invisible syntax like a double trailing space is some valid syntax.

andrew_6 anni fa

TL;DR - "Markdown is too simple for me, I'd like it to be more nuanced"

I'm not saying that to be cheeky. The article can be boiled down to that because the author is looking for HTML features in Markdown, when there's very little need. e.g. we don't need classes in markdown and we don't need IDs or `name` attribute specifiers because that can be accomplished already by mixing in the HTML that one needs.

kerkeslager6 anni fa

I agree with some of this (i.e. the numbers), but I think it's coming from a place of not understanding what Markdown is for. For example, your complaint about indentation for code blocks makes no sense if you're using Markdown appropriately.

The original idea was to take emergent syntax used by text file authors as cues for humans reading text files, and use that as a syntax for generating HTML, so you could use text files as the source of truth for generating HTML.

Backticks aren't an emergent syntax used by text file authors as cues for humans reading text files--that's a syntax directly intended for generating code blocks in HTML, with little semantic value if the markdown is going to be consumed as text.

If your goal is to have something consumable as both text and HTML, then some sacrifices have to be made, because text simply can't do everything that HTML can. The error-prone indentation syntax is just a compromise, but there were features that were left out completely. The original markdown didn't contain underline or strikethrough, for example, because text can't do those things.

The problem is that for a few years, this idea turned out to be useful as a way of allowing users rich text editing capability on websites. So people wanted Markdown to do everything that HTML could do, hence we get underline, strikethrough, code fences, etc. This hurts use cases where markdown is used for its original purpose, because modern markdown isn't as nicely consumable as text files, but users didn't care because they weren't using Markdown to be consumable as text files. And this made sense for a while.

And where this becomes stupid is that if you don't care about it looking nice as text, then you shouldn't be using Markdown. There are a wealth tools for rich text editing on the web (TinyMCE being the most obvious choice, but not the only one available) and they're FAR superior in user-friendliness to Markdown. Many actually support Markdown, but there's less and less reason to even expose that functionality to your users. If you don't care about how your Markdown looks as text, then just use HTML and edit it with a rich text editor.

There's another use case where you want to compose HTML content without the overhead of actually writing HTML, but you want to "do it like a coder", so using a rich text editor isn't appropriate because you want to be able to diff and whatnot. But in that case, there's still no reason to be using markdown, because if you're "doing it like a coder" than you can just write code which makes what you're doing much clearer, and give you a lot more power. Textile, Org-Mode, LaTeX are all better options.

GitHub has persisted in using Markdown well past the advent of mature web text editors, because they still seem to be operating under the illusion that nontechnical users will become a significant part of their user base. Slack and Reddit are both moving toward fully rich text, and the fact that they are still trying to expose their Markdown roots just makes their rich text painful to use. MediaWiki using their markup language still, probably because they are blocked by the enormously difficult task of migrating an enormous amount of content, but if you're starting a new project, you don't have any of the tradeoffs that these organizations do, so you shouldn't make the mistake of following in their footsteps.

RMPR6 anni fa

Typo

> differnt types of content.

battery_cowboy6 anni fa

Kinda on-topic (50/50): I'm looking for a flavor of something-like-markdown, but it would have semantic tagging and some abilities to add my own attributes to an element/tag (like for links, I want to be able to specify some to open in another tab, but others to open in the same tab, I'm willing to do that with raw attributes if I can add them on) for conversion to HTML in a static generator, is there something like that anyone knows about? (I prefer not to "roll my own" if I can use a standards-based language)

For instance, I'd want to do the example in the GitHub flavored markdown with tags like <article> or <aside> around markdown-like syntax. Markdown is so easy compared to HTML, so I want that ease in my article-writing workflow.

I was considering using HTML directly in a templating language, but I want it to be a more human-friendly text format, like Markdown.

aib6 anni fa

Have you seen Pandoc[1]? I'm not sure it supports the particular cases you've stated, but I've been using it happily as an HTML generator[2].

1: https://pandoc.org/MANUAL.html

2: https://www.aib42.net/articles source at https://github.com/aib/www.aib42.net/tree/master/articles

battery_cowboy6 anni fa

I'll look at it thank you

Eugeleo6 anni fa

You could try Pollen [1]; there’s a little bit of setup, but you can generate beautiful webpages in it. It even has a markdown dialect, in which you write most things in markdown, but you can also add your own custom tags.

[1]: https://docs.racket-lang.org/pollen/

battery_cowboy6 anni fa

Thank you I'll check it out

dpbriggs6 anni fa

This can be done in Org files using text source blocks with `ATTR_HTML :target _blank`

https://emacs.stackexchange.com/questions/14320/org-mode-lin...

battery_cowboy6 anni fa

Thanks, I'll check Org out

arve06 anni fa

markdown-it [1] has a number of plugins that let you add extra features to commonmark. For adding attributes, I wrote markdown-it-attrs [2]. Combine that with a flexible static site generator, like metalsmith [3], and you have a solution adjustable to your needs.

1: https://github.com/markdown-it/markdown-it 2: https://github.com/arve0/markdown-it-attrs 3: https://metalsmith.io/

battery_cowboy6 anni fa

I intend to use this setup, modified a bit, it's pretty much just what I was looking for: a very modular static generation tool that still uses a language I can read easily before generation, even if it isn't a 100% standard/stock language.

I was running into issues where some feature idea I had (ex: a way to expire an article based on some "code", like a function to check if Debian 10 is EOL yet in an article on how to install Debian 10) wouldn't be supported by my static generator, so I wanted to write my own or fork it, but instead I can just write modules for metalsmith or markdown-it for different features I need, it's perfect.

battery_cowboy6 anni fa

Thanks I'll check it out, it sounds kinda like what I'm looking for overall

oever6 anni fa

Adding ids to parts of the text and then embedding Turtle in ``` regions would go a long way to making that possible.

battery_cowboy6 anni fa

I'm not sure I know what you mean. Do you have an example?

oever6 anni fa

Sure. Here's some Markdown with Turle.

    At 10pm I had a call with [#karl](Karl).

    ```turtle
    @prefix p: <http://example.org/person/>
    @prefix r: <http://example.org/relation/>
    @prefix owl: <http://www.w3.org/2002/07/owl#>
    
    p:karl owl:sameAs <#karl> ;
        r:author <http://example.org/books/NestOfTriples>
        r:friend p:pat
    ```

thayne6 anni fa

have you looked at asciidoc?

battery_cowboy6 anni fa

I will do that, thank you for the suggestion

freepor6 anni fa

People put too much behind Markdown is what happened. It was just a random idea on a blog post. But people made it a universal authoring standard and it is just not up to the task.

blackrock6 anni fa

Markdown has been a godsend.

It’s just what I wanted. Something text based, where I can sorta control some formatting, but isn’t tag heavy like HTML.

I just need it to format a few things, to make it easier for myself to consume later.

The most useful for me is actually the syntax highlighted code blocks.

I use it mostly for brain storming, planning, and scratch work.

jimmaswell6 anni fa

What was even the motivation in the first place to not respect newlines?

kccqzy6 anni fa

I assume you are talking about the fact that adjacent lines are merged into a single paragraph.

Have you written traditional plain text emails or write any plain text documents? You almost always hard wrap your lines for readability. Even in HTML, newlines are mostly equivalent to just spaces.

Carpetsmoker6 anni fa

This is also very advantageous in diffs; diff-ing a Markdown file with many 1000+ character lines is rather hard.

jimmaswell6 anni fa

When does a markdown line get that long?

Carpetsmoker6 anni fa

When people write it like that?

karmakaze6 anni fa

What's even worse is to insert newlines, you use invisible markup that will often get removed depending on editor settings:

"When you do want to insert a break tag using Markdown, you end a line with two or more spaces, then type return."[0]

[0] https://daringfireball.net/projects/markdown/syntax#p

Carpetsmoker6 anni fa

You can just use

Someone6 anni fa

If the first word after the newline wouldn’t fit on the last line before the newline, you can’t see whether there is a newline.

Also, since you don’t know window width, that can happen even if, on your terminal, the last line of a paragraph is only 3 characters and the first word of the next is “A”.

jakear6 anni fa

Hot take (maybe): GitHub flavored markdown is the ideal markup language. If the author’s ideas were actually better, we’d use them instead.

It supports code well, it supports non-enumerated lists well, it supports enumerated lists well (if you don’t want view it in rendered markdown, you can view the raw and just disregard the numbers, understanding that the items are supposed to be sequential). It supports links well. It supports images well. It’s easily readable, even with no prior context (@toml, yaml, etc.).

It does whatever a static website could want, and it does it all decently well.

judge20206 anni fa

People tend to use whatever they have to use to be on a platform since these different parsers aren't portable. Everyone is on GH for the code hosting, getting a markdown editor that works is a bonus. If you go to any other community that uses a different markdown standard or even something that's not markdown, people will be using that - not because it's better than GH flavored markdown, but because that's what's available.

ComputerGuru6 anni fa

Not true in the slightest. I used for periods of my life StackOverflow, Jira/Confluence, and bbcode exclusively and hated interacting with each of their markup languages.

b0rsuk6 anni fa

Github supports reStructuredText just fine. You can even display images in Readme without any extension, just a plain image directive.

beart6 anni fa

Yes the author praises GitHub flavored markdown. The criticisms presented are on gaps in the original markdown design, not implementations.

swyx6 anni fa

author here. yup. tried to make that clear by constantly referring to Gruber's spec. A few years ago I didn't even know there were different flavors of markdown. Fortunately/Unfortunately Gruber's is the one that stuck and is universally accepted by all markdown tooling, hence it is now the lowest common denominator we must work with.

arve06 anni fa

Have you seen the commonmark standard? Did not see that mentioned. https://commonmark.org/

dpbriggs6 anni fa

I think we're using it because GitHub renders GitHub flavoured markdown well.

Thankfully it also renders Org files pretty well, which AFAIK supports everything listed and more.