Everyone uses an editor? No no no no… 1000 times no. I hate WYSIWYG editors and what thei represent. Putting formating ahead of content was an horrible idea that tends to survive in the heads of many, while at the same time it already has been proven conter productive anyway.
Markdown is human writable, and could be adopted by the masses for example on messaging apps, social media, etc. If people are introduced or forced to use it at work or school.
Bbcode was very popular in the 2000s and webforums broke through in popularity well beyond techies.
What if students had to make their written school assignments in mark down? Is it such a complicated thing to ask the? In which way is MSWord any simpler? It’s not!
If you need to include tabular data, markdown is hard, IMO. The original markdown required you to just write HTML for them, which was no picnic. None of the dialects that have evolved since then are anywhere near as easy as editing a table in Word. And I say this as someone who intensely dislikes Word.
I like writing in markdown, using a plain old text editor. But when I need to insert a table, I use visidata to edit and export github-flavored markdown. I don’t mind it, because I appreciate the other benefits of markdown. I could not claim, with a straight face, that it’s as easy as a WYSIWYG editor would be for creating the document.
(Also, FWIW, markdown has been adopted on discord, and I think most matrix clients do the right thing with it too.)
I wrote my own Markdown/ORG mode markup language for my blog. The one thing I do not do is store the posts in my markup language, but the final HTML render—that way, I’m not stuck with whatever syntax I use forever (and I’ve changed some of the syntax since I initially developed it). Also, for tables, I use simple tab-separated values:
#+table Some data goes here
*foo bar baz
**foo bar baz
3 14 15
92 62 82
8 -1 4
#-table
Whitespace are tabs, the line starting with the asterisk is a header line; the double asterisk is the footer. This handles 95% of the tables I generate, and because I store posts HTML format, it doesn’t matter much that it looks a bit messy here.
I think most people don’t get what John Gruber was trying to do—make it easier to write blog posts.
“Putting formating ahead of content was an horrible idea that tends to survive in the heads of many”
I use Emacs and Org-mode but I have never understood the insistence that those who use anything from LaTeX to Docbook to Markdown are separating content and structure.
Oh, how I tried to learn LaTeX until it smacked me in the forehead that I had to complie a document!
Anyone who types #header ##subheading * bullet while typing (or using autocomplete) is thinking about format and structure while producing content.
I loathe word processors but creating a template makes it just as easy to seperate content and structure. Even back in the 90s on USENET and other pure plaintext forums, or RCF’s that matter, it was commonplace to insert ASCII tables and /emphasis/, like I am now with * and /s.
Nothing has ever stopped anyone from treating a screen like a typewriter or pad of paper and just writing and writing and writing and come back later to add structure and formatting.
Writing is writing. Editing is editing. Typesetting is typesetting. The only difference now is we all have to do all three, but nothing but our minds prevents us from doing them separately.
Agreed. The only WYSIWYG editor I’ve ever enjoyed using is TexMacs, despite it’s strange window/buffer approach and bugs. I wish every WYSIWYG editor learned from it. The vast majorty of them are a complete nightmare. I want to throw my computer every time Slack’s new WYSIWYG message box screws up my formatting.
I think they underestimate how many young people use discord and markdown for formatting their text.
there’s no modern semantic elements such as main, article, section, nav, header, footer, figure, picture
Well yes, but also, I don’t need that in reddit or discord. And the places that do need it, are better off doing said post processing. Also I’m very glad that I can actually use it instead of a badly behaving WYSIWYG editor (looking at you reddit trashfire that ate my text too many times). Same goes for github/gitea/gogs/gitlab entries.
It’s a modern BBCode for “forums”, which is also better in being readable without rendering.
What Markdown does not do is probably more important than what it does.
This. Markdown’s strength is that it doesn’t try to be all things. There’s a megaton of content in the space that sits between scientific paper / book scale organisation, and, well, let’s go for tweets as an example at the other end of the spectrum. What Markdown does really well is cater for that content. If anyone is going to argue that Markdown isn’t good enough, I’ll ask them to show me how many tools they have in their toolbox, and if there’s more than one, their argument is bunk.
Also: WYSIWYG is tremendously overrated and I’d argue that in some circles it has hindered content creation rather than supported it.
Finally: I can’t help but smile to see the Markdown formatting available just winking at me below this textarea input box in Lobsters.
It might be a shame, but it’s a predictable consequence of the fact that org-mode doesn’t have an independent implementation that most people can use. Markdown had a simple perl program that you can call from a makefile or any sort of script to render your text to html. These days there are loads of libraries to choose from, to render on the client, server, GUI, etc. dynamically.
I strongly agree. And that is still a little disappointing, because org-mode was so well suited for that kind of thing. org-babel had so much potential for literate programming. I wish that had broken differently.
While I appreciate Org mode’s outlining features, Org mode’s syntax has some limitations that make me glad it didn’t catch on.
Code is clunky to mark up.
Block delimiters are #+BEGIN_SRC javascript and #+END_SRC instead of Markdown’s ```javascript and ```. That syntax uses three different punctuation characters – it’s hard to remember and type.
I bet that most authors type that syntax with the three keystrokes <s Tab (using the sstructure template), but that only works in Emacs.
The inline code delimiters ~#example~ are harder to visually distinguish from code than Markdown’s inline code delimiters `#example`.
It is difficult to escape special characters. (I was going to write that Org mode did not support escaping, but I just discovered the manual page Escape Character.)
Org mode’s escape character is the zero-width space ‘’, which is harder to type, read, and edit than Markdown’s backslash ‘\’.
I can’t tell from the manual whether an escaping zero-width space will still appear in exported HTML. If so, then there is formatted text that is impossible to write in Org mode. In comparison, Markdown’s escaping backslashes are never in the output, and even if you think you’ve found something you can’t write, Markdown can fall back to inline HTML.
It’s inconsistent whether you have to type the zero-width space before or after a special character to cancel it out. In Markdown, the backslash always goes before the special character.
The key benefit of Markdown is that it’s readable as plain text. I can write docs in a repo in Markdown and they are comprehensible both as text and as rendered HTML / PDF / whatever.
Compare the input:
This is my top-level heading
=====================
This is some text.
Now a subheading
-------------------------
1. First a numbered list
2. With some stuff
- okay, and a bullet
- Here we go
To the output:
This is my top-level heading
This is some text.
Now a subheading
First a numbered list
With some stuff
okay, and a bullet
Here we go
Either of these is fine for a human to read (though the bulleted list shows a bug in the Markdown parser that lobste.rs uses, which is part of the author’s point). That’s a property that most other document markup languages lack. DocBook is far more powerful but the source is painful to read. AsciiDoc is a bit more readable but is still very verbose in comparison.
The real problem comes when you want to write content in Markdown that goes beyond what Markdown can express.
That’s more readable than the AsciiDoc that I’ve seen, perhaps I was looking at things that used a lot more advanced features. I find the underlined headings in Markdown a lot more visually distinct in plain text than the prefix version (in Markdown and AsciiDoc), possibly because I was used to them by the early ‘90s in plain text docs. The numbered list in Markdown is a lot better. Consider a paragraph of text that refers to point 5 in a list. With the Markdown version, I can jump to that when reading far more easily than if every line starts with a dot. This is also useful in editing: I’ve written LaTeX where I’ve referred to the wrong number in an enumerated list because I didn’t correctly count the number of \item lines, but never done that in Markdown.
The drawback with setext headers is that they look best in monospace. Putting exactly that many underlining characters. (Your example a few posts up that didn’t do that looks kinda weird.) Atx headers work* in proportional fonts too, so that’s why I prefer them.
And many monospace fonts aren’t actually monospace. I found out the hard way with maTeXt (if you look at the rendered math with your browser, it’s likely to appear broken, even though it looks fine in a terminal, where characters are forced to align properly).
I don’t really care about extensibility if it means every time I want an in-line code block with part or all of it linked to another document I need to write my own role. Not supporting nested in-line markup is just brain-dead.
It was a more robust and better designed option, retaining the essential same mindset as markdown. It is unfortunate that markdown won the popularity contest. But marketing and hype dictated the outcome.
Markdown is a text-to-HTML conversion tool for web writers.
The overriding design goal for Markdown’s formatting syntax is to make it as readable as possible. The idea is that a Markdown-formatted document should be publishable as-is, as plain text, without looking like it’s been marked up with tags or formatting instructions. While Markdown’s syntax has been influenced by several existing text-to-HTML filters, the single biggest source of inspiration for Markdown’s syntax is the format of plain text email.
Gruber never intended MD to become the be-all and end-all of authoring. In fact I think that’s why he didn’t let CommonMark use the Markdown name.
Yes, also because he didn’t want Markdown to be a single standard. Which is why he has no problems with “GitHub-flavored” markdown and didn’t want CommonMark using the markdown name.
I recently fell down a bit of a Sphinx rabbit hole that got me into RST after years of Markdown and org. I really really appreciate how easy they make it to add your own plugins that can manipulate the parsed tree. That project is temporarily on the shelf but I’m hoping to get back into it when the snow falls more.
Well there’s DocBook XML and its plaintext representation, AsciiDoc.
Embedding videos, social media widgets, etc. isn’t
possible at all.
For actual documents, I’d call that a feature.
as well as being completely invisible to the writer, so who knows what
the end result will be:
That would seem to be in line with the original vision for the web. You
don’t know what format your document will be presented in. Maybe it’s
on a typical computer monitor. Or maybe printed on dead trees. Or
perhaps rendered as speech, braille, or even morse code. I’m sure the
last one sounds silly, but imagine how a person who is deaf, blind, and
missing hands might read. A device that taps out morse with haptic
feedback would be quite plausible.
I think the main reason why markdown gets hate is that people don’t understand what it is. It’s a way to write what people wrote before markdown, in emails, on newsgroups, in text files. It’s a formatting that is natural if you do it that way.
But when you then end up looking at markdown files where headings don’t look like headings, lists not like lists and especially tables not like tables, because people only look at the output of their editor plugin, etc. it’s also clear that they actually want to write in something else.
The main criticisms of Markdown seem to all match with its original use case. The problem is that people feel or are forced to use it, for situations where they at least think something else would be better. With GitHub making Markdown popular for README files, and these nowadays becoming pretty much the equivalent of static HTML pages, which in and of itself is at least a questionable direction.
Markdown isn’t that clear cut markup language spec, because it’s text to be read, that is just defined enough for computers to render out that text into HTML.
I see parallels there with YAML, which also found its way to be config files to replace the equally bad choice of JSON to be config files. YAML was also mostly about readable adaptable text, and not something that would really have to deal with types a lot. Now we use it for giant config files, instead of stuff that was actually made for that purpose, like UCL, toml, and the only ones realizing that seem to be the Hashicorp folks with HCL.
The reason I bring this up, is because it shows a pattern where something is great, people use it, like to use it, but then more and more people try to squeeze it into other realms, because yeah, it’s possible, but it might not be a good idea. And when it end up being used everywhere instead of only where it makes sense, people write articles like this about how they suck.
There is this habit of thinking that you should only use one way, probably the most commonly used way of achieving something, but when it comes at the cost of having to bend and twist things to make it work or when simply it’s not the right tool for the job, just go and use something else.
I also think this often goes into the whole “modern”, “best practice”, “commonly used” area. Just because any markup language is commonly used, it doesn’t mean you should use it to do everything with it. It’s not like you use only one knife from spreading butter, to sawing boards, just because you can and already own it or know how to use it.
Also sometimes it just takes some experimentation in early development, to figure out what works and does feel right, and what you might want to replace.
Please don’t act like there can only be Markdown or HTML. People don’t usually come up with new markup languages, because they hope it will abolish all the other ones, and if they do I would be skeptical and stay away from it, because it’s almost bound to soon be “that weird old format”.
And yes, there’s good reasons why these problems arise. A lot of developers rightfully want to standardize how to do things, and want to have things flexible and generic, but following it too much leads to weird stuff, like Markdown extensions, programming languages with a bazillion keywords, and every project looking like it uses a totally different language, because every language feature ever invented in any programming language gets added, or functions, methods and APIs accidentally becoming their own Turing complete language, because of all the parameters you can pass.
With compatibility being such a hyped term, I think it would be could for the industry if we’d use the right, rather than the most popular tools and building blocks to compose our systems. I also think it would help if not every new tool that came along would call every other “obsolete” or “legacy”, just because it goes a different route. People will take that to heart and think they have to shove the new tool into every little project. Not every new standard and technology must always take over and replace everything else, it can even remotely be imagined to replace. Doctors with their MRIs and what not also still use their eyes, a lamp and a wooden stick to take a look into your throat.
Markdown is valuable because of its limitations, not in spite of them. Learn a handful of syntactical rules — header syntax, emphasis syntax, list syntax, link syntax, and rules about indentation — and you basically understand the entire thing. That’s the whole ball game.
I found this perspective interesting - the author (whom I happen to e-know since way back) is unhappy with MD as a parseable format which is a usual techie gripe, but also notes that the HTML it produces is inconsistent and outdated.
If Mozilla, of all organizations, have dumped HTML in favor of Markdown and consider the above better than, you know, <span class="foo">, then I must be tilting at windmills. I get it.
The example above this would be impossible or unmanageable with raw HTML. There are specific code snippets for cross references and specific link types. At best you could use customElements, but then you’re locked into requiring client side JS or an experimental backend rendering pipeline.
I do think there’s some space for a more HTML-like, JSX inspired backend template language like <CrossRef foo />, but that already exists and it’s called MDX…
I find editing in vim really pleasant, especially coupled with an automatic formatter, ala gofmt, I use pandoc as a fixer via https://github.com/dense-analysis/ale.
This reads to me like “I don’t like markdown because it promises not to do a bunch of things it was deliberately design to not do that I would like to be able to do.” It’s like saying “I hate Toyotas because they can’t fly.”
I quite like Markdown: because all I want are headers, paragraphs, and very light styling. Which is exactly what it was designed for, and handles very well.
Three out of four of my last F/T paid roles were as a tech writer. I encountered various tools, most horrible, partly because of the “docs as code” movement in FOSS which I personally dislike. I used Markdown a little and AsciiDoc rather more. (Never touched RST.)
But now I’m a journalist again, and Markdown has come to the fore as a really easy, quick, widely-understood format for writing for the Web. It does the core stuff I want, very easily, and the stuff that most of its critics kvetch about is stuff I don’t want and for which there are better tools.
For instance AsciiDoc is about as easy but can do tons more. If you want to write docs, Markdown is probably too simple. If it doesn’t do what you need, then use something that does.
I would not recommend MD for docs. I know lots of people are using it for stuff like that, and IMHO it’s a mistake. Anyone using MD and encountering friction or finding it inadequate is using the wrong tool and that is not MD’s fault.
I think Markdown is popular because it’s a reasonably intuitive bridge between how we format handwritten documents (which is itself a blend of what makes sense on the page, and an approximation of ~spoken rhetoric) and HTML.
In some cases (like the table example), what’s trivial on the page is painful with a keyboard. The technologies that shaped the old idioms didn’t have editability as a selection pressure. You can make a few edits inline, but at some point you’ll just have to rewrite the document.
Much of the power and pain of code are byproducts of the machines forcing us to be explicit, but we didn’t have the foresight to spend centuries molding ourselves (human languages, pedagogy, rhetoric) around that kind of precision. Markdown meets us very close to where we are. The other path, I think, entails developing toolchains that do expect that precision and requiring the humans to do the changing.
Why is TCP so popular? TCP has a lot of issues and there are better ways to connect faster / more flexibly on the modern internet hardware that rarely drops packets, see HTTP 3 dropping TCP.
Simply because it “won”, it has a network effect, it was adopted on many websites and apps, so it had the advantage of being recognizable. Why do we think of Coke as #1 and Pepsi as “secondary”? Honestly it could have even been random. I’m just glad to have such a standard that is relatively widely adopted even though it is imperfect. And no, us markdown heads do not use an editor. We type our blockquotes one line at a time inside a web browser’s <textarea>. Sometimes I even blockqoute 3 code blocks before breakfast.
I’ve been vocal about Markdown being bad for the many of the reasons listed. The latest cramp about it is that there’s no defined way to do metadata. Want to include an author, editor, license, keywords, etc. well, tough luck. With AsciiDoc, Org Mode, reStructuredText, the specs define how to embed metadata in their documents. When I edit an ODF in LibreOffice or an SVG in Inkscape, there is a document properties menu for this. RAW images in Darktable, there’s a prominent “metadata editor” panel in the lighttable view. Having a way to embed metadata is the default behavior for digital creative work file formats, but Markdown doesn’t have it. There’s “front matter”, which is literally just an ill-defined, nonstandardized, non-portable table–and it took your document from being able to be rendered in many contexts to now looking like garbage on your Git forge with a table that you have to parse and realize isn’t the content (and this issue doesn’t exist with examples like AsciiDoc because the renderer knows in this context, it doesn’t need to render the metadata). Without metadata, you have attribution and licensing issues, and need to invent ad-hoc formats.
It contains 95% of the functionality that most people need to create a document.
This I 95% don’t agree with. Where Markdown really doesn’t shine: writing blog posts and documentation–a place where you need more robust features like metadata, admonitions, attributions for blockquotes, collapsible block, etc. Markdown cannot deliver without getting locked into a “flavor”. I’m still slowly in the process of redoing my personal blog and there’s a mess to unravel because I originally tied myself to both the limiting Markdown but also got locked into a static site generator with a specific format I had to follow. Luckily, developers can, right now, go out and choose a better format for their projects (and no, this won’t make contributions harder because the text is still text).
The latest cramp about it is that there’s no defined way to do metadata. Want to include an author, editor, license, keywords, etc. well, tough luck . . . [if] you need more robust features like metadata, admonitions, attributions for blockquotes, collapsible block, etc. Markdown cannot deliver without getting locked into a “flavor”.
But Markdown isn’t meant to provide these capabilities! If you need these things, then Markdown isn’t a solution for your problem. That’s fine! It doesn’t mean Markdown needs to change. It means you should pick something else, I guess, right?
That’s true. It works for things like comments here on Lobste.rs. However, developers not exposed to alternatives, aren’t realizing when they should be switching tools for the job and invent a bunch of incompatible forks and tools rather than moving to the tool for the job. That said, with AsciiDoc, reStructuredText, Org Mode, etc. you can write simple stuff too. It seems we’ve set unrealistic expectations to many that if it’s good enough for a limited functionality required for a comments section, it’s good enough for my blog, my README, etc. and generally it isn’t.
shrug I’m not sure that the capabilities afforded by markup languages more powerful than Markdown outweigh their costs, for the use cases that Markdown targets.
As an analogy, consider technical diagrams. I think there are basically 2 types of diagrams worth using: boxes-and-lines diagrams, to express component relationships in a system; and sequence diagrams, to express information flow between components over time.
I think raw ASCII is the best way to draw both of these diagrams, because the constraints that raw ASCII imposes on author expressiveness is actually virtuous. Anything that’s too complex to express in raw ASCII is probably too complex for typical consumers. Said another way, if you can’t draw it effectively in raw ASCII, then the thing you’re trying to draw probably needs to be simplified — broken up into multiple drawings, etc.
I think the same thing is more or less true for anything you could conceivably write in Markdown. If you feel like Markdown is a limiting factor, and you need your README or blog post to express things that aren’t possible to express, then I think it’s usually — not always! but almost always — an indication that you’re trying to express more detail than is appropriate for your audience.
Concretely: a README should probably not include semantic author attributions of its blockquotes. The consumers of READMEs do not benefit from this information, and the maintainers of READMEs suffer from the additional syntax required to express that concept. The same thing is more or less true for licensing information, keyword metadata, etc. etc.
I don’t know what goes into your blog posts but for mine, MD would be fine and I wish my current blogging site supported it for posts. It does for comments, which is very handy.
Yeah. I have collapsible blocks. I use admonitions (and not breaking the semantics of the <blockquote> element). I attribute quotes properly. I have definition lists, glossaries, footnotes. My image tags have heights, widths, and titles. Sometimes my blocks and lists have titles that aren’t <h#> headings. Occassionally I need to add a one-off CSS class too. My blog has keywords, and descriptions, an author, licensing, and other metadata. When I use Asciidoctor, all of these features are built into the syntax and don’t require an ad hoc systems or additional tools (though I am electing to use Soupault to help iron the data into a format I like better). And without much thought I could turn these documents into a book in PDF form and not be littered with HTML tags. I can also host look at it on Gitea or GitLab if I needed for whatever reason and I don’t have eyesore elements to deal with my limitations.
I would venture that your blog needs some of these features too, but you’re probably relying on an ad hoc format like front matter that prevents its portability, or are using some elements incorrectly (like list items with BOLD text instead of definition lists, or have inline HTML which ruins the plaintext aesthetic and breaks in some contexts.
I would venture that your blog needs some of these features too
Chuckle Nope.
you’re probably relying on an ad hoc format like front matter
If I were ¼ century younger, I’d reply LOLnope or something.
Sometimes I remember to replace * bold * with actual bold tags, but that’s as close to formatting as it gets. No. It’s a quick place to put random thoughts, and in the instance of my tech blog, I generally copy-paste longer comments there to preserve them and offer them to a wider audience. Posts fairly regularly get shared on Lobste.rs so I guess it’s working.
This is sort of the point I was getting at: Markdown does all I need and more, and criticism of it is generally from people who need a different tool and so are misaddressing their complaints.
I am not in any way denigrating your blog or anything! I am just saying that there is a good place for quick’n’dirty tools and I like them.
This is why I dislike “docs as code”: because programmers’ editors are awful tools for a writer and I really dislike using them. I don’t want or need syntax highlighting, or line moves, or pattern matching. I really do need a live word count though, and nothing give me that since MS Word for macOS.
ADoc has uses. I am very happy that I do not need a single thing it does that MD doesn’t any more, and I wish more people used ADoc instead of MD.
you’re probably relying on an ad hoc format like front matter that prevents its portability
That’s right. YAML front matter. Looks good & works great.
or have inline HTML which ruins the plaintext aesthetic and breaks in some contexts.
Some. But, it’s easy to remember and looks a lot better than AsciiDoctor syntax 💁🏻♀️
That’s the entire idea behind markdown: it doesn’t try to be the be-all, end-all. It’s a simple filter for when you wanna write HTML but don’t wanna have to type out every single br or p or a bref or h1. It’s an amazing tool on the editing side and that’s all it needs to be.
If you want to blog like you’re writing a thesis, more power to you. I personally just want to put pixels on screens, without having to worry about not closing tags. Markdown fills that need admirably.
Sure, but a lot of people don’t pay attention to the generated HTML and end up with unsemantic elements that ruin other tools trying to consume the HTML. In cases like excluding width/height on images lead to performance and rendering issues. A lot of this is exacerbated by the lack of robustness and because of folks without blame not wanting to “worry about not closing tags”, use the wrong semantics due to the tools afforded by Markdown. If just getting text out is the goal and not following the HTML semantics, then Gemini seems like the format to choose.
A specific example is admonitions where you see some folks using **NOTE:** foo, but this leads to just a plain paragraph with bold text with nothing to separate it from the main content (and some don’t all caps it, and other don’t bold it). Other implementation overload and abuse the > for block quotes (with broken implementations like GitHub’s still using the <blockquote> when generated which isn’t semantic and violates the spec of “a section that is quoted from another source” instead of using something semantic like <aside> or generic like <div>) and the label part isn’t agreed on in these overloaded block quote ideas. Microsoft does something with [!note].The CommonMark RFC is for blocks starting like :::note, but it seems most aren’t using for one reason or the other. Admonitions are very common for code documentation, and AsciiDoc and reStructuredText don’t have competing ways to write it–it’s a part of the spec and doesn’t break semantics.
I use <aside> just fine on my blog, I use it all the time. I use it by simply typing <aside> which is easy enough to remember without having to do anything special. This is why dropping down to HTML is so awesome and part of Markdown’s magic.
If just getting text out is the goal and not following the HTML semantics, then Gemini seems like the format to choose.
Yes. It works. Just like plain text email works or plain text SMS text messages work.
The easy of adding inline HTML isn’t the issue, it’s the use of unsemantic elements. This may be unintentional–especially for folks that haven’t read chunks of the HTML spec–but it’s still causing the wrong elements to be used. An informational admonition is complementary to the content, not a direct part of the document (which is why it’s often rendered in some form of call out). The blockquotes-for-admonition example mentioned is straight up wrong rather than an missing wrapper though. And when you see people create block quotes like
Arguing that you don’t care about the right to privacy because you have
nothing to hide is no different than saying you don’t care about free speech
because you have nothing to say.
> Arguing that you don't care about the right to privacy because you have
> nothing to hide is no different than saying you don't care about free speech
> because you have nothing to say.
― Edward Snowden, https://www.reddit.com/r/IAmA/comments/36ru89/just_days_left_to_kill_mass_surveillance_under/crglgh2/
Now the quote attribution is in a generic <p> paragraph tag and not properly grouped with <blockquote>
Arguing that you don’t care about the right to privacy because you have
nothing to hide is no different than saying you don’t care about free speech
because you have nothing to say.
> Arguing that you don't care about the right to privacy because you have
> nothing to hide is no different than saying you don't care about free speech
> because you have nothing to say.
>
> ― Edward Snowden, https://www.reddit.com/r/IAmA/comments/36ru89/just_days_left_to_kill_mass_surveillance_under/crglgh2/
This isn’t correct either because you’re missing the <cite>. So does this mean are you going to always going to bother writing for every attributable quote (assuming this is the structure you want; I know <figure> is common too)? Will you remember to use the correct structure every time?
<div class="Quote">
> Arguing that you don't care about the right to privacy because you have
> nothing to hide is no different than saying you don't care about free speech
> because you have nothing to say.
>
> <footer class="Quote-attribution">― Edward Snowden, <cite>https://www.reddit.com/r/IAmA/comments/36ru89/just_days_left_to_kill_mass_surveillance_under/crglgh2/</cite></div></footer>
</div>
when in AsciiDoc you can do this and not think about the HTML semantics as they are handled for you
[quote, Edward Snowden, https://www.reddit.com/r/IAmA/comments/36ru89/just_days_left_to_kill_mass_surveillance_under/crglgh2/]
Arguing that you don't care about the right to privacy because you have
nothing to hide is no different than saying you don't care about free speech
because you have nothing to say.
This is exactly the level of programmer-brain semantic nitpicking that 99% of the population never should have to learn.
This is why in the olden days typographer was a separate job from journalist or authors, and these days why template designer is a separate job. So writers can be free to just write.
The fact that AsciiDoc has a way to do it is a strike against it for general users since they’re gonna be seen as dumb if they don’t do it semantically properly.
It’s possible to make a post-processor on the template language level to detect and fix those “footer”/“header” quote attributions by looking for foo bar: before the quote or –foo bar after the quote. (I should go set something like that up, thanks for reminding me; although in this case your proposed correct structure is incorrect since semantics can’t live on the class/id level and a footer is only appropriate for a document or section.) I don’t mind this sort of semantical type setting for the HTML target specifically. I do type <cite> and <i> all the time (and use Markdown’s shortcut for em. Common things super easy while rare things like i and cite in a normal, straightforward style. That is the way).
At the same time, I super appreciate that on gemtext, it’s not necessary. You just write and you’re done. Same goes for email, SMS, tweets, Mastodon etc. It’s just loosey-goosey text and it’s so functional and pragmatic.
Different formats have different semantical salience levels. On email you’ve got to get the “To:” correctly snd it’s also good to have “Subject:” and/or a “Body:”. In a printed book you might want page numbers.
The more of these semantical salience levels you slather onto a writer’s yoked shoulders, the worse their writing will be.
Also, the entire idea of the semantic web kinda failed. The more rules there are, the more rulebreaking texts there are. What’s the point? Some super web crawler evil AI gonna be even more correct in its dissection of humanity? Some of these semantic markups help screenreaders if they are applied consistently, like table navigation, but some don’t.
I don’t wanna have to learn AsciiDoc’s block structure syntax 💁🏻♀️ on top of having to learn the underlying HTML I also need to learn the semantics ins and out of (in order to be motivated to even use the AsciiDoc syntax in the first place)
I disagree. For me the purpose of the lightweight markup language is to hide having to remember some of the difficult semantics in a portable syntax that can be exported to many formats without having to think too hard about the source material. The semantic web still give you a) good heuristics to follow (solving the “naming things” problem) and b) lets you skip needing to add role=* to elements to help with assistive technology. If you go further and use microdata, then you can free up needing to layout your markup in a very specific way for tools like the web crawlers–it also can disambiguates to a machine (i.e. is this date for created, updated, or published?) something that may be clear to a user visually reading content.
If you don’t want to think about it too much, then it’s okay to use <div> and <span>, but it’s not okay to use the wrong element (e.g. using a <blockquote> when it’s not quoting anything)
I agree that Gemtext is the place for that sort of thing. In many ways, folks should aim to use *.txt files if the goal isn’t to target HTML. GameFAQs was a better site when guides were plaintext and full of ASCII art over the HTML files–however, these formats don’t do the best job with accessibility or machines to understand the semantics. If SEO were less important, then still see curated lists like GameFAQs and Yahoo’s old search, but we have to appease the machines and if you play along with the semantic web, then there less ambiguous content for machines to error on. And at the end of the day, I find AsciiDoc’s plaintext semantics a lot easier to read than HTML as plaintext while being close enough to the ASCII text of the past.
If you don’t want to think about it too much, then it’s okay to use and , but it’s not okay to use the wrong element (e.g. using a when it’s not quoting anything)
Right. I don’t use any divs personally because I have templating that does section, blockquote etc personally but I’ve argued again and again that Markdown-based languages, like on Reddit or here on lobste.rs, should have i instead of em since i is never wrong (and sometimes the only right one) but em can be wrong.
we have to appease the machines
Screenreaders yeah, search engine’s no, we don’t. If peeps wanna find the site they can bookmark it ♥ or use links.
a portable syntax that can be exported to many formats
To me, the lightweight format doesn’t itself have to be this über catch-all ultra portable thing. If a good one existed (which is maybe not even possible, as we learned from DocBook’s failures), we could then have a markdown-like language that dropped into it. Like, take DocBook again as an example. Writing it becomes much simpler with a li’l filter that does para and emphasis and other super common things, while the more nitty gritty things like the info block can live in a template written directly in the DocBook language.
Put another way: the PSTCBETMF needs to be very broad in order to cover all the features of all possible targets while the LYAWI (language you’re actually writing in) only needs to cover the most common, everyday features of one expression source.
Like, take my text overview page: https://idiomdrottning.org/texts
There’s no way I’d wanna write that in Markdown or AsciiDoc or like YAML or HAML or Textile or something. It has sections and columns and links and all kinds of stuff. (Instead it’s all generated from a template I wrote with Liquid and XHTML directly.)
Markdown is only good for writing text but it’s damn good there.
the lightweight markup language is to hide having to remember some of the difficult semantics
You’ve identified exactly where we disagree there.
It becomes the worst of all worlds:
you have to know/understand the underlying semantics (just like you have to when you’re writing a template)
you have to know/remember the way the lightweight markup language represents those semantics in all its exact fiddliness with brackets and commas and whitespace
you have to the stare at all that syntax in all its ugliness even though it’s only like ten percent “lighter” than the target language
you might have to flip back and forth to a render/preview to see if it worked
Take links for example:
https://wikipedia.org[Wikipedia] is an example in AsciiDoc.
<a href="https://wikipedia.org/">Wikipedia</a> is an example when dropping down to HTML.
The AsciiDoc version is barely any more readable! It totally breaks the reading flow.
I think we agree about our disagreement here other than how and where we feel that line should split (and I can see your point). I don’t mind learning and remembering a bit more syntax to have more features and more easily turn it a document into a PDF or slides. I do care about the semantics quite a bit though.
Footnote-superscripts don’t come before the phrase they’re attached to.
The page you’re gonna visit next doesn’t come before the text you’re reading now.
I don’t mind learning and remembering a bit more syntax to have more features
Well… we all wants things to be as simple as possible. But then I say no simpler.
If I want syntax for all those features, I know where to find it. I don’t need to create a semaphore system of smoke signals and shadow puppets where I can write what I in turn meant to actually write. There’s no reason the syntax for those special features should be like AsciiDoc’s mystical squares and commas instead of a normal, full-featured, real, explicit syntax.
It’s not as if I need to write those “explicit syntax” parts tediously, character by character, either; my blogging system isn’t a typewriter so I’ve set it up to prompt me for things. What category should this be? What is the URL to that thing I square bracketed?
And when I need to do weirder things like this treasure generator I have an escape hatch from the simple convenience layer (Markdown) into the real thing (HTML). Right there in the same blog.
The easy of adding inline HTML isn’t the issue, it’s the use of unsemantic elements.
Authors who want to quote something will have a few things at hand:
The text itself (guaranteed)
The author (likely)
An origin URL (possible)
A usable markup syntax for quotes can’t assume that all of these bits of metadata will be available. If all you have is #1, you shouldn’t have to know about #2 or #3 to express your intent. And, in all cases, you should be able to express your intent without deep knowledge of the tool you’re using.
If you wanna quote something, the ASCII text default way to do that, understood by every human on the internet, is more or less this:
> Your quote here.
Whatever syntax you have for quoting has got to support that as a base case. Given that, the question becomes how to optionally layer-on the other bits of metadata — author, and origin URL — in a way that works with this base assumption. And
[quote, Author Lastname, https://example.com/path/to/document]
Your quote here.
Sure, but the optionality is itself a problem. Even if I don’t use a particular feature myself, I still have to know about it, in order to understand the output of others.
Markdown suffers from this, too. You can maybe make a case for both the - and * markers for un-numbered lists, but I can’t see any reason for the === syntax to denote headings. There are probably other ambiguities, too.
In the ASCII days it was common to use heading like (as is the case with reStructuredText)
Title
====
This is supported in AsciiDoc, but they probably found it a bit obtuse and impractical in many cases and used the = sigil. What on Earth would make # more meaningful?
# has several structural advantages over ===, I think. It sits on the same line as the heading, so it’s easier to parse for both humans and computers. It supports arbitrary levels thru repetition, and it’s intuitive: # H1 and ## H2 and etc. make sense. And because it prefixes the header text rather than underlining it, the typography always basically “works”.
Your Heading
============
Should be fully underlined, if you're going to underline it.
Whereas
===
If you don't it looks quite silly ;)
c.f.
# Your heading
## Whereas
### Subsection with long name
Wait what? Did you think underline was the only style supported? AsciiDoc normally, from my experience, wants users to do
= Your heading
== Whereas
=== Subsection with long name
That is no different other than the sigil. You can even see this in practice in the raw version of the heading documentation for Asciidoctor, as well as the rendered docs. And due to “Section levels must be nested logically.”, you can’t nest improperly, something Markdown doesn’t enforce and was a pain I had to deal with recently.
The only time I personally use the underline option is for the main title for stylistic reasons, because it adds visual separation for the metdata and makes it stand out in the visual hierarchy as the document title
My Title: and its Subtitle
==========================
toastal
:keywords: foo, bar, baz
:description: a mock post
:license-url: https://creativecommons.org/licenses/by-nc-sa/4.0/
:license-title: Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International (CC BY-NC-SA 4.0)
[abstract]
--
Today we will discuss something
--
== My first section
And its paragraph
=== Subsection with long name
Another paragraph
Wait what? Did you think underline was the only style supported? AsciiDoc normally, from my experience, wants users to do . . .
Yeah, I did! Neat that AsciiDoc lets you use = as a prefix like that. Markdown doesn’t, and that was my point of reference. I don’t use AsciiDoc, in large part due to the sort of optionality we’re talking about right now. If a language allows its users to express a given outcome (e.g. an tag) in more than one way, I see that as a problem that needs to be fixed. YMMV, of course!
nest improperly
What does “nesting improperly” mean? AFAIK this isn’t a concept that exists in the headers produced by e.g. # Heading or ## Subheading in Markdown. That syntax translates directly to <h1> or <h2> which are tags that need to be closed but otherwise carry no semantic value.
The only time I . . .
The text you wrote there is pretty complex in terms of sigils and syntax and demarcated sections and etc. For a human reader of that plain text, it is IMO substantially more difficult to understand than the XML or HTML that would be produced from it. And again IMO this is a direct result of the set of features, and the optionality of syntax, which AsciiDoc (?) provides. It’s fine if you don’t agree! People are different, no problem. But if you PR’d a project I maintained and added docs in that format, hard no from me 😉
edit: If all of that information is strictly necessary, and this Markdown version
# My Title: and its Subtitle
## Metadata
- Keywords: foo, bar, baz
- Description: a mock post
- License: [CC BY-NC-SA 4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/)
## Abstract
Today we will discuss something.
## My first section
And its paragraph.
### Subsection with long name
Another paragraph.
is in some respect insufficient in terms of expressiveness, then I just can’t grok the value prop of an intermediary language between that and straight up HTML/XML. Those languages are meant to be basically human-readable, right?
This may be a legacy thing, as a lot of old docs supported the underline style. It makes parsing more complicated which is relevant, but as a user, it’s not a big deal and can be skipped.
nesting headings improperly
From their docs:
Section levels must be nested logically. There are two rules you must follow:
A document can only have multiple level 0 sections if the doctype is set to book.
The first level 0 section is the document title; subsequent level 0 sections represent parts.
Section levels cannot be skipped when nesting sections (e.g., you can’t nest a level 5 section directly inside a level 3 section; an intermediary level 4 section is required).
I have seen users do this wrong–especially when focusing on the visual style a heading provides instead of the semantic one for the document (e.g. Why did you make this an <h4>? Because I wanted the text smaller.).
your markdown
What’s happened here is that you’ve built an ad-hoc system. It’s not that it’s not readable as plaintext–it’s easier to read–but it caries no underlying semantic value.
Metadata and abstract as regular headings
How is the parse reasonable supposed to assume these are not just sections with content? How would I create a regular sections called “Abstract” or “Metadata”?
Metadata as a list
Did you want a definition list? (Oh, Markdown doesn’t support this 🙃). These get rendered as plain <li> elements without any concept of key/value that. Do I have to escape : if I need it in a key? What’s up with keywords being comma-separated? Is this another ad-hoc convention (vs. <dl><dt>Keywords</dt><dd>foo</dd><dd>bar</dd><dd>baz</dd></dl>)?
In the case of Asciidoctor, I can do something with this metadata labeled as such:
my metadata can be correctly tagged in HTML, PDF, DocBook, and other outputs in their expected formats
metadata can be reused inside the document since it’s the same as the ‘variable’ syntax
I can use docfile formats to add additional metadata to various parts of files if I need something special
other ‘consumers’ of my file can happily ignore them (e.g. Codeberg doesn’t need to display the license of that document or the author, etc. (or could put them in the <head> but not rendered in the document)–with Markdown, because it’s ad hoc, they can only assume it always needs to be displayed)
Abstract as a generic section
Abstracts are a special part of the document with a special meaning. You often want to style it differently. This was one of this issues I had recently trying to parse a lot of different people’s Markdown files they sent me; some people had an Abstract with a heading, some had a paragraph with nothing to delimit it and others started with a generic paragraph that wasn’t an abstract. Others started with a backstory instead. Without a heading, you can’t reasonably assume a block is the abstract or not or what order these elements are in. If the user specifies it, it’s clear.
What’s happened here is that you’ve built an ad-hoc system. It’s not that it’s not readable as plaintext–it’s easier to read–but it caries no underlying semantic value.
So I guess a good way of summarizing what I’m trying to say here is that if you need to express “underlying semantic value” in a document, you should not use a plain-text markup language like Markdown (for sure) or AsciiDoc (IMO) in the first place. These tools are not meant to provide a high degree of semantic expressiveness. They’re meant to provide the bare minimum set of capabilities — mostly typographical — while maintaining plain-text legibility.
How is the [parser] reasonably supposed to . . .
Ah! Maybe this is a point. Tools like Markdown aren’t meant to produce mechanically parseable output. They’re meant to produce typographically acceptable documents that can be “parsed” by human readers.
Maybe AsciiDoc tries to solve a different set of use cases. That’s cool! But it means the tools aren’t really comparable. When I’m writing a GitHub comment or whatever, semantic annotation features are actively harmful to my user experience.
If you want semantically meaningful, mechanically parsable documents, then why not just write HTML/XML directly? With care, it’s absolutely human-readable — it was designed to be so! And you don’t lose any expressive power in translation.
I wouldn’t disagree with the assessment, but I would disagree that human-readable isn’t the only goal. Machines parse our markup for SEO, for web scraping, and we can use that metadata in interesting ways like creating an outline or feed. In these cases, having a semantic makes these transformations easier and parsing more accessible. I feel the advantages of AsciiDoc or reStructuredText are big enough and don’t change enough that they’re still “lightweight markup languages” while having more expressiveness. While I had an hunch this mattered and switched on personal stuff a while ago, but it was much more apparent whenl I touched a recent project in which I was tasked to wrangle multiple authors’ different Markdown style that it became so apparent that the project really could have used a switch in the syntax for compliance and consistency. We ended up having to build sidecar files for the metadata but authors chosen a format with metadata, this could have been avoided, easier to manage, and less buggy.
Edit re: the cite attribute, the same document states
If the cite attribute is present, it must be a valid URL potentially surrounded by spaces. […] User agents may allow users to follow such citation links, but they are primarily intended for private use (e.g., by server-side scripts collecting statistics about a site’s use of quotations), not for readers.
(My emphasis)
I’d much rather have the citation source linked to the attribution “element”, like so, to make it easier for readers to follow the link. I don’t really care about statistics about a site’s use of quotations.
I had thought the attribution needed to be outside the <blockquote>, but this isn’t the default layout for Asciidoctor and I was assuming they were right in their semantics. I doubled back on what I originally written under those assumptions, but it seems they are wrong and I’m happy I had another opportunity to reread the spec (even if it was just a few lines down from what I had linked for how <blockquote> was being misused for admontions). I will raise an issue with them now. I think they know about it (there is a migration to adopt more HTML5 and semantic HTML in the future) and the asciidoctor-html5s does it closely enough.
What’s caught my eye recently is the asciidoctor-html5s alternative backend for Asciidoctor. I know there are long-term goals for the Asciidoc project to modernize its HTML representation, but this is something that can be used now.
My biggest missing feature for AsciiDoc would be:
a shorthand for <abbr> tags for accessibility–ideally in a manner where the <abbr>s would be automatically added as I wrote and they were automatically appended to the glossary. You don’t realize how much jargon people write until you step a little out of your own space
more metadata options: editors, collaborators, translators (not just authors)
I added support for <abbr> tags to my own markup language. I define the bunch that I use at the top of the document and anywhere the acronym or abbreviation appear in the text, an appropriate <abbr> tag is generated. It fails if you use an acronym with two different meanings (e.g. “the IRA (Irish Republican Army) has its own IRA (Individual Retirement Account)” for a silly example) but it has rarely come up. I have had to special case a bunch since acronyms can come in many forms (D&D, GHz, IPv4, NaNoGenMo) but it generally works.
I use <abbr title="Three Letter Acronym">TLA</abbr>.
Perfect example of why just dropping down to the HTML you already know is better than having to figure out some arcane syntax to learn in order to generate the HTML semantics that you also need to know & be aware of in order to use them.
What happens when you want to convert this to another format that isn’t HTML? This is lock-in–lock-in you might be okay with, but it does hamper other uses.
I was a fan of Textile before Markdown took over. In retrospect, I’m not sure it was the clearly superior language. It leaned hard on existing knowledge of HTML. After years of Markdown seeping into everything, I’ve become accustomed to its many limitations and quirks. Markdown is more readable in its raw form, which I’ve come to appreciate. All I wish now is that John Gruber would make peace with the people who are trying to make it better and let them use the name. I think it would go a long way toward unifying a fragmented landscape of implementations.
I don’t know Gruber or what his deal is, but trying to read between the lines of the few things he’s written on the topic, I get the impression that to him Markdown is not a file-format. Instead, Markdown is the idea of writing a quick-and-dirty script to transform the thing you want to write into the format you want to produce, ignoring the corner-cases you don’t care about. GitHub-flavored Markdown is Markdown, Textile is Markdown, ABC notation is Markdown. The syntax that everybody else calls Markdown is just the syntax that one particular tool happened to support on the particular day it got popular, and doesn’t have a greater claim to the name than any other, and certainly doesn’t deserve to be preserved forever as The Official Definition of Markdown.
That said, I think the CommonMark syntax is pretty comfortable, and despite its quirks, I get a lot of value out of being able to use familiar formatting conventions in just about every textbox on the Web. The world might genuinely be a better place if there were just One Standard Markdown we could use everywhere, but I’m sympathetic to the idea that maybe it wouldn’t.
Everyone uses an editor? No no no no… 1000 times no. I hate WYSIWYG editors and what thei represent. Putting formating ahead of content was an horrible idea that tends to survive in the heads of many, while at the same time it already has been proven conter productive anyway.
Markdown is human writable, and could be adopted by the masses for example on messaging apps, social media, etc. If people are introduced or forced to use it at work or school.
Bbcode was very popular in the 2000s and webforums broke through in popularity well beyond techies.
What if students had to make their written school assignments in mark down? Is it such a complicated thing to ask the? In which way is MSWord any simpler? It’s not!
If you need to include tabular data, markdown is hard, IMO. The original markdown required you to just write HTML for them, which was no picnic. None of the dialects that have evolved since then are anywhere near as easy as editing a table in Word. And I say this as someone who intensely dislikes Word.
I like writing in markdown, using a plain old text editor. But when I need to insert a table, I use visidata to edit and export github-flavored markdown. I don’t mind it, because I appreciate the other benefits of markdown. I could not claim, with a straight face, that it’s as easy as a WYSIWYG editor would be for creating the document.
(Also, FWIW, markdown has been adopted on discord, and I think most matrix clients do the right thing with it too.)
another nice option is
pandoc:FWIW, Emac’s
markdown-modehas a few functions that make writing tables easy.There’s
markdown-insert-tablewhich prompts for the size and alignment and inserts a pre-built table, and even allows tabbing between cells.And then there’s a number of
markdown-table-*functions for editting them - moving rows, adding columns, etc..I wrote my own Markdown/ORG mode markup language for my blog. The one thing I do not do is store the posts in my markup language, but the final HTML render—that way, I’m not stuck with whatever syntax I use forever (and I’ve changed some of the syntax since I initially developed it). Also, for tables, I use simple tab-separated values:
Whitespace are tabs, the line starting with the asterisk is a header line; the double asterisk is the footer. This handles 95% of the tables I generate, and because I store posts HTML format, it doesn’t matter much that it looks a bit messy here.
I think most people don’t get what John Gruber was trying to do—make it easier to write blog posts.
“Putting formating ahead of content was an horrible idea that tends to survive in the heads of many”
I use Emacs and Org-mode but I have never understood the insistence that those who use anything from LaTeX to Docbook to Markdown are separating content and structure.
Oh, how I tried to learn LaTeX until it smacked me in the forehead that I had to complie a document!
Anyone who types #header ##subheading * bullet while typing (or using autocomplete) is thinking about format and structure while producing content.
I loathe word processors but creating a template makes it just as easy to seperate content and structure. Even back in the 90s on USENET and other pure plaintext forums, or RCF’s that matter, it was commonplace to insert ASCII tables and /emphasis/, like I am now with * and /s.
Nothing has ever stopped anyone from treating a screen like a typewriter or pad of paper and just writing and writing and writing and come back later to add structure and formatting.
Writing is writing. Editing is editing. Typesetting is typesetting. The only difference now is we all have to do all three, but nothing but our minds prevents us from doing them separately.
Agreed. The only WYSIWYG editor I’ve ever enjoyed using is TexMacs, despite it’s strange window/buffer approach and bugs. I wish every WYSIWYG editor learned from it. The vast majorty of them are a complete nightmare. I want to throw my computer every time Slack’s new WYSIWYG message box screws up my formatting.
I think they underestimate how many young people use discord and markdown for formatting their text.
Well yes, but also, I don’t need that in reddit or discord. And the places that do need it, are better off doing said post processing. Also I’m very glad that I can actually use it instead of a badly behaving WYSIWYG editor (looking at you reddit trashfire that ate my text too many times). Same goes for github/gitea/gogs/gitlab entries.
It’s a modern BBCode for “forums”, which is also better in being readable without rendering.
BBCode is an excellent comparison, because I remember the web being riven with unclosed BBCode tags and bad formatting.
What Markdown does not do is probably more important than what it does.
This. Markdown’s strength is that it doesn’t try to be all things. There’s a megaton of content in the space that sits between scientific paper / book scale organisation, and, well, let’s go for tweets as an example at the other end of the spectrum. What Markdown does really well is cater for that content. If anyone is going to argue that Markdown isn’t good enough, I’ll ask them to show me how many tools they have in their toolbox, and if there’s more than one, their argument is bunk.
Also: WYSIWYG is tremendously overrated and I’d argue that in some circles it has hindered content creation rather than supported it.
Finally: I can’t help but smile to see the Markdown formatting available just winking at me below this textarea input box in Lobsters.
It’s just a shame Org syntax didn’t beat out Markdown syntax. Org supports such simplicity and much complexity, in a readable plaintext format.
It might be a shame, but it’s a predictable consequence of the fact that org-mode doesn’t have an independent implementation that most people can use. Markdown had a simple perl program that you can call from a makefile or any sort of script to render your text to html. These days there are loads of libraries to choose from, to render on the client, server, GUI, etc. dynamically.
I strongly agree. And that is still a little disappointing, because org-mode was so well suited for that kind of thing. org-babel had so much potential for literate programming. I wish that had broken differently.
While I appreciate Org mode’s outlining features, Org mode’s syntax has some limitations that make me glad it didn’t catch on.
#+BEGIN_SRC javascriptand#+END_SRCinstead of Markdown’s```javascriptand```. That syntax uses three different punctuation characters – it’s hard to remember and type.<sTab (using thesstructure template), but that only works in Emacs.~#example~are harder to visually distinguish from code than Markdown’s inline code delimiters`#example`.There’s a lot of reasons why Org-mode didn’t end up winning out because of complexity.
Orgmode is wonderful and terrible in a lot of the same ways Emacs is.
The key benefit of Markdown is that it’s readable as plain text. I can write docs in a repo in Markdown and they are comprehensible both as text and as rendered HTML / PDF / whatever.
Compare the input:
To the output:
This is my top-level headingThis is some text.
Now a subheadingEither of these is fine for a human to read (though the bulleted list shows a bug in the Markdown parser that lobste.rs uses, which is part of the author’s point). That’s a property that most other document markup languages lack. DocBook is far more powerful but the source is painful to read. AsciiDoc is a bit more readable but is still very verbose in comparison.
The real problem comes when you want to write content in Markdown that goes beyond what Markdown can express.
I thin AsciiDoctor dialect is not?
Though, the point about lack of a great standard and non-semantic HTML output apply to asciidoctor in spades.
All of what you posted is vanilla asciidoc
There is also some markdown compatibility in AsciiDoctor: https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/#markdown-compatibility
That’s more readable than the AsciiDoc that I’ve seen, perhaps I was looking at things that used a lot more advanced features. I find the underlined headings in Markdown a lot more visually distinct in plain text than the prefix version (in Markdown and AsciiDoc), possibly because I was used to them by the early ‘90s in plain text docs. The numbered list in Markdown is a lot better. Consider a paragraph of text that refers to point 5 in a list. With the Markdown version, I can jump to that when reading far more easily than if every line starts with a dot. This is also useful in editing: I’ve written LaTeX where I’ve referred to the wrong number in an enumerated list because I didn’t correctly count the number of \item lines, but never done that in Markdown.
The drawback with setext headers is that they look best in monospace. Putting exactly that many underlining characters. (Your example a few posts up that didn’t do that looks kinda weird.) Atx headers work* in proportional fonts too, so that’s why I prefer them.
*: Or work just as poorly 💁🏻♀️
In monospace, on a visual display, at that.
In my experience atx headers are better for screenreaders.
And many monospace fonts aren’t actually monospace. I found out the hard way with maTeXt (if you look at the rendered math with your browser, it’s likely to appear broken, even though it looks fine in a terminal, where characters are forced to align properly).
I find it funny RST (restructured text) is never mentioned in these debates.
On the contrary, the only time I ever see it mentioned is precisely in these debates.
Rst has its problems (terrible headers, no nested inline markup) but the extensibility you get is just wonderful.
Yes, glad someone mentioned the headers.
A lot of python stuff still uses RST.
I don’t really care about extensibility if it means every time I want an in-line code block with part or all of it linked to another document I need to write my own role. Not supporting nested in-line markup is just brain-dead.
It was a more robust and better designed option, retaining the essential same mindset as markdown. It is unfortunate that markdown won the popularity contest. But marketing and hype dictated the outcome.
It’s funny, but OG Markdown was just a dude with a then popular blog and a whole mess of Perl: https://daringfireball.net/projects/markdown/
(my emphasis)
The list of filters (from https://daringfireball.net/projects/markdown/syntax#philosophy), links from the original:
Gruber never intended MD to become the be-all and end-all of authoring. In fact I think that’s why he didn’t let CommonMark use the Markdown name.
Yes, also because he didn’t want Markdown to be a single standard. Which is why he has no problems with “GitHub-flavored” markdown and didn’t want CommonMark using the markdown name.
RST is mentioned as an inspiration to MD, see my comment down below https://lobste.rs/s/zwugbc/why_is_markdown_popular#c_o1ibid
I recently fell down a bit of a Sphinx rabbit hole that got me into RST after years of Markdown and org. I really really appreciate how easy they make it to add your own plugins that can manipulate the parsed tree. That project is temporarily on the shelf but I’m hoping to get back into it when the snow falls more.
Well there’s DocBook XML and its plaintext representation, AsciiDoc.
For actual documents, I’d call that a feature.
That would seem to be in line with the original vision for the web. You don’t know what format your document will be presented in. Maybe it’s on a typical computer monitor. Or maybe printed on dead trees. Or perhaps rendered as speech, braille, or even morse code. I’m sure the last one sounds silly, but imagine how a person who is deaf, blind, and missing hands might read. A device that taps out morse with haptic feedback would be quite plausible.
I think the main reason why markdown gets hate is that people don’t understand what it is. It’s a way to write what people wrote before markdown, in emails, on newsgroups, in text files. It’s a formatting that is natural if you do it that way.
But when you then end up looking at markdown files where headings don’t look like headings, lists not like lists and especially tables not like tables, because people only look at the output of their editor plugin, etc. it’s also clear that they actually want to write in something else.
The main criticisms of Markdown seem to all match with its original use case. The problem is that people feel or are forced to use it, for situations where they at least think something else would be better. With GitHub making Markdown popular for README files, and these nowadays becoming pretty much the equivalent of static HTML pages, which in and of itself is at least a questionable direction.
Markdown isn’t that clear cut markup language spec, because it’s text to be read, that is just defined enough for computers to render out that text into HTML.
I see parallels there with YAML, which also found its way to be config files to replace the equally bad choice of JSON to be config files. YAML was also mostly about readable adaptable text, and not something that would really have to deal with types a lot. Now we use it for giant config files, instead of stuff that was actually made for that purpose, like UCL, toml, and the only ones realizing that seem to be the Hashicorp folks with HCL.
The reason I bring this up, is because it shows a pattern where something is great, people use it, like to use it, but then more and more people try to squeeze it into other realms, because yeah, it’s possible, but it might not be a good idea. And when it end up being used everywhere instead of only where it makes sense, people write articles like this about how they suck.
There is this habit of thinking that you should only use one way, probably the most commonly used way of achieving something, but when it comes at the cost of having to bend and twist things to make it work or when simply it’s not the right tool for the job, just go and use something else.
I also think this often goes into the whole “modern”, “best practice”, “commonly used” area. Just because any markup language is commonly used, it doesn’t mean you should use it to do everything with it. It’s not like you use only one knife from spreading butter, to sawing boards, just because you can and already own it or know how to use it.
Also sometimes it just takes some experimentation in early development, to figure out what works and does feel right, and what you might want to replace.
Please don’t act like there can only be Markdown or HTML. People don’t usually come up with new markup languages, because they hope it will abolish all the other ones, and if they do I would be skeptical and stay away from it, because it’s almost bound to soon be “that weird old format”.
And yes, there’s good reasons why these problems arise. A lot of developers rightfully want to standardize how to do things, and want to have things flexible and generic, but following it too much leads to weird stuff, like Markdown extensions, programming languages with a bazillion keywords, and every project looking like it uses a totally different language, because every language feature ever invented in any programming language gets added, or functions, methods and APIs accidentally becoming their own Turing complete language, because of all the parameters you can pass.
With compatibility being such a hyped term, I think it would be could for the industry if we’d use the right, rather than the most popular tools and building blocks to compose our systems. I also think it would help if not every new tool that came along would call every other “obsolete” or “legacy”, just because it goes a different route. People will take that to heart and think they have to shove the new tool into every little project. Not every new standard and technology must always take over and replace everything else, it can even remotely be imagined to replace. Doctors with their MRIs and what not also still use their eyes, a lamp and a wooden stick to take a look into your throat.
+100.
Markdown is valuable because of its limitations, not in spite of them. Learn a handful of syntactical rules — header syntax, emphasis syntax, list syntax, link syntax, and rules about indentation — and you basically understand the entire thing. That’s the whole ball game.
I found this perspective interesting - the author (whom I happen to e-know since way back) is unhappy with MD as a parseable format which is a usual techie gripe, but also notes that the HTML it produces is inconsistent and outdated.
The example above this would be impossible or unmanageable with raw HTML. There are specific code snippets for cross references and specific link types. At best you could use customElements, but then you’re locked into requiring client side JS or an experimental backend rendering pipeline.
I do think there’s some space for a more HTML-like, JSX inspired backend template language like
<CrossRef foo />, but that already exists and it’s called MDX…I find editing in vim really pleasant, especially coupled with an automatic formatter, ala
gofmt, I usepandocas a fixer via https://github.com/dense-analysis/ale.This reads to me like “I don’t like markdown because it promises not to do a bunch of things it was deliberately design to not do that I would like to be able to do.” It’s like saying “I hate Toyotas because they can’t fly.”
I quite like Markdown: because all I want are headers, paragraphs, and very light styling. Which is exactly what it was designed for, and handles very well.
Yes, that’s the impression I got as well.
Three out of four of my last F/T paid roles were as a tech writer. I encountered various tools, most horrible, partly because of the “docs as code” movement in FOSS which I personally dislike. I used Markdown a little and AsciiDoc rather more. (Never touched RST.)
But now I’m a journalist again, and Markdown has come to the fore as a really easy, quick, widely-understood format for writing for the Web. It does the core stuff I want, very easily, and the stuff that most of its critics kvetch about is stuff I don’t want and for which there are better tools.
For instance AsciiDoc is about as easy but can do tons more. If you want to write docs, Markdown is probably too simple. If it doesn’t do what you need, then use something that does.
I would not recommend MD for docs. I know lots of people are using it for stuff like that, and IMHO it’s a mistake. Anyone using MD and encountering friction or finding it inadequate is using the wrong tool and that is not MD’s fault.
I think Markdown is popular because it’s a reasonably intuitive bridge between how we format handwritten documents (which is itself a blend of what makes sense on the page, and an approximation of ~spoken rhetoric) and HTML.
In some cases (like the table example), what’s trivial on the page is painful with a keyboard. The technologies that shaped the old idioms didn’t have editability as a selection pressure. You can make a few edits inline, but at some point you’ll just have to rewrite the document.
Much of the power and pain of code are byproducts of the machines forcing us to be explicit, but we didn’t have the foresight to spend centuries molding ourselves (human languages, pedagogy, rhetoric) around that kind of precision. Markdown meets us very close to where we are. The other path, I think, entails developing toolchains that do expect that precision and requiring the humans to do the changing.
(I have been kinda picking at these ideas in two series of blog posts I’ve been writing this year, https://t-ravis.com/post/doc/what_functions_and_why_functions/ and https://t-ravis.com/post/doc/what_color_is_your_markup/)
Why is TCP so popular? TCP has a lot of issues and there are better ways to connect faster / more flexibly on the modern internet hardware that rarely drops packets, see HTTP 3 dropping TCP.
Simply because it “won”, it has a network effect, it was adopted on many websites and apps, so it had the advantage of being recognizable. Why do we think of Coke as #1 and Pepsi as “secondary”? Honestly it could have even been random. I’m just glad to have such a standard that is relatively widely adopted even though it is imperfect. And no, us markdown heads do not use an editor. We type our blockquotes one line at a time inside a web browser’s
<textarea>. Sometimes I even blockqoute 3 code blocks before breakfast.I’ve been vocal about Markdown being bad for the many of the reasons listed. The latest cramp about it is that there’s no defined way to do metadata. Want to include an author, editor, license, keywords, etc. well, tough luck. With AsciiDoc, Org Mode, reStructuredText, the specs define how to embed metadata in their documents. When I edit an ODF in LibreOffice or an SVG in Inkscape, there is a document properties menu for this. RAW images in Darktable, there’s a prominent “metadata editor” panel in the lighttable view. Having a way to embed metadata is the default behavior for digital creative work file formats, but Markdown doesn’t have it. There’s “front matter”, which is literally just an ill-defined, nonstandardized, non-portable table–and it took your document from being able to be rendered in many contexts to now looking like garbage on your Git forge with a table that you have to parse and realize isn’t the content (and this issue doesn’t exist with examples like AsciiDoc because the renderer knows in this context, it doesn’t need to render the metadata). Without metadata, you have attribution and licensing issues, and need to invent ad-hoc formats.
This I 95% don’t agree with. Where Markdown really doesn’t shine: writing blog posts and documentation–a place where you need more robust features like metadata, admonitions, attributions for blockquotes, collapsible block, etc. Markdown cannot deliver without getting locked into a “flavor”. I’m still slowly in the process of redoing my personal blog and there’s a mess to unravel because I originally tied myself to both the limiting Markdown but also got locked into a static site generator with a specific format I had to follow. Luckily, developers can, right now, go out and choose a better format for their projects (and no, this won’t make contributions harder because the text is still text).
But Markdown isn’t meant to provide these capabilities! If you need these things, then Markdown isn’t a solution for your problem. That’s fine! It doesn’t mean Markdown needs to change. It means you should pick something else, I guess, right?
That’s true. It works for things like comments here on Lobste.rs. However, developers not exposed to alternatives, aren’t realizing when they should be switching tools for the job and invent a bunch of incompatible forks and tools rather than moving to the tool for the job. That said, with AsciiDoc, reStructuredText, Org Mode, etc. you can write simple stuff too. It seems we’ve set unrealistic expectations to many that if it’s good enough for a limited functionality required for a comments section, it’s good enough for my blog, my README, etc. and generally it isn’t.
shrug I’m not sure that the capabilities afforded by markup languages more powerful than Markdown outweigh their costs, for the use cases that Markdown targets.
As an analogy, consider technical diagrams. I think there are basically 2 types of diagrams worth using: boxes-and-lines diagrams, to express component relationships in a system; and sequence diagrams, to express information flow between components over time.
I think raw ASCII is the best way to draw both of these diagrams, because the constraints that raw ASCII imposes on author expressiveness is actually virtuous. Anything that’s too complex to express in raw ASCII is probably too complex for typical consumers. Said another way, if you can’t draw it effectively in raw ASCII, then the thing you’re trying to draw probably needs to be simplified — broken up into multiple drawings, etc.
I think the same thing is more or less true for anything you could conceivably write in Markdown. If you feel like Markdown is a limiting factor, and you need your README or blog post to express things that aren’t possible to express, then I think it’s usually — not always! but almost always — an indication that you’re trying to express more detail than is appropriate for your audience.
Concretely: a README should probably not include semantic author attributions of its blockquotes. The consumers of READMEs do not benefit from this information, and the maintainers of READMEs suffer from the additional syntax required to express that concept. The same thing is more or less true for licensing information, keyword metadata, etc. etc.
I don’t know what goes into your blog posts but for mine, MD would be fine and I wish my current blogging site supported it for posts. It does for comments, which is very handy.
Yeah. I have collapsible blocks. I use admonitions (and not breaking the semantics of the
<blockquote>element). I attribute quotes properly. I have definition lists, glossaries, footnotes. My image tags have heights, widths, and titles. Sometimes my blocks and lists have titles that aren’t<h#>headings. Occassionally I need to add a one-off CSS class too. My blog has keywords, and descriptions, an author, licensing, and other metadata. When I use Asciidoctor, all of these features are built into the syntax and don’t require an ad hoc systems or additional tools (though I am electing to use Soupault to help iron the data into a format I like better). And without much thought I could turn these documents into a book in PDF form and not be littered with HTML tags. I can also host look at it on Gitea or GitLab if I needed for whatever reason and I don’t have eyesore elements to deal with my limitations.I would venture that your blog needs some of these features too, but you’re probably relying on an ad hoc format like front matter that prevents its portability, or are using some elements incorrectly (like list items with BOLD text instead of definition lists, or have inline HTML which ruins the plaintext aesthetic and breaks in some contexts.
Chuckle Nope.
If I were ¼ century younger, I’d reply
LOLnopeor something.Sometimes I remember to replace * bold * with actual bold tags, but that’s as close to formatting as it gets. No. It’s a quick place to put random thoughts, and in the instance of my tech blog, I generally copy-paste longer comments there to preserve them and offer them to a wider audience. Posts fairly regularly get shared on Lobste.rs so I guess it’s working.
This is sort of the point I was getting at: Markdown does all I need and more, and criticism of it is generally from people who need a different tool and so are misaddressing their complaints.
I am not in any way denigrating your blog or anything! I am just saying that there is a good place for quick’n’dirty tools and I like them.
This is why I dislike “docs as code”: because programmers’ editors are awful tools for a writer and I really dislike using them. I don’t want or need syntax highlighting, or line moves, or pattern matching. I really do need a live word count though, and nothing give me that since MS Word for macOS.
ADoc has uses. I am very happy that I do not need a single thing it does that MD doesn’t any more, and I wish more people used ADoc instead of MD.
That’s right. YAML front matter. Looks good & works great.
Some. But, it’s easy to remember and looks a lot better than AsciiDoctor syntax 💁🏻♀️
That’s the entire idea behind markdown: it doesn’t try to be the be-all, end-all. It’s a simple filter for when you wanna write HTML but don’t wanna have to type out every single br or p or a bref or h1. It’s an amazing tool on the editing side and that’s all it needs to be.
If you want to blog like you’re writing a thesis, more power to you. I personally just want to put pixels on screens, without having to worry about not closing tags. Markdown fills that need admirably.
Sure, but a lot of people don’t pay attention to the generated HTML and end up with unsemantic elements that ruin other tools trying to consume the HTML. In cases like excluding width/height on images lead to performance and rendering issues. A lot of this is exacerbated by the lack of robustness and because of folks without blame not wanting to “worry about not closing tags”, use the wrong semantics due to the tools afforded by Markdown. If just getting text out is the goal and not following the HTML semantics, then Gemini seems like the format to choose.
A specific example is admonitions where you see some folks using
**NOTE:** foo, but this leads to just a plain paragraph with bold text with nothing to separate it from the main content (and some don’t all caps it, and other don’t bold it). Other implementation overload and abuse the>for block quotes (with broken implementations like GitHub’s still using the<blockquote>when generated which isn’t semantic and violates the spec of “a section that is quoted from another source” instead of using something semantic like<aside>or generic like<div>) and the label part isn’t agreed on in these overloaded block quote ideas. Microsoft does something with[!note].The CommonMark RFC is for blocks starting like:::note, but it seems most aren’t using for one reason or the other. Admonitions are very common for code documentation, and AsciiDoc and reStructuredText don’t have competing ways to write it–it’s a part of the spec and doesn’t break semantics.I use
<aside>just fine on my blog, I use it all the time. I use it by simply typing<aside>which is easy enough to remember without having to do anything special. This is why dropping down to HTML is so awesome and part of Markdown’s magic.Yes. It works. Just like plain text email works or plain text SMS text messages work.
The easy of adding inline HTML isn’t the issue, it’s the use of unsemantic elements. This may be unintentional–especially for folks that haven’t read chunks of the HTML spec–but it’s still causing the wrong elements to be used. An informational admonition is complementary to the content, not a direct part of the document (which is why it’s often rendered in some form of call out). The blockquotes-for-admonition example mentioned is straight up wrong rather than an missing wrapper though. And when you see people create block quotes like
― Edward Snowden, https://www.reddit.com/r/IAmA/comments/36ru89/just_days_left_to_kill_mass_surveillance_under/crglgh2/
Now the quote attribution is in a generic
<p>paragraph tag and not properly grouped with<blockquote>This isn’t correct either because you’re missing the
<cite>. So does this mean are you going to always going to bother writing for every attributable quote (assuming this is the structure you want; I know<figure>is common too)? Will you remember to use the correct structure every time?when in AsciiDoc you can do this and not think about the HTML semantics as they are handled for you
This is exactly the level of programmer-brain semantic nitpicking that 99% of the population never should have to learn.
This is why in the olden days typographer was a separate job from journalist or authors, and these days why template designer is a separate job. So writers can be free to just write.
The fact that AsciiDoc has a way to do it is a strike against it for general users since they’re gonna be seen as dumb if they don’t do it semantically properly.
It’s possible to make a post-processor on the template language level to detect and fix those “footer”/“header” quote attributions by looking for foo bar: before the quote or –foo bar after the quote. (I should go set something like that up, thanks for reminding me; although in this case your proposed correct structure is incorrect since semantics can’t live on the class/id level and a footer is only appropriate for a document or section.) I don’t mind this sort of semantical type setting for the HTML target specifically. I do type
<cite>and<i>all the time (and use Markdown’s shortcut for em. Common things super easy while rare things like i and cite in a normal, straightforward style. That is the way).At the same time, I super appreciate that on gemtext, it’s not necessary. You just write and you’re done. Same goes for email, SMS, tweets, Mastodon etc. It’s just loosey-goosey text and it’s so functional and pragmatic.
Different formats have different semantical salience levels. On email you’ve got to get the “To:” correctly snd it’s also good to have “Subject:” and/or a “Body:”. In a printed book you might want page numbers.
The more of these semantical salience levels you slather onto a writer’s yoked shoulders, the worse their writing will be.
Also, the entire idea of the semantic web kinda failed. The more rules there are, the more rulebreaking texts there are. What’s the point? Some super web crawler evil AI gonna be even more correct in its dissection of humanity? Some of these semantic markups help screenreaders if they are applied consistently, like table navigation, but some don’t.
I don’t wanna have to learn AsciiDoc’s block structure syntax 💁🏻♀️ on top of having to learn the underlying HTML I also need to learn the semantics ins and out of (in order to be motivated to even use the AsciiDoc syntax in the first place)
I disagree. For me the purpose of the lightweight markup language is to hide having to remember some of the difficult semantics in a portable syntax that can be exported to many formats without having to think too hard about the source material. The semantic web still give you a) good heuristics to follow (solving the “naming things” problem) and b) lets you skip needing to add
role=*to elements to help with assistive technology. If you go further and use microdata, then you can free up needing to layout your markup in a very specific way for tools like the web crawlers–it also can disambiguates to a machine (i.e. is this date for created, updated, or published?) something that may be clear to a user visually reading content.If you don’t want to think about it too much, then it’s okay to use
<div>and<span>, but it’s not okay to use the wrong element (e.g. using a<blockquote>when it’s not quoting anything)I agree that Gemtext is the place for that sort of thing. In many ways, folks should aim to use
*.txtfiles if the goal isn’t to target HTML. GameFAQs was a better site when guides were plaintext and full of ASCII art over the HTML files–however, these formats don’t do the best job with accessibility or machines to understand the semantics. If SEO were less important, then still see curated lists like GameFAQs and Yahoo’s old search, but we have to appease the machines and if you play along with the semantic web, then there less ambiguous content for machines to error on. And at the end of the day, I find AsciiDoc’s plaintext semantics a lot easier to read than HTML as plaintext while being close enough to the ASCII text of the past.Right. I don’t use any divs personally because I have templating that does section, blockquote etc personally but I’ve argued again and again that Markdown-based languages, like on Reddit or here on lobste.rs, should have i instead of em since i is never wrong (and sometimes the only right one) but em can be wrong.
Screenreaders yeah, search engine’s no, we don’t. If peeps wanna find the site they can bookmark it ♥ or use links.
To me, the lightweight format doesn’t itself have to be this über catch-all ultra portable thing. If a good one existed (which is maybe not even possible, as we learned from DocBook’s failures), we could then have a markdown-like language that dropped into it. Like, take DocBook again as an example. Writing it becomes much simpler with a li’l filter that does para and emphasis and other super common things, while the more nitty gritty things like the info block can live in a template written directly in the DocBook language.
Put another way: the PSTCBETMF needs to be very broad in order to cover all the features of all possible targets while the LYAWI (language you’re actually writing in) only needs to cover the most common, everyday features of one expression source.
Like, take my text overview page: https://idiomdrottning.org/texts
There’s no way I’d wanna write that in Markdown or AsciiDoc or like YAML or HAML or Textile or something. It has sections and columns and links and all kinds of stuff. (Instead it’s all generated from a template I wrote with Liquid and XHTML directly.) Markdown is only good for writing text but it’s damn good there.
You’ve identified exactly where we disagree there. It becomes the worst of all worlds:
Take links for example:
The AsciiDoc version is barely any more readable! It totally breaks the reading flow.
Much more readable!
I think we agree about our disagreement here other than how and where we feel that line should split (and I can see your point). I don’t mind learning and remembering a bit more syntax to have more features and more easily turn it a document into a PDF or slides. I do care about the semantics quite a bit though.
The only call out here is that the
is closer to
in that it’s URL then text
and you can do
Just like you still need to label it in Markdown (but there’s a short hand if key matches your text)
URL before text?!😱 Cart before horse!
Footnote-superscripts don’t come before the phrase they’re attached to.
The page you’re gonna visit next doesn’t come before the text you’re reading now.
Well… we all wants things to be as simple as possible. But then I say no simpler. If I want syntax for all those features, I know where to find it. I don’t need to create a semaphore system of smoke signals and shadow puppets where I can write what I in turn meant to actually write. There’s no reason the syntax for those special features should be like AsciiDoc’s mystical squares and commas instead of a normal, full-featured, real, explicit syntax.
It’s not as if I need to write those “explicit syntax” parts tediously, character by character, either; my blogging system isn’t a typewriter so I’ve set it up to prompt me for things. What category should this be? What is the URL to that thing I square bracketed?
And when I need to do weirder things like this treasure generator I have an escape hatch from the simple convenience layer (Markdown) into the real thing (HTML). Right there in the same blog.
I learned recently that Asciidoctor supports Unicode bullets,
•, for list items, and that is enough to sell me. Type what you mean.Yeah, I’ve talked to Gruber about adding them to Markdown too.
It’s just that the square bracket percent sign comma magic in AsciiDoc is such an unsell.
Authors who want to quote something will have a few things at hand:
A usable markup syntax for quotes can’t assume that all of these bits of metadata will be available. If all you have is #1, you shouldn’t have to know about #2 or #3 to express your intent. And, in all cases, you should be able to express your intent without deep knowledge of the tool you’re using.
If you wanna quote something, the ASCII text default way to do that, understood by every human on the internet, is more or less this:
Whatever syntax you have for quoting has got to support that as a base case. Given that, the question becomes how to optionally layer-on the other bits of metadata — author, and origin URL — in a way that works with this base assumption. And
is I guess not it?
You have that option too if you want it: https://docs.asciidoctor.org/asciidoc/latest/blocks/blockquotes/#markdown-style-blockquotes
Sure, but the optionality is itself a problem. Even if I don’t use a particular feature myself, I still have to know about it, in order to understand the output of others.
Markdown suffers from this, too. You can maybe make a case for both the
-and*markers for un-numbered lists, but I can’t see any reason for the===syntax to denote headings. There are probably other ambiguities, too.In the ASCII days it was common to use heading like (as is the case with reStructuredText)
This is supported in AsciiDoc, but they probably found it a bit obtuse and impractical in many cases and used the
=sigil. What on Earth would make#more meaningful?#has several structural advantages over===, I think. It sits on the same line as the heading, so it’s easier to parse for both humans and computers. It supports arbitrary levels thru repetition, and it’s intuitive:# H1and## H2and etc. make sense. And because it prefixes the header text rather than underlining it, the typography always basically “works”.c.f.
It’s just much cleaner. (shrug) all IMO of course
Wait what? Did you think underline was the only style supported? AsciiDoc normally, from my experience, wants users to do
That is no different other than the sigil. You can even see this in practice in the raw version of the heading documentation for Asciidoctor, as well as the rendered docs. And due to “Section levels must be nested logically.”, you can’t nest improperly, something Markdown doesn’t enforce and was a pain I had to deal with recently.
The only time I personally use the underline option is for the main title for stylistic reasons, because it adds visual separation for the metdata and makes it stand out in the visual hierarchy as the document title
Yeah, I did! Neat that AsciiDoc lets you use
=as a prefix like that. Markdown doesn’t, and that was my point of reference. I don’t use AsciiDoc, in large part due to the sort of optionality we’re talking about right now. If a language allows its users to express a given outcome (e.g. an tag) in more than one way, I see that as a problem that needs to be fixed. YMMV, of course!What does “nesting improperly” mean? AFAIK this isn’t a concept that exists in the headers produced by e.g.
# Headingor## Subheadingin Markdown. That syntax translates directly to<h1>or<h2>which are tags that need to be closed but otherwise carry no semantic value.The text you wrote there is pretty complex in terms of sigils and syntax and demarcated sections and etc. For a human reader of that plain text, it is IMO substantially more difficult to understand than the XML or HTML that would be produced from it. And again IMO this is a direct result of the set of features, and the optionality of syntax, which AsciiDoc (?) provides. It’s fine if you don’t agree! People are different, no problem. But if you PR’d a project I maintained and added docs in that format, hard no from me 😉
edit: If all of that information is strictly necessary, and this Markdown version
is in some respect insufficient in terms of expressiveness, then I just can’t grok the value prop of an intermediary language between that and straight up HTML/XML. Those languages are meant to be basically human-readable, right?
This may be a legacy thing, as a lot of old docs supported the underline style. It makes parsing more complicated which is relevant, but as a user, it’s not a big deal and can be skipped.
From their docs:
I have seen users do this wrong–especially when focusing on the visual style a heading provides instead of the semantic one for the document (e.g. Why did you make this an
<h4>? Because I wanted the text smaller.).What’s happened here is that you’ve built an ad-hoc system. It’s not that it’s not readable as plaintext–it’s easier to read–but it caries no underlying semantic value.
How is the parse reasonable supposed to assume these are not just sections with content? How would I create a regular sections called “Abstract” or “Metadata”?
Did you want a definition list? (Oh, Markdown doesn’t support this 🙃). These get rendered as plain
<li>elements without any concept of key/value that. Do I have to escape:if I need it in a key? What’s up with keywords being comma-separated? Is this another ad-hoc convention (vs.<dl><dt>Keywords</dt><dd>foo</dd><dd>bar</dd><dd>baz</dd></dl>)?In the case of Asciidoctor, I can do something with this metadata labeled as such:
docfileformats to add additional metadata to various parts of files if I need something special<head>but not rendered in the document)–with Markdown, because it’s ad hoc, they can only assume it always needs to be displayed)Abstracts are a special part of the document with a special meaning. You often want to style it differently. This was one of this issues I had recently trying to parse a lot of different people’s Markdown files they sent me; some people had an Abstract with a heading, some had a paragraph with nothing to delimit it and others started with a generic paragraph that wasn’t an abstract. Others started with a backstory instead. Without a heading, you can’t reasonably assume a block is the abstract or not or what order these elements are in. If the user specifies it, it’s clear.
So I guess a good way of summarizing what I’m trying to say here is that if you need to express “underlying semantic value” in a document, you should not use a plain-text markup language like Markdown (for sure) or AsciiDoc (IMO) in the first place. These tools are not meant to provide a high degree of semantic expressiveness. They’re meant to provide the bare minimum set of capabilities — mostly typographical — while maintaining plain-text legibility.
Ah! Maybe this is a point. Tools like Markdown aren’t meant to produce mechanically parseable output. They’re meant to produce typographically acceptable documents that can be “parsed” by human readers.
Maybe AsciiDoc tries to solve a different set of use cases. That’s cool! But it means the tools aren’t really comparable. When I’m writing a GitHub comment or whatever, semantic annotation features are actively harmful to my user experience.
If you want semantically meaningful, mechanically parsable documents, then why not just write HTML/XML directly? With care, it’s absolutely human-readable — it was designed to be so! And you don’t lose any expressive power in translation.
I wouldn’t disagree with the assessment, but I would disagree that human-readable isn’t the only goal. Machines parse our markup for SEO, for web scraping, and we can use that metadata in interesting ways like creating an outline or feed. In these cases, having a semantic makes these transformations easier and parsing more accessible. I feel the advantages of AsciiDoc or reStructuredText are big enough and don’t change enough that they’re still “lightweight markup languages” while having more expressiveness. While I had an hunch this mattered and switched on personal stuff a while ago, but it was much more apparent whenl I touched a recent project in which I was tasked to wrangle multiple authors’ different Markdown style that it became so apparent that the project really could have used a switch in the syntax for compliance and consistency. We ended up having to build sidecar files for the metadata but authors chosen a format with metadata, this could have been avoided, easier to manage, and less buggy.
In this document the attribution is in a
<p>paragraph outside the which implies it is correct according to the standard:https://html.spec.whatwg.org/multipage/grouping-content.html#the-blockquote-element
(second example, author is “Stephen Roberts”)
Edit re: the cite attribute, the same document states
(My emphasis)
I’d much rather have the citation source linked to the attribution “element”, like so, to make it easier for readers to follow the link. I don’t really care about statistics about a site’s use of quotations.
You are correct!
I had thought the attribution needed to be outside the
<blockquote>, but this isn’t the default layout for Asciidoctor and I was assuming they were right in their semantics. I doubled back on what I originally written under those assumptions, but it seems they are wrong and I’m happy I had another opportunity to reread the spec (even if it was just a few lines down from what I had linked for how<blockquote>was being misused for admontions).I will raise an issue with them now.I think they know about it (there is a migration to adopt more HTML5 and semantic HTML in the future) and theasciidoctor-html5sdoes it closely enough.Right, it should’ve been
What’s caught my eye recently is the
asciidoctor-html5salternative backend for Asciidoctor. I know there are long-term goals for the Asciidoc project to modernize its HTML representation, but this is something that can be used now.My biggest missing feature for AsciiDoc would be:
<abbr>tags for accessibility–ideally in a manner where the<abbr>s would be automatically added as I wrote and they were automatically appended to the glossary. You don’t realize how much jargon people write until you step a little out of your own spaceI added support for
<abbr>tags to my own markup language. I define the bunch that I use at the top of the document and anywhere the acronym or abbreviation appear in the text, an appropriate<abbr>tag is generated. It fails if you use an acronym with two different meanings (e.g. “the IRA (Irish Republican Army) has its own IRA (Individual Retirement Account)” for a silly example) but it has rarely come up. I have had to special case a bunch since acronyms can come in many forms (D&D, GHz, IPv4, NaNoGenMo) but it generally works.I use
<abbr title="Three Letter Acronym">TLA</abbr>.Perfect example of why just dropping down to the HTML you already know is better than having to figure out some arcane syntax to learn in order to generate the HTML semantics that you also need to know & be aware of in order to use them.
What happens when you want to convert this to another format that isn’t HTML? This is lock-in–lock-in you might be okay with, but it does hamper other uses.
I just have a bunch in a text file and I wrote a Blosxom plugin to replace them when the HTML is generated.
Here’s my announcement https://gerikson.com/blog/scrivener/Defining-acronyms.html, old enough to vote next year….
404 × 2
Whoops, private repo. Updated the link.
More builtin* metadata options (docinfo files do exist)
I was a fan of Textile before Markdown took over. In retrospect, I’m not sure it was the clearly superior language. It leaned hard on existing knowledge of HTML. After years of Markdown seeping into everything, I’ve become accustomed to its many limitations and quirks. Markdown is more readable in its raw form, which I’ve come to appreciate. All I wish now is that John Gruber would make peace with the people who are trying to make it better and let them use the name. I think it would go a long way toward unifying a fragmented landscape of implementations.
I don’t know Gruber or what his deal is, but trying to read between the lines of the few things he’s written on the topic, I get the impression that to him Markdown is not a file-format. Instead, Markdown is the idea of writing a quick-and-dirty script to transform the thing you want to write into the format you want to produce, ignoring the corner-cases you don’t care about. GitHub-flavored Markdown is Markdown, Textile is Markdown, ABC notation is Markdown. The syntax that everybody else calls Markdown is just the syntax that one particular tool happened to support on the particular day it got popular, and doesn’t have a greater claim to the name than any other, and certainly doesn’t deserve to be preserved forever as The Official Definition of Markdown.
That said, I think the CommonMark syntax is pretty comfortable, and despite its quirks, I get a lot of value out of being able to use familiar formatting conventions in just about every textbox on the Web. The world might genuinely be a better place if there were just One Standard Markdown we could use everywhere, but I’m sympathetic to the idea that maybe it wouldn’t.