`````ts
const Accordian = styled.details<{ isAprilFirst: boolean; }>`
````css
accent: rebeccapurple;
font-family: ${
```js
props => props.isAprilFirst ? 'Comic Sans' : 'Time New Roman'
```
};
````
`;
`````CommonMark is a comprehensive specification which also has a reference implementation and a test suite.
I sometimes wonder... is it Markdown's specification chaos the reason for its success? Maybe it was just barely enough spec to be usable but also small enough to allow anyone to make an implementation that seemed right. No qualifications to fail. Thus, it proliferated.
The xkcd[1] problem is a darn shame, though. At least CommonMark exists for people who want to point to a "Standard"
But ya, in order to look good in source form, but still handle arbitrary content, they had to add all these little exceptions and corner cases.
1. People have a hard time remembering the order and which characters to use. The most common error I see is (text)[href]. Spaces in between the [text] and (href) is also common.
2. ( and ) are URL code points: they can exist in URLs without being percent-encoded. This means that you can’t just paste or emit regularly serialised URLs, you also need to change any ( to %28 and ) to %29.
To fix it, you start out by using <> to delimit the URL instead of (). This fixes the serialised URL problem (< and > aren’t URL code points), and it was the traditional delimition of URLs too, where delimition was required. You could say that () was common too, but I’d argue that was just normal linguistic parenthesis rather than URL delimition. Markdown even uses <> as URL delimition already, but only for links with no custom text (called “automatic links” in Gruber’s definition, “autolinks” in CommonMark): “https://example.com” is just text, “<https://example.com>” makes it a link.
As for the way of adding a title attribute to a link, that shows that the parentheses aren’t even actually delimiting the URL. And then you get into the mess that’s […] and […][…], in addition to […](…). It’s an ill-considered mess.
2. I guess that’s fair. I think parentheses in urls are a bigger issue than parentheses in markdown though. Parentheses in urls often end up percent encoded whether they need to be or not.
> You could say that () was common too, but I’d argue that was just normal linguistic parenthesis rather than URL delimition.
Right. I would say that markdown is inspired more by linguistic styles than markup styles.
You certainly could use <>, but I actually don’t think that matches the way people usually write urls in non-markup formatting. I find it interesting that Gruber chose to use that for autolinks, though.
I do appreciate you clarifying. I see what you mean, at least with respect to all the issues around #2. The more I use markdown, though, the more I come up appreciate this format, specifically because it’s so readable as text. I think it’s a reasonable trade off.
There is a solution: restructure it so the href part is inside the link, rather than adjacent to, which is the real problem. reStructuredText had `text <href>`_. In that form, the trailing underscore is a wart, but there’s more justification to it than it may initially seem (where Markdown can have [text] or [text][], reStructuredText’s equivalent is text_ or `text`_). For my own lightweight markup language, I’ve been using [text <href>] for a couple of years (and had {text <href>} before that).
> Parentheses in urls often end up percent encoded whether they need to be or not.
That’s what you can expect from something implementing RFC 3986; but these days, almost everything uses WHATWG’s URL Standard <https://url.spec.whatwg.org/>, under whose rules parentheses are not percent-encoded.
> I actually don’t think that matches the way people usually write urls in non-markup formatting
It isn’t any more, but it used to be very common.
> under whose rules parentheses are not percent-encoded.
I don’t know. I feel like half the time I end up with parens encoded. I’ll have to keep an eye on it. Maybe that behavior isn’t common anymore.
> [urls identified with <link> in plain text] used to be very common.
I don’t recall this being common but it’s possible I’m just not remembering.
Otherwise, it is a relatively smooth writing experience. Much better than word, asciidoc, or latex.
An alternative would be to simply use square brackets for both clauses of the link.
> The details can be found at my website (https://example.com).
The problem with this is that if you want to render this “pretty”, there’s no way to know whether the link should be “my website” or “website” or even the whole sentence. So you add brackets to clarify.
> The details can be found at [my website](https://example.com).
There are certainly alternatives but I don’t think any of them are more natural, or memorable for that matter.
Edit: It took me a re-read to fully understand your comment, I can see how square brackets might be an incremental addition. This may also help remember the syntax, thanks!
AsciiDoc doesn’t actually have a real link syntax—what it has is more or less an natural consequence of other syntax choices, but isn’t actually URL-aware, and will mangle some less common URLs. Still, what you get is mostly this kind of thing:
• https://example.com[Link text]
• link:URL[Link text]
But woe betide you if you go beyond what it supports, its techniques when you need escaping are grotesque, monstrous horrors. Seriously, when you fall off the happy path, AsciiDoc is awful.
The big issue isn’t specifically that markdown is wrong or right but that all these different systems are very inconsistent.
For comparison, Org-mode uses [[LINK][DESCRIPTION]] instead of [DESCRIPTION](LINK).
It seems that in the HTML 5 age there is some subset of HTML which should be completely satisfying for anyone. Maybe it is custom components that work like JSX (e.g. <footnote>) or something like tailwind. Editing HTML with one eye on a live view is more pleasant for me than anything else. Every kind of rich editor that looks like Microsoft Word (esp. Word!) comes across as a dull tool where selections, navigation, and applying styles almost work. There's got to be some kind of conceptual problem at the root of it all that makes fixing it like pushing around a bubble under the rug. I want to believe in Dreamweaver but 2-second latency to process keystrokes on AMD's best CPU from 2 years ago and the incredulous attitude Adobe support has about the problem makes it a non-started [1]
[1] if I ran an OS failing to update the UI in 0.2 sec gives an immediate kill -9 and telemetry of the event will get you dropped out of the app store not much later. I'm not saying rendering has to be settled in 0.2 sec but there has to be some response that feels... responsive.
Be glad they didn’t adopt Everything2’s “pipe link” syntax: [link|url]. Or maybe it was [url|link]? It’s been well over two decades, I don’t remember anymore.
Loosy goosy is fine for a hobby project but if you do anything with vanilla Markdown beyond simple links, headings and text, you quickly find yourself in a frustrating zone of incompatible hacks and syntax extensions.
https://news.ycombinator.com/item?id=8271327
I generally like John Gruber and have been a DF reader for years, but I really never understood his perspective on this; I have trouble seeing it as much more than a "worse is better" kind of take.
All these complications would have been avoidable with a more thought through design/better choices of symbols. For example one could have used brackets:
[[[lang
code here
]]]
[[[html
html code
[[[css
css code
]]]
[[[js
js code
]]]
html code
]]]
In a parser that would be much simpler to parse. It is kind of like parsing S-expressions. There is no need for 4 backticks, 5, or any higher number. I don't want to sit there counting backticks in the document, to know what part of a nested code block some code belongs to. It's a silly design.
The complication doesn't stem from lack of distinct start and end, what you are trying to solve for here, is when you have multiple languages in a single block, and want pretty colors on each. Seeing that HTML doesn't support imbrication of pre tags (or rather doesn't render one embedded in the next), that would probably not work without producing something that is not pure html.
> In a parser that would be much simpler to parse
Parsing a variable number of ` is not more complex than looking ahead for a closing boundary. In fact, once you introduce escaping characters, you need to handle escaping of the escaping character, which is slightly more complex.
Which is quick and easy to understand.
Sometimes you want to paste a large region of code into a code block, and escaping the content is harder than fixing and start and end delimiters. This matters particularly in Markdown, where embedding large regions of code or text is common, whereas other languages you’d put it in its own file.
So I still suggest the ability to change the number of open and close brackets. Then you’ll also need an implicit newline or other way to distinguish content that starts with an open bracket.
The classic way in markdown to insert block of code is to indent the code.
Indenting inline code requires a text editor that makes indentation ergonomic or else extra effort per line; and it doesn't mesh well with lists or block quotes.
I always used html elements like <pre /> and <code /> to go around this in the past
Solved it by surrounding code with more ticks than maximum number of consecutive ticks inside its text. This allows arbitrary nesting.
Postgres solves it by using `$something$ whatever $something$` [2].
[1] https://github.com/PratikDeoghare/brashtag [2] https://www.postgresql.org/docs/current/sql-syntax-lexical.h...
So, the same thing that Markdown does, as described in TFA?
https://learn.microsoft.com/en-us/dotnet/csharp/language-ref...
Unfortunately, some markdown implementations don't handle this well. We were looking at using code-fence like syntax in Rust and we were worried about people knowing how to embed it in markdown code fences but bad implementations was the ultimate deal breaker. We switched to `---` instead, making basic cases look like yaml stream separators which are used for frontmatter.
Actually, yes, now you know for a fact that none of the Markdown implementation will render it correctly.
So, I guess, they used `~~~` instead and it was an error in OP post.
For anything more complicated, just give up and use html
blah
#+END_SRC
org-mode to the rescue ;p