FWIW, just a couple of weeks ago we started doing that for a new sqlite subproject: https://sqlite.org/wasm
With the exception of one page, all of them are markdown, rendered on demand by the Fossil SCM. The one exception is an HTML file, which we need in order to host a small JS application.
When you say rendered on demand, you mean by the client, as in a page request? Why not just rerender to HTML on developer change? Genuinely curious why rendering on demand is preferred in this case.
> Why not just rerender to HTML on developer change?
Because that's not how the Fossil SCM renders content. It has a cache, but only for certain high-CPU data like generation of zip files of the source tree. Caching markdown docs wouldn't work in all cases, anyway: when you link to a ticket, for example, it gets rendered differently depending on whether it's opened or closed. Thus the renderer has to know the current status of any fossil-internal constructs a doc links to. Of course, we could say "just update the cache of all docs which link to a ticket every time the ticket is updated," but That Way Lies Madness. In an Enterprise-level system that would possibly be worth doing. For the Fossil SCM it's overkill.
Though re-rendering on every page hit _sounds_ bad, we've been doing it in the Fossil SCM since it went into being and it has never caused us any undue performance issues. Every doc you see on <https://fossil-scm.org/home>, as opposed to the non-doc URIs, is served directly from the SCM db and all (or very close to all) of it is either markdown or Fossil's older/original wiki format, both rendered on demand. CPU load is minimal and rendering is "fast enough" for everything we've ever done with it.
> AsciiDoc is a plain text markup language for writing technical content. It’s packed with semantic elements and equipped with features to modularize and reuse content.
Nice! You don't need the HTML and BODY tags though.
I think however this defeats the purpose: yes you're delivering the content as Markdown, but you have to deliver it as `text/html` for it to be rendered, so anyone fetching it can't tell it's Markdown content. Also every document has to have (invisible-ish) HTML junk appended
A "better" solution would be a browser that sends the `Accept: text/markdown, text/html` header and a server that serves Markdown only when requested.
Let's just embrace the chaos and develop a new flavor for every browser until there are precisely 31 different flavors of Markdown. We cap it there, Baskin Robbins style, and then watch the world burn.
We could have a higher level language and tooling that transpiles everything to all known markdown flavors and bundles them all. But I guess one of these 31 flavors already does that.
Make a World Wide Markdown Consortium, release v1 of Markdown based on a randomly picked flavor, let it stagnate for decades, then let Google implement shadowMarkdown in Google Chrome, which renders at 300FPS for them, and unluckily falls back to a JS polyfill that ends up solving a rubik's cube before every character it renders. Once that has gone for long enough, let Google form their own MHATWG and pretend it's open while they keep a majority of the seats, to steer the evolution of WebMarkdown.
Also Safari still doesn't support headings for some reason.
My personal preference would be GitHub flavored markdown, since as a coder it includes a lot of very useful non-standard markups. The compromises it makes on the non-deterministic markup elements are acceptable as well.
Many of the GitHub readmes are in markdown already, so people are quite familiar with it and there might already be an open source package that renders it out…
I guess it wasn't clear, but I meant those markdowns are rendered on everyones github page.. But the whole github pages thing is new to me. Very cool and seems like what the blog post was asking for.
Like how they're introducing admonitions syntax by overloading the blockquote sigil that makes it difficult or impossible to nest, has a heavy English bias, and doesn't even transform the underlying element making the use of blockquote unsemantic. They also just skipped the CommonMark RFC and other implementations throwing their weight into the ring with no regard for prior art. I also don't think a corporation, Microsoft, needs to be in charge of the spec either. No thank you.
It isn't as supported as I'd like, but it does exist and I've encountered it "in the wild" a few times, so it's not just some guy typing away on a website either.
After all these years, I still haven't found an important argument in favor of CommonMark. As I point out every time someone presents it as the answer, it doesn't handle things like math, so you still need to use unstandardized extensions, making the whole thing pointless.
The argument is that if you disqualify everything for not having $FEATURE, where $FEATURE varies from person to person, you have also essentially disqualified markdown entirely. As the saying goes, everyone uses only 10% of Microsoft Word, but everyone uses a different 10% of Microsoft Word. Much the same thing applies to this case for much the same reasons. If your standard is going to be "I want everything in any variant of Markdown ever and also any plugin ever", you will end up with something that is just as complicated as HTML, only different this time. (Possibly even more complicated than HTML.) CommonMark is a decent solution to "I want to use Markdown", if you're willing to take the simplification.
Note in this case I don't think there's anything wrong with refusing the simplification. It's just that if that is your set of your requirements, you've disqualified Markdown entirely. Personally, I think that is the state of the situation; Markdown can't do this. Markdown and all of its family members and close friends intrinsically work by reducing the problem. If you refuse to reduce the problem, you've refused to use Markdown. That is not a moral judgment; that's an engineering judgment. From the position the major browsers operate in, they will never attain anywhere near enough agreement on this to ever implement it without it simply becoming another monster of its own as everybody piles in with all their favorite extensions.
I have some websites that run with Hugo, which is in principle based on Markdown, but if necessary you can have raw HTML pages or other things too. This is actually the ideal; use Markdown when it makes sense, use other things when it doesn't, and thus, neither of those two things has to carry the burdens of the other side. This is the real and best solution, honestly, and it also has the advantage that it's here now. Use whatever flavor you want, where ever you want, whenever you want, today. I'm doing this and I don't see any advantage to trying to convince the browser to do this. I have a deploy step regardless of what I do, so it's no skin off my nose whether that step deploys my pages raw or there's a render step in addition to the deploy.
All dialects of Org Mode, AsciiDoc, reStructuredText, HTML files, ODF files, EXIF data on images support metadata in file--it's the norm. The fact that Markdown's spec doesn't support metadata by default and most "dialects" don't this ad hoc syntax (YAML of all broken things) shows that Markdown not suitable for most kinds of documents.
agree that it'd be nice to have a markdown file be rendered inherently within the browser so i don't have to use haroopad on my windows machine, but it feels like we're just going to reinvent HTML
Agreed, original HTML was not too different than markdown really. (But more standard, and slightly more powerful with things like tables, code blocks, and definition lists, all of which are only non-standard extensions to markdown!)
Maybe what OP really wants is a lot more people to write HTML without _any_ CSS or Javascript. But that's already more or less available, so there are reasons people don't do it to grapple with.
Perhaps a mode where you tell the browser to ignore any CSS or Javascript; possibly also in this mode the browser could use better more readable standard html rendering, similar to what most markdown renderers choose by default (bigger font sizes and line-height, more and more even whitspace around headings, maximum page width, etc), instead of the legacy choices they are now sticking with for backwards compat.
> Perhaps a mode where you tell the browser to ignore any CSS or Javascript; possibly also in this mode the browser could use better more readable standard html rendering, similar to what most markdown renderers choose by default (bigger font sizes and line-height, more and more even whitspace around headings, maximum page width, etc), instead of the legacy choices they are now sticking with for backwards compat.
Oh, I was thinking of a mode that the _page source code_ would trigger somehow, instead of the client triggering on a page that was possibly written to be full of complex CSS and JS. But also, maybe? It does seem related to OP. I am just brainstorming, don't have anything particularly thought out.
I am imagining instead a mode that tells the user-agent "Use your own standard HTML stylesheet, and it's allowed to change and be updated over the years, to fix bugs and improve design, you don't have to stick with your default styles from 30 years ago,' but "use the same stylesheet you are using for other pages in this mode, I don't want to have to come up with it, and I don't want it to be fixed in time to what I come up with today either or require my maintenance"
That is, i suppose, more like "reader/readability mode" in all those aspects--but triggered by the source instead of by the user.
But, sure, a CSS stylesheet is another thing. I'm just thinking around the use cases I think OP is setting out; you can do so too, with other suggestions, you don't have to try telling me I mean something other than I mean to do so!
Reader mode also attempts to discard "unimportant" content – if you intentionally enter reader mode, it's fine to discard even things like the page navigation, but not so much for a browser's default mode.
Plus sometimes it's too overeager and discards content that shouldn't actually be discarded (e.g. I'm hosting some radio show transcripts, and with my markup Firefox's reader mode discards the bit of text indicating who's actually speaking).
Recently there was a thread about GitHub Blocks, interactive elements within READMEs and Markdown files in general. If we could standardize that and support it, that would be cool.
You mean stuff that is already standardized and in Asciidoctor? That would be easier than trying to wrangle in all of these forks/flavors with all their incompatible extensions and tools all while have no way to handle metadata?
I would love to use more markdown but I need multidimensional layouts decided by the author (variable columns with text and images) and I haven't seen anything like this.
Part of the benefit of Markdown is that you can view the raw source and still get useful info out of it. But this site prerendered the Markdown and served HTML which defeats part of the purpose.
Markdeep is good at progressively mixing HTML & MD so you can choose how much of each to put in to your page. I use it for mostly MD + MathJax notes + some HTML/JS/SVG/Canvas/WebGL for when I want dynamic graphics in my notes.
HTML is already a markup language. You could just as easily make basic websites using HTML and some basic inline CSS.
(They’d even have some extra features missing from Markdown that I’d consider still part of a basic content formatting suite like floating or multi-column layouts. They’d even have a defined standard for machine readable metadata!)
The problem is that people don’t make websites like that very often, even though they can. This is trying to solve a problem that doesn’t currently exist.
What Markdown provides here is an even lower barrier to entry for the majority of people... they just write text, learn a fraction more Markdown to so more... and if they want total control they eventually learn HTML too.
It's not mutually exclusive... Markdown includes HTML.
—I’d say it’s the other way around isn’t it? Wouldn’t Markdown be a subset of HTML, since all markdown can be expressed in HTML but not all HTML can be expressed in Markdown?—
Edit: Markdown can contain HTML that gets meaningfully interpreted as markup as well.
I’d also say HTML is not difficult to write, even for someone new to the concept. I don’t think anyone making their GeoCities homepage was too strained learning HTML, and those were leagues more advanced than what’s possible with only Markdown!
If you want people to be excited about self-publishing online again, it’s probably best to start with the markup language that allows for some fun :)
If say 10% of the pool of internet users at the time could make an HTML page on Geocities, what % of today’s pool of internet users could do it? The pool has gotten much larger and much less tech savvy on average.
So you can't create a simple markdown rendered without creating a full-blown html/css renderer. So a cli renderer doesn't make sense either in that case.
Html 'support' is just a hack for any shortcomings of markdown.
To be fair, you can include Markdown inside script tags (assign a custom type like "text/markdown") and render this (the script's innerHTML) by another script.
If you think about it in terms of syntax, then sure. Markdown is a superset of HTML. I think it's much more meaningful to compare their semantics instead. From that point of view, Markdown is a nicer, more human-readable syntax for a very small subset of html, plus an escape hatch to reach the rest of HTML using conventional syntax.
Markup is not the barrier to entry. Nobody in 2022 is building HTML-only websites. Even 20 years ago CMSes let hundreds of thousands of people write blogs online.
Let's say somebody takes the time to learn Markdown. Then what?
Are they going to then also learn how to select a web host, how to set up SSL, how to use CSS to make the website look the way they want?
They won't. That's why Wordpress, and later Facebook, won the online publishing wars.
Yes, so all websites are already written in markdown. Its just tjat No browsers support the typical header/list shorthands, but that doesn’t matter because even if they did you’d still need more tages to get interactivity and styling working.
People aren’t imagining a world where markdown makes anything simpler they are imagino by that a format change would make people build less complex websites. But why would they? It’s not HTML that makes the Twitter front end or Facebook complicated, it’s the desisted functionality, which wouldn’t change even if the spice code looked more like markdown and less like html.
So are Markdown rendering libraries entirely pointless? I'm not sure where you'd get the impression that HTML is a subset of HTML rather than Markdown being a superset of HTML. (even that is very reductive, though)
I spend a good part of my week writing docs. The docs that come out of Markdown are hard to read, hard to maintain, long, ugly, and limited, requiring postprocessing for simple things like a Table of Contents. Websites need content to be even richer than docs (and no, Mr. Developer, what you want is not the sole requirement of the rest of the people on the planet). If you want to make an entire website out of Markdown, make Markdown suck less.
I think we need a configuration format for websites. Configuration formats are designed for humans first, and fit to purpose. What might that format require? Probably: style, layout, macros, emeddable objects, inheritable/overrideable values, logic, loops, etc. Basically a DSL. You describe independent blocks (layout, style, content, etc) and the browser takes the instructions and renders the result. Not insanely different in concept than HTML/CSS, but everything could use one common format, in a manner more human-friendly than we have now, content would be independent of form/function, and none of it would inherit some unrelated design principles from some antiquated non-human-friendly technology.
text "Employees table description" |
This is a description of the employees table.
The name and e-mail address are listed to the right.
table "Employees"
@Name ~> Frank
Suzanne
Rahul
Aman
@E-mail address -> frank@me.com
suzanne@me.com
rahul@me.com
aman@me.com
style "table.Employees"
@Name
column
bgcolor "green"
@"Email address" rows bgcolor "gray"
layout "main-page"
panel "1"
align: left
content "text.Employees table description"
panel "2"
align: right-of "layout.main-page.1"
content "table.Employees"
You've described a static site generator, which I mean not as "hey you should have known that" but more as a "good news, that basically exists and you can use it now!"
No, there's no standard with static site generator, but there never will be. The combination of the wide variety of needs and use cases and the ease of starting one of these up (I can literally bash together the skeleton of a useful static site generator in 4 hours, and this isn't just "oh I could recreate dropbox in a weekend if I wanted to because I am a swaggering HN programmer", it is something I've literally done rather than sit down and learn someone else's because it was faster to bash something together than read docs) means that there will never be a shortage of these, and none of them will ever managed to capture 99% of the market to become a de facto standard.
I basically have websites that work the way the author describes. There's no particular need or benefit from expecting the web browsers to do this. There are disadvantages to this approach but the web browser directly rendering the markdown doesn't really solve any of them.
I mean it _sounds_ good, but how will we cram a million ads down user's throats and measure every twitch of their input devices? It's almost as though the author is suggesting that web site proprietors might be more interested in "serving content" than "driving engagement" which I find disturbing and upsetting.
But the engaged clickable web is anyways dead. This post is a static HTML file hosted on IPFS with no back links to my carefully curated blog and media presence. No branding. It's because I've accepted that people's bullshit-radar is sensitive towards overly optimized engagement content. Rather I want my text to be read and those that care will anyways online-search me. It's not my idea btw. The web has reached peak clickability: https://tedgioia.substack.com/p/has-the-internet-reached-pea...
I think covid is when the internet jumped the shark for Joe Average.
You would get banned from twitter, facebook, reddit, instagram etc for saying what was official policy until _yesterday_. The sheer insanity of that policy left the terminally online in charge everywhere and the quality of every website suffered. If I look back to reddit posts which google still brings up more than half the people are banned. These are people who wrote thousand word replies to technical problems and were pillars of the community. The only ones left are the mentally ill unemployed since they are the only ones who have time to keep track of what is allowed there.
HN was headed down the same hole until that hilarious post by PG about heretics that got flagged for 8 hours. I imagine at that point it hit everyone in charge here that the people making the most noise were not their friends.
Markdown could potentially replace HTML as a more succinct markup language but it's not sufficient by itself because it has no way to represent styling and layout. You'd need to jam CSS into it somehow
> We really need a new publishing tool for everyone that doesn't require intricate knowledge of how the entire web computing stack functions.
That tool is called HTML. It is usually supplemented by CSS. Every Markdown element has a one-to-one translation to it. This webpage is a particular stylesheet, plus basic HTML elements that you could write in <> style just as easily as you could write them in *_# style. If HTML requires particular defaults to look right, then that is a really great reason to fix the defaults, but not a really great reason to junk the whole thing and start over.
Markdown isn't particularly good, it isn't particularly standardized, and it isn't even compatible with reader mode (e.g. images). Just write HTML. Browser standards have not degraded to the point that you need to write a web page differently than people wrote them fifteen years ago for it to look the same; a toolbox with a million complicated tools and one obvious screwdriver is not a toolbox that makes it very hard to unscrew screws.
Don't forget that markup refers to the document's formatting and markdown is a specific markup library that converts text-to-HTML. So technically all browsers do support markdown.
We should re-visit the actual term "mark-up" which refers to decorating copy during the editing phase. I think many people agree that using markdown to "mark-up" copy on websites is easier.
Completely agree. It's already pretty easy to create a nice readable page with an off-the-shelf stylesheet & semantic markup.
Sites choose not to do that, for non-technical reasons.
For all it's faults, this is partially what AMP aimed to solve, by restricting what developers could do. However, developers/businesses didn't adopt AMP because it was a better user experience, they adopted it because it got them higher up in Google search.
This doesn't really make sense, for a couple reasons...
There are many flavors of markdown. We'd need a standards body, compatibility suites, etc., and for all the browser vendors to adopt it.
Meanwhile, markdown is designed to transform to HTML, which browsers already render. Adding a markdown-to-html plugin/step to your web server or publishing process is not exactly the most burdensome thing, relative to everything else it takes to develop, publish, and maintain a site. And it resolves the markdown flavors issue.
The thing is, people could choose to publish, simple uncomplicated sites now -- it would be cheap and easy, too. The HTML is barely more complicated than the equivalent markdown, and it would take a few lines of CSS to apply a basic style.
The many sites that choose to be complicated, cluttered, and expensive will continue to be so, for the same reasons they are now. Markdown would just be another way to build simple sites, which they don't want.
I get this, but OTOH it is IMO best to distribute digital artifacts in the format that is most useful for editing or creating derivative works. This is the free software philosophy but also a societal good. Many of us learned HTML and web technologies by reading the source code of websites, and we've closed that door behind us with all of the build steps that turn our actual code into a computer-readable-only mess which we send out for consumption by normal users' browsers. It would be nice if "view source" showed you something like what the author actually wrote in their text editor.
you can distribute websites as markdown! Return markdown with a plain text content type and it'll show as markdown, which was designed to look good as-is and not require rendering to HTML
Markdown is supposed to (be able to) look good as-is. Most people's Markdown doesn't look good as-is, though. They target the GitHub renderer and come from the GitHub-listing-as-a-product-landing-page school of thought, so even project READMEs are generally a mess.
Presumably if you want to "distribute digital artifacts in the format that is most useful for editing or creating derivative works", like parent said, you would make it look good.
Exactly this. I was paraphrasing the definition of source code from the GPL: "The source code for a work means the preferred form of the work for making modifications to it."
This isn't an unknowable hypothetical. No need to presume anything. Markdown found in the wild is a mess. The GitHub Flavored Markdown renderer even encourages it.
This is actually horrible for society as it implies that the Web Browser will have to implement a billion different parsers for all of the separate file formats it supports, which not only causes it to have a ridiculously large attack surface but pretty much implies there will only be a couple serious separate implementations (if even that soon...) as it is just too difficult for even a large company now to build a browser.
Meanwhile, it doesn't even ensure the property of being able to view source, as people can and do obfuscate things they don't want you to see, and if people want you to see the source code there is nothing preventing them from making that entirely pipeline visible, including, but certainly not limited to, shipping a trivial markdown parser to the browser instead of doing the conversion on a server.
In a perfect world, the browser should have simply provided something like canvas hooked up to something like WebAssembly, and we should have provided for everyone a trivial markup file format rendered that people could include by default and a handful of graphic file format implementations that could be easily mix-and-matched to pull just the ones people wanted into their site.
I came to write something similar to this, basically.
If anything we should push for websites to divide content from presentation: if html tags were used properly there would be no need for markdown.
And on that matter, pushing for proper use of html tags in documents is a more achievable goal than asking everybody to just drop html and write markdown.
This fails to differentiate a "standard" from simply a "specification" (of a format, protocol, language...). I.e. we don't say "PostScript standard", but rather a "PostScript specification".
All of the claims they make apply to any specification, and yes, divergence is necessary to make progress.
A standard is a commonly agreed to specification, frequently ratified in one or another international organization (ISO, IETF, ECMA, W3C...). The main value of a standard is in ensuring interoperability where that matters more than all the other concerns raised.
Eg. we'd never have much of the internet if people didn't simply settle on the IP (v4) protocol.
This xkcd is always posted when anything related to a standard is mentioned, but almost never in response to a standard that was actually created to unify all standards in its space.
That's a pretty narrow reading of that XKCD: even the examples it gives are not the result of attempting to unify a set of standards.
Eg. AC chargers had a bunch of different, diverged "standards" for pretty much restricted use-cases (those 1.5mm x 4mm connectors and then micro- and mini-USB). Text encodings had multiple standards for encoding the same text (eg IBM, Windows code pages and ISO encodings) without unification attempts.
In both of these examples, there is one unifying standard added (USB-C and UTF-8 + Unicode) that did stop the proliferation of new standards.
But majority of things never result in one unifying standard that can do everything win: even SGML brough up in this discussion is an example. CORBA also springs to mind.
Gemini it's the needed standard between Gopher, tied to small devices with a 80 column display, and the Web with enforced encyption for security but without requiring lots of resources.
The difference is 30 years of websites and tools being built on HTML. There's an opportunity cost to consider: is formatting simple websites in Markdown and rendering them natively that much more valuable than simply writing them in HTML or using a Markdown-to-HTML tool that it's worth the cost of creating standards, implementing them in browsers, etc. as opposed to putting those efforts elsewhere?
If you were starting from scratch, maybe. But it seems like we've already reached a point where existing solutions for Markdown-to-HTML get you almost all of the value and none of the cost.
It's the extra complexity to move markdown rendering from the control/responsibility of the server side, where it fits naturally, to the user-agent side, where it doesn't -- and for something that site publisher can already do (and evidently, rarely want to do).
RFC 7763 does not define Markdown in any way. It acknowledges both the popularity and messiness of the Markdown family of syntaxes, registers a so-broad-as-to-be-nearly-useless media type for the family, and establishes a registry of variants (https://www.iana.org/assignments/markdown-variants/markdown-...).
Critically here, it does not recognise Markdown as a usable markup format in its own right. Only as a family of often ill-defined syntaxes that may be tolerably readable in raw form, and with the correct, unspecified tools may be converted to a formal markup language like HTML.
“Markdown” is utterly unsuitable as a publishing format. It’s designed as a writing format.
>There are many flavors of markdown. We'd need a standards body, compatibility suites, etc., and for all the browser vendors to adopt it.
Well, if it were to be adopted by vendors, the many flavors would be a non-problem. They can just agree on a flavor and be down with it. There's CommonMark anyway, they can just use that.
They render as loose lists (note the ugly spacing that appears) regardless of the number of new lines between them:
https://imgur.com/VEiAZKV
The workaround is adding a tab (or other character, like a braille space) between the lists, which really makes them one list:
https://imgur.com/Z5WLy6w
I didn't say there wasn't a standard. Just because there is a standard doesn't mean it works well. Hence the whole "more than one standard" situation...
For people considering adding Markdown support to web browsers or other publishing tools, please consider adopting Djot instead: https://github.com/jgm/djot
It's very similar to the Markdown syntax we all know and love/hate, but fixes many inconsistencies in the spec, and also makes it possible to parse a document in linear time, with no backtracking. It is also much fuller-featured than commonmark, with support for definition lists, footnotes, tables, several new kinds of inline formatting (insert, delete, highlight, superscript, subscript), math, smart punctuation, attributes that can be applied to any element, and generic containers for block-level, inline-level, and raw content.
Looks like it simply makes Markdown easier for both computers and humans! I love this and can’t believe I haven’t seen it before.
> Requiring quirky behavior and blank lines that hurt reading
Really? The linked spec says, referring to a blank link in indented lists:
> reStructuredText makes the same design decision.
And as a design goal:
> your document [must be] readable just as it is, without conversion to HTML and without special editor modes that soft-wrap long lines. Remember that source readability was one of the prime goals of Markdown and Commonmark…
Or this, which made me celebrate:
> anything that is indented beyond the start of the list marker belongs in the list item.
In Markdown it’s really hard (aka impossible) to get sections to respect the indentation level they belong to. What a simple rule here: inside a list, items belong to their list item. Beautiful!
Other great quotes:
> we don't need two different styles of headings or code blocks.
> avoid using doubled characters for strong emphasis. Instead… use _ for emphasis and * for strong emphasis
> code span parsing does not backtrack. So if you open a code span and don't close it, it extends to the end of the paragraph
Sanity. Sanity introduced to an ambiguous spec. It’s wonderful.
This bit made me a little unsure:
> although we want to provide the flexibility to include raw content in any output format, there is no reason to privilege HTML. For similar reasons we do not interpret HTML entities, as commonmark does
While Markdown was meant to transform to HTML, I wish it was a spec renderable without a HTML or web browser layer. So I like this. Equally though one use case I personally have is Markdown to static HTML and it’s useful having HTML tags present and handled. So my understanding of this part of the spec is confused (what does “interpret” mean?) but if it means no support for inline HTML that is indeed a pity.
> reStructuredText makes the same design decision.
"This other product that doesn't understand the appeal of Markdown and also thought this was a technical problem rather than a user barrier to entry problem made the same mistake" is not exactly a strong defense.
> Sanity. Sanity introduced to an ambiguous spec. It’s wonderful.
Users don't care how hard or easy something is to parse. You write a parser once; you write Markdown millions of times.
> Looks like it simply makes Markdown easier for both computers and humans! I love this and can’t believe I haven’t seen it before.
Unfortunately it does not. This is less readable and more annoying to write:
>Markdown:
>- Fruits
> - apple
> - orange
>
>djot:
>- Fruits
>
> - apple
> - orange
These are fundamentally different products. If you want something easy to parse and human readable, use YAML. If you want something easy to write, use Markdown.
I don’t mind pressing Enter twice instead of once.
I know that’s a glib answer. And I agree an extra line break should, to a human which reads indents, be unnecessary. But given the ambiguities of Markdown, something that is both human-readable and computer-readable is a huge advantage.
Also,
> Users don't care how hard or easy something is to parse
I don’t read it as about parsing. I read it as about writing. You can write one way and know exactly how it will be interpreted.
> So my understanding of this part of the spec is confused (what does “interpret” mean?) but if it means no support for inline HTML that is indeed a pity.
All its saying is that that djot doesn't have special rules for HTML so it spits out the same thing it receives, apparently with escaping relevant to the selected output mode. Note right above the part you quoted it shows an example of using HTML ("we simply do not allow raw HTML, except in explicitly marked contexts").
>Markdown is a text-to-HTML conversion tool for web writers. Markdown allows you to write using an easy-to-read, easy-to-write plain text format, then convert it to structurally valid XHTML (or HTML).
> Thus, “Markdown” is two things: (1) a plain text formatting syntax; and (2) a software tool, written in Perl, that converts the plain text formatting to HTML.
I believe nowadays most people refer to (1) instead of Perl tool, when talking about Markdown.
Personally I use Markdown *a lot* for Flutter apps, where text is rendered natively. Also use it for legal documents, which are converted to PDF via pandoc. Another project I have is a console app that also shows formatted help text written in Markdown. In all these cases there is no HTML whatsoever and no 'text-to-HTML conversion tool'. Yet it's all Markdown, so no need to reduce its applications to HTML, let alone claiming that it's designed "to transform to HTML".
350 comments
[ 4.6 ms ] story [ 419 ms ] threadWith the exception of one page, all of them are markdown, rendered on demand by the Fossil SCM. The one exception is an HTML file, which we need in order to host a small JS application.
Yup.
> Why not just rerender to HTML on developer change?
Because that's not how the Fossil SCM renders content. It has a cache, but only for certain high-CPU data like generation of zip files of the source tree. Caching markdown docs wouldn't work in all cases, anyway: when you link to a ticket, for example, it gets rendered differently depending on whether it's opened or closed. Thus the renderer has to know the current status of any fossil-internal constructs a doc links to. Of course, we could say "just update the cache of all docs which link to a ticket every time the ticket is updated," but That Way Lies Madness. In an Enterprise-level system that would possibly be worth doing. For the Fossil SCM it's overkill.
Though re-rendering on every page hit _sounds_ bad, we've been doing it in the Fossil SCM since it went into being and it has never caused us any undue performance issues. Every doc you see on <https://fossil-scm.org/home>, as opposed to the non-doc URIs, is served directly from the SCM db and all (or very close to all) of it is either markdown or Fossil's older/original wiki format, both rendered on demand. CPU load is minimal and rendering is "fast enough" for everything we've ever done with it.
http://prose.io/
Isn't that the opposite of Markdown?
People who propose replacing markdown with AsciiDoc completely miss the point of Markdown in my opinion.
Here's the example:
Now, whether this is wise to encourage or not I can't speak to.It would be great if browsers parsed markdown as text-only
[1]: https://news.ycombinator.com/item?id=25352385#25355751
I think however this defeats the purpose: yes you're delivering the content as Markdown, but you have to deliver it as `text/html` for it to be rendered, so anyone fetching it can't tell it's Markdown content. Also every document has to have (invisible-ish) HTML junk appended
A "better" solution would be a browser that sends the `Accept: text/markdown, text/html` header and a server that serves Markdown only when requested.
Also Safari still doesn't support headings for some reason.
Many of the GitHub readmes are in markdown already, so people are quite familiar with it and there might already be an open source package that renders it out…
Its using "Jekyll" to render those "github-pages" sites https://github.com/jekyll/jekyll
It isn't as supported as I'd like, but it does exist and I've encountered it "in the wild" a few times, so it's not just some guy typing away on a website either.
Note in this case I don't think there's anything wrong with refusing the simplification. It's just that if that is your set of your requirements, you've disqualified Markdown entirely. Personally, I think that is the state of the situation; Markdown can't do this. Markdown and all of its family members and close friends intrinsically work by reducing the problem. If you refuse to reduce the problem, you've refused to use Markdown. That is not a moral judgment; that's an engineering judgment. From the position the major browsers operate in, they will never attain anywhere near enough agreement on this to ever implement it without it simply becoming another monster of its own as everybody piles in with all their favorite extensions.
I have some websites that run with Hugo, which is in principle based on Markdown, but if necessary you can have raw HTML pages or other things too. This is actually the ideal; use Markdown when it makes sense, use other things when it doesn't, and thus, neither of those two things has to carry the burdens of the other side. This is the real and best solution, honestly, and it also has the advantage that it's here now. Use whatever flavor you want, where ever you want, whenever you want, today. I'm doing this and I don't see any advantage to trying to convince the browser to do this. I have a deploy step regardless of what I do, so it's no skin off my nose whether that step deploys my pages raw or there's a render step in addition to the deploy.
It would be very hard to make a case for CommonMark over something like Pandoc markdown, given that it does so much more than CommonMark.
Note that the discussion here is markdown inside a browser. That's not a good place to go with a dramatic simplification.
Being there, why not just implement full org-mode in browsers natively, and use it instead of html?
agree that it'd be nice to have a markdown file be rendered inherently within the browser so i don't have to use haroopad on my windows machine, but it feels like we're just going to reinvent HTML
Maybe what OP really wants is a lot more people to write HTML without _any_ CSS or Javascript. But that's already more or less available, so there are reasons people don't do it to grapple with.
Perhaps a mode where you tell the browser to ignore any CSS or Javascript; possibly also in this mode the browser could use better more readable standard html rendering, similar to what most markdown renderers choose by default (bigger font sizes and line-height, more and more even whitspace around headings, maximum page width, etc), instead of the legacy choices they are now sticking with for backwards compat.
Isn't that just Reader Mode?
I don't personally use any "reader mode" much.
I am imagining instead a mode that tells the user-agent "Use your own standard HTML stylesheet, and it's allowed to change and be updated over the years, to fix bugs and improve design, you don't have to stick with your default styles from 30 years ago,' but "use the same stylesheet you are using for other pages in this mode, I don't want to have to come up with it, and I don't want it to be fixed in time to what I come up with today either or require my maintenance"
That is, i suppose, more like "reader/readability mode" in all those aspects--but triggered by the source instead of by the user.
But, sure, a CSS stylesheet is another thing. I'm just thinking around the use cases I think OP is setting out; you can do so too, with other suggestions, you don't have to try telling me I mean something other than I mean to do so!
Plus sometimes it's too overeager and discards content that shouldn't actually be discarded (e.g. I'm hosting some radio show transcripts, and with my markup Firefox's reader mode discards the bit of text indicating who's actually speaking).
Also, isn't this basically what HTML does anyway?
clean speech warning: swearing. https://youtu.be/_CEBG_s92P8?t=398
A better option would be to use something like https://casual-effects.com/markdeep/ and serve the MD/HTML file. Then you can get a client-rendered HTML (https://casual-effects.com/markdeep/features.md.html) or view the raw MD (https://casual-effects.com/markdeep/features.md.html?noforma...) if the browser doesn't support HTML.
Markdeep is good at progressively mixing HTML & MD so you can choose how much of each to put in to your page. I use it for mostly MD + MathJax notes + some HTML/JS/SVG/Canvas/WebGL for when I want dynamic graphics in my notes.
I'd never subject a reader to this kind of horrible UI.
(They’d even have some extra features missing from Markdown that I’d consider still part of a basic content formatting suite like floating or multi-column layouts. They’d even have a defined standard for machine readable metadata!)
The problem is that people don’t make websites like that very often, even though they can. This is trying to solve a problem that doesn’t currently exist.
You can include in Markdown any and all HTML.
What Markdown provides here is an even lower barrier to entry for the majority of people... they just write text, learn a fraction more Markdown to so more... and if they want total control they eventually learn HTML too.
It's not mutually exclusive... Markdown includes HTML.
Edit: Markdown can contain HTML that gets meaningfully interpreted as markup as well.
I’d also say HTML is not difficult to write, even for someone new to the concept. I don’t think anyone making their GeoCities homepage was too strained learning HTML, and those were leagues more advanced than what’s possible with only Markdown!
If you want people to be excited about self-publishing online again, it’s probably best to start with the markup language that allows for some fun :)
I feel like the Venn diagram is nearly a circle, but I don’t have anything to back that up.
To most people, symbols and words being “special” in some text = coding, I’m still not convinced that the cognitive load of:
# my title
Is different than
<h1>my title</h1>
HTML can’t contain Markdown at all - a ### in HTML does nothing but a <strong>hello</strong> in Markdown does exactly what you expect it to.
Html 'support' is just a hack for any shortcomings of markdown.
It depends on your parser. Commonmark, for example, has rules for entering html mode: https://spec.commonmark.org/0.29/#html-blocks
Neither is truly a superset of the other.
HTML is not difficult to write, it's difficult to edit.
A S-expression-based dialect of HTML (with macros!) would be fun.
Markdown specific syntax is not valid in HTML pages, but all HTML is valid in Markdown.
Let's say somebody takes the time to learn Markdown. Then what?
Are they going to then also learn how to select a web host, how to set up SSL, how to use CSS to make the website look the way they want?
They won't. That's why Wordpress, and later Facebook, won the online publishing wars.
Yes, so all websites are already written in markdown. Its just tjat No browsers support the typical header/list shorthands, but that doesn’t matter because even if they did you’d still need more tages to get interactivity and styling working.
People aren’t imagining a world where markdown makes anything simpler they are imagino by that a format change would make people build less complex websites. But why would they? It’s not HTML that makes the Twitter front end or Facebook complicated, it’s the desisted functionality, which wouldn’t change even if the spice code looked more like markdown and less like html.
I think we need a configuration format for websites. Configuration formats are designed for humans first, and fit to purpose. What might that format require? Probably: style, layout, macros, emeddable objects, inheritable/overrideable values, logic, loops, etc. Basically a DSL. You describe independent blocks (layout, style, content, etc) and the browser takes the instructions and renders the result. Not insanely different in concept than HTML/CSS, but everything could use one common format, in a manner more human-friendly than we have now, content would be independent of form/function, and none of it would inherit some unrelated design principles from some antiquated non-human-friendly technology.
No, there's no standard with static site generator, but there never will be. The combination of the wide variety of needs and use cases and the ease of starting one of these up (I can literally bash together the skeleton of a useful static site generator in 4 hours, and this isn't just "oh I could recreate dropbox in a weekend if I wanted to because I am a swaggering HN programmer", it is something I've literally done rather than sit down and learn someone else's because it was faster to bash something together than read docs) means that there will never be a shortage of these, and none of them will ever managed to capture 99% of the market to become a de facto standard.
I basically have websites that work the way the author describes. There's no particular need or benefit from expecting the web browsers to do this. There are disadvantages to this approach but the web browser directly rendering the markdown doesn't really solve any of them.
/s
But the engaged clickable web is anyways dead. This post is a static HTML file hosted on IPFS with no back links to my carefully curated blog and media presence. No branding. It's because I've accepted that people's bullshit-radar is sensitive towards overly optimized engagement content. Rather I want my text to be read and those that care will anyways online-search me. It's not my idea btw. The web has reached peak clickability: https://tedgioia.substack.com/p/has-the-internet-reached-pea...
The social media has gone absolutely toxic in an frantic attempt to maximize revenue per user.
You would get banned from twitter, facebook, reddit, instagram etc for saying what was official policy until _yesterday_. The sheer insanity of that policy left the terminally online in charge everywhere and the quality of every website suffered. If I look back to reddit posts which google still brings up more than half the people are banned. These are people who wrote thousand word replies to technical problems and were pillars of the community. The only ones left are the mentally ill unemployed since they are the only ones who have time to keep track of what is allowed there.
HN was headed down the same hole until that hilarious post by PG about heretics that got flagged for 8 hours. I imagine at that point it hit everyone in charge here that the people making the most noise were not their friends.
https://gemini.circumlunar.space/
I wrote a similar spec for lists: https://lists.sh/spec
The renderer is crazy simple when you can figure out the type by reading the first 4 chars of each line.
That tool is called HTML. It is usually supplemented by CSS. Every Markdown element has a one-to-one translation to it. This webpage is a particular stylesheet, plus basic HTML elements that you could write in <> style just as easily as you could write them in *_# style. If HTML requires particular defaults to look right, then that is a really great reason to fix the defaults, but not a really great reason to junk the whole thing and start over.
Markdown isn't particularly good, it isn't particularly standardized, and it isn't even compatible with reader mode (e.g. images). Just write HTML. Browser standards have not degraded to the point that you need to write a web page differently than people wrote them fifteen years ago for it to look the same; a toolbox with a million complicated tools and one obvious screwdriver is not a toolbox that makes it very hard to unscrew screws.
https://xkcd.com/927/
yeah, no. I can't tell if this is some kind of parody or what
We should re-visit the actual term "mark-up" which refers to decorating copy during the editing phase. I think many people agree that using markdown to "mark-up" copy on websites is easier.
https://daringfireball.net/projects/markdown/
Sites choose not to do that, for non-technical reasons.
For all it's faults, this is partially what AMP aimed to solve, by restricting what developers could do. However, developers/businesses didn't adopt AMP because it was a better user experience, they adopted it because it got them higher up in Google search.
There are many flavors of markdown. We'd need a standards body, compatibility suites, etc., and for all the browser vendors to adopt it.
Meanwhile, markdown is designed to transform to HTML, which browsers already render. Adding a markdown-to-html plugin/step to your web server or publishing process is not exactly the most burdensome thing, relative to everything else it takes to develop, publish, and maintain a site. And it resolves the markdown flavors issue.
The thing is, people could choose to publish, simple uncomplicated sites now -- it would be cheap and easy, too. The HTML is barely more complicated than the equivalent markdown, and it would take a few lines of CSS to apply a basic style.
The many sites that choose to be complicated, cluttered, and expensive will continue to be so, for the same reasons they are now. Markdown would just be another way to build simple sites, which they don't want.
Yes please. Perfect: to want something that can be done; to need something that can happen.
HTML is an extensible language. Markdown is not.
Meanwhile, it doesn't even ensure the property of being able to view source, as people can and do obfuscate things they don't want you to see, and if people want you to see the source code there is nothing preventing them from making that entirely pipeline visible, including, but certainly not limited to, shipping a trivial markdown parser to the browser instead of doing the conversion on a server.
In a perfect world, the browser should have simply provided something like canvas hooked up to something like WebAssembly, and we should have provided for everyone a trivial markup file format rendered that people could include by default and a handful of graphic file format implementations that could be easily mix-and-matched to pull just the ones people wanted into their site.
If anything we should push for websites to divide content from presentation: if html tags were used properly there would be no need for markdown.
And on that matter, pushing for proper use of html tags in documents is a more achievable goal than asking everybody to just drop html and write markdown.
[1] https://gemini.circumlunar.space/docs/faq.gmi
All of the claims they make apply to any specification, and yes, divergence is necessary to make progress.
A standard is a commonly agreed to specification, frequently ratified in one or another international organization (ISO, IETF, ECMA, W3C...). The main value of a standard is in ensuring interoperability where that matters more than all the other concerns raised.
Eg. we'd never have much of the internet if people didn't simply settle on the IP (v4) protocol.
Eg. AC chargers had a bunch of different, diverged "standards" for pretty much restricted use-cases (those 1.5mm x 4mm connectors and then micro- and mini-USB). Text encodings had multiple standards for encoding the same text (eg IBM, Windows code pages and ISO encodings) without unification attempts.
In both of these examples, there is one unifying standard added (USB-C and UTF-8 + Unicode) that did stop the proliferation of new standards.
But majority of things never result in one unifying standard that can do everything win: even SGML brough up in this discussion is an example. CORBA also springs to mind.
If you were starting from scratch, maybe. But it seems like we've already reached a point where existing solutions for Markdown-to-HTML get you almost all of the value and none of the cost.
For browsers to also support markdown, there should be some use case that isn’t already well-supported.
It's the extra complexity to move markdown rendering from the control/responsibility of the server side, where it fits naturally, to the user-agent side, where it doesn't -- and for something that site publisher can already do (and evidently, rarely want to do).
Chances are your client already handles a bunch other than HTML like SVG. Or even contextual ones like WebVTT.
[0] https://www.rfc-editor.org/rfc/rfc7763.html
RFC 7763 does not define Markdown in any way. It acknowledges both the popularity and messiness of the Markdown family of syntaxes, registers a so-broad-as-to-be-nearly-useless media type for the family, and establishes a registry of variants (https://www.iana.org/assignments/markdown-variants/markdown-...).
Critically here, it does not recognise Markdown as a usable markup format in its own right. Only as a family of often ill-defined syntaxes that may be tolerably readable in raw form, and with the correct, unspecified tools may be converted to a formal markup language like HTML.
“Markdown” is utterly unsuitable as a publishing format. It’s designed as a writing format.
Well, if it were to be adopted by vendors, the many flavors would be a non-problem. They can just agree on a flavor and be down with it. There's CommonMark anyway, they can just use that.
If you have two lists separated by only new lines: https://imgur.com/IFejJvX
They render as loose lists (note the ugly spacing that appears) regardless of the number of new lines between them: https://imgur.com/VEiAZKV
The workaround is adding a tab (or other character, like a braille space) between the lists, which really makes them one list: https://imgur.com/Z5WLy6w
Which makes it render in a less worse way: https://imgur.com/F5lc0ek
This is expected behavior per CommonMark.
There is a number of browser extensions that render Markdown nicely. Install one, and get your friends do the same.
Make your web server serve markdown files with a Content-Type: text/markdown or even text/plain header. Put some Markdown files there.
Enjoy. It should just work.
HTML has had the exact same problems.
You can say "CommonMark spec" and it's solved, isn't it?
Standard is not only specification, but also tacit agreement by many parties to use same standard.
People that have skin in the game usually want a say on what flavour should it be.
It's very similar to the Markdown syntax we all know and love/hate, but fixes many inconsistencies in the spec, and also makes it possible to parse a document in linear time, with no backtracking. It is also much fuller-featured than commonmark, with support for definition lists, footnotes, tables, several new kinds of inline formatting (insert, delete, highlight, superscript, subscript), math, smart punctuation, attributes that can be applied to any element, and generic containers for block-level, inline-level, and raw content.
Some examples, showing how Djot would be rendered into HTML: https://htmlpreview.github.io/?https://github.com/jgm/djot/b...
Standardization of the spec is good. Requiring quirky behavior and blank lines that hurt reading is bad.
> Requiring quirky behavior and blank lines that hurt reading
Really? The linked spec says, referring to a blank link in indented lists:
> reStructuredText makes the same design decision.
And as a design goal:
> your document [must be] readable just as it is, without conversion to HTML and without special editor modes that soft-wrap long lines. Remember that source readability was one of the prime goals of Markdown and Commonmark…
Or this, which made me celebrate:
> anything that is indented beyond the start of the list marker belongs in the list item.
In Markdown it’s really hard (aka impossible) to get sections to respect the indentation level they belong to. What a simple rule here: inside a list, items belong to their list item. Beautiful!
Other great quotes:
> we don't need two different styles of headings or code blocks.
> avoid using doubled characters for strong emphasis. Instead… use _ for emphasis and * for strong emphasis
> code span parsing does not backtrack. So if you open a code span and don't close it, it extends to the end of the paragraph
Sanity. Sanity introduced to an ambiguous spec. It’s wonderful.
This bit made me a little unsure:
> although we want to provide the flexibility to include raw content in any output format, there is no reason to privilege HTML. For similar reasons we do not interpret HTML entities, as commonmark does
While Markdown was meant to transform to HTML, I wish it was a spec renderable without a HTML or web browser layer. So I like this. Equally though one use case I personally have is Markdown to static HTML and it’s useful having HTML tags present and handled. So my understanding of this part of the spec is confused (what does “interpret” mean?) but if it means no support for inline HTML that is indeed a pity.
"This other product that doesn't understand the appeal of Markdown and also thought this was a technical problem rather than a user barrier to entry problem made the same mistake" is not exactly a strong defense.
> Sanity. Sanity introduced to an ambiguous spec. It’s wonderful.
Users don't care how hard or easy something is to parse. You write a parser once; you write Markdown millions of times.
> Looks like it simply makes Markdown easier for both computers and humans! I love this and can’t believe I haven’t seen it before.
Unfortunately it does not. This is less readable and more annoying to write:
>Markdown:
>- Fruits
> - apple
> - orange
>
>djot:
>- Fruits
>
> - apple
> - orange
These are fundamentally different products. If you want something easy to parse and human readable, use YAML. If you want something easy to write, use Markdown.
I know that’s a glib answer. And I agree an extra line break should, to a human which reads indents, be unnecessary. But given the ambiguities of Markdown, something that is both human-readable and computer-readable is a huge advantage.
Also,
> Users don't care how hard or easy something is to parse
I don’t read it as about parsing. I read it as about writing. You can write one way and know exactly how it will be interpreted.
The comparison to commonmark is important - it has special rules for HTML: https://spec.commonmark.org/0.29/#html-blocks
All its saying is that that djot doesn't have special rules for HTML so it spits out the same thing it receives, apparently with escaping relevant to the selected output mode. Note right above the part you quoted it shows an example of using HTML ("we simply do not allow raw HTML, except in explicitly marked contexts").
Is it though?
From 2004
https://daringfireball.net/projects/markdown/
I believe nowadays most people refer to (1) instead of Perl tool, when talking about Markdown.
Personally I use Markdown *a lot* for Flutter apps, where text is rendered natively. Also use it for legal documents, which are converted to PDF via pandoc. Another project I have is a console app that also shows formatted help text written in Markdown. In all these cases there is no HTML whatsoever and no 'text-to-HTML conversion tool'. Yet it's all Markdown, so no need to reduce its applications to HTML, let alone claiming that it's designed "to transform to HTML".