Markdown within HTML


I think it could be useful to allow Markdown processing within HTML. Markdown is already used all over the web (including right here), with processing done both server- and client-side. Baking it into HTML or a related spec could help standardize all the existing flavours out there (e.g. “classic” Markdown, Markdown Extra, Github Flavored Markdown, etc.), could make it easier for authors (both web devs and content authors) to use, and could hopefully improve performance.

There are two ways I could see this working:

  1. A new <markdown> element
  2. <pre> with a new prop/attribute (e.g. markdown, or formatting="markdown")

Both would be easy to polyfill with JS markdown processors, but using <pre> would also present relatively easy-to-read fallback text, even if a polyfill (or JS) wasn’t available. Using an attribute like formatting="markdown" also opens up the possibility of including other types of formatting in the future, such as Textile.

One potential pitfall is licensing: Markdown is licensed under “a BSD-style open source license”, and I have no idea how this plays with spec license stuff.

I’d love to hear your thoughts on this.


This sort of thing has been brought up before, and in similar contexts (an element for displaying CVS as a table, etc).

The main problem is that it’s unclear how to expose the markup inside of it. Possibly it could be generated in exposed Shadow DOM these days? You’d still have to explicitly style it, rather than having it pick up styles from the page (a b selector won’t style <b> elements inside of shadow DOM; you need to do pre[markdown]::shadow b).


@newtron Markdown itself would need a clear specification; something which has been lacking for some time actually. Last time I checked there were some failed attempt at formalising it and also a working group suggestion which didn’t get any uptake. Even Jeff Atwood failed to get a specification.

Besides the issues mentioned by @tabatkins I think there are also syntactical issues; there isn’t really any embedded meaning into markdown nor is there any way to extend it - even just to provide id’s.

There is the other worry that opening the door to text encoding formats will get every encoding writer out there suggesting the same to the W3C too; We could quickly see suggestions for Jade, Textile, BBCode.


This is why I think a custom element would make the most sense. People who want Markdown can use it.

If it turns out every site on the internet is using it within a few years, then we’d have a stronger case for baking it into browsers.


@domenic sure write it as a quick JS lib that shim’s the behaviour and test the adoption. The problem for me would be the task in specifying it first / adoption of the favourite Markdown.

The other problem as I see for the custom element is that encoding; I think should be an attribute level decision - like language or text direction. We could end up in many text encoding elements which for me doesn’t make sense: <bbcode /> <textile /> <jade /> <haml /> <etc />

I would shoot more for the parameter which could be added to block level elements.


Custom elements that provide a draft of proposal and can compete with other options should really be the default answer for any new tag suggestion. Pickup won’t always be based on what we might expect and that’s ok. Sometimes to even evaluate and give good feedback we need something to use and discuss. I say take a crack at a concrete proposal/element


I looked for threads about it on various mailing lists and wasn’t able to track anything down. If you have links, I’d love to take a look at the past discussion.

I actually really like the idea of doing it in the Shadow DOM.

That’s a great point, and definitely an obstacle, but if there’s interest I don’t think it should stop us from at least making the attempt. In fact, I think it’s encouraging that Jeff Atwood is interested in standardizing Markdown, because it might mean he, his readers, and other like-minded folk might be interested in getting involved if we try to revive the effort.

Some flavours of Markdown actually do allow for adding classes and IDs. See, for example, Markdown Extra’s special attributes. That said, I agree that no matter what flavour of Markdown gets encoded, it’s not going to be a perfect match for HTML and its semantic or syntactic power. I don’t think it needs to be, though.

The use case isn’t to use Markdown for the entire web, it’s to address a specific pain point where Markdown is already being used: user-generated content. Most websites that use Markdown now do so for comments, posts, and other content generated by users that either don’t need a lot of detailed control, don’t have the technical knowledge to write full HTML, or where full HTML can’t be trusted.

It could happen, but I’d argue that if there’s enough interest in actually standardizing it, implementing it, and maintaining it, then that isn’t necessarily a bad thing. This possibility is why I’d prefer the <pre formatting="markdown"> approach, for better extensibility later.

That does make sense, but then we’d be stuck with <markdown> instead of, as I mentioned above <pre formatting="markdown">. Not the end of the world, but it’s not as clean IMO. Also, I’m not sure what benefit a custom element would have over the existing server- and client-side solutions out there. In fact, we can already see that many sites are using Markdown, even if it’s not “every site on the internet”.



In general, I agree that’s probably the right approach. But seeing as how we already know that Markdown is widely-used, and that an actual element is probably not the best solution, I don’t think a custom element is the right approach here.


@newtron Markup is not universally written or universally used in the same way - there is no data for a markdown attribute or tag. Your assertion about extensibility or preference is actually at the end of the day your own preference. It may well be that the community thinks <jade> and <textile> are ergonomically (or for some reason functionally) better than formatting="markdown" on a <pre>. I expect if you make the later with a good spec as a proposal, you will quickly find someone doing it as a tag too. Put something out there - them compete and evolve a bit - there is little value and much risk in going from debate to spec. If you can get a draft and actual usage with a convincing case for the formatting attribute version, it will ultimately speed things up, not slow them down IMO.


Oh ya, definitely, it is just my opinion/preference. But it’s a preference based on some reasoning, that I outlined above and will try to clarify below:

First, given the possibility of future formatting types, I think an attribute is more flexible and extensible than a series of new tags. Maybe I’m wrong. I realize that in terms of priority of constituencies, focusing on this type of “elegance” is pretty low, so if there are decent user, author, or implementer reasons to prefer tags, then that’s fair.

Second, I think fallback content would be easier to deal with for the average author if the markdown existed in a <pre> tag, simply because, e.g.,

* one
* two
* three

is easier to read than

* one * two * three

A <pre> tag would at least allow the inherent readability of Markdown come through without any additional work on the part of the author. However, maybe I’m wrong about this, too.

If the community disagrees with any of the above reasoning or has good counter-arguments, I’m more than willing to hear about it. I’m not set on any on particular syntax or anything, but I’m not convinced that going the custom element route will help us learn anything new.

Sorry, I’m not entirely clear what you’re suggesting here. If you’re saying to do a spec draft + polyfill for the attribute, developed simultaneously, then I definitely would agree that it’s a good approach.

Regardless of the approach though, I’m actually more interested to see how much interest there is from the standards community and implementors. I suspect there’s author interest (which we could hopefully gauge with the draft + polyfill or custom element or whatever), but there’s no point working on it if there’s no interest from implementors and/or standards folks.


Yes, a prollyfill… Write a draft, then try implementing it outside the browser. You will learn new things about the problem space, you will create something actually useful to developers. Developers will try to use it, they’ll tell you about what isn’t working for them, it may give them real value for real needs right now regardless of whether that particular thing ever becomes a standards - that’s a healthy incentive for involvement that is historically upside down. Use means you’ll get feedback which will make the proposal better - and we’ll know whether it’s getting uptake or whether a competitor is born that more people prefer, etc. It could also die hard. Either way, this creates a nice tight feedback loop that involves developers and doesn’t get hung up in years of debate about abstract things not actually involving developers… See the Extensible Web Manifesto

There are some things which are sort of non-starters and there are things which everyone is immediately interested in… Both are rare and I don’t think that this is either. More usually it is somewhere along a spectrum and all of the incentives are historically at odds with one another. We’d like to change that. If there is a good proposal, implementation, use, etc - implementors and standards community will take notice. Specifiction is especially great here because it brings together developers with ideas, makers/users and standards folk. Seriously, I’d encourage you to put together a solid proposal and implementation - or even two (one as a tag the other as an attr and try to make the case why one is so much better).


@briankardell Great, I think sounds reasonable. Anybody on here interested in helping out with a draft or polyfill?


@newtron I’m certainly willing to take a look, review code and help where I can.


Did somebody say polyfill? Count me in!


So we (myself but mostly Ciro Santilli) have a Markdown Test Suite in active development with an interop table. The goal was more or less to understand the state of implementations before creating a specification.

I didn’t really take the time to push the specification, but any pull requests are welcome. The test suite results will help to understand what is widely deployed and what is muddy.


Thank you for this, I had noticed the group on W3C; various other attempts at writing tests and specifications before - I have a feeling I saw this in its early inception.

This certainly looks like the most mature implementation so far and the best starting place; I will take a look over this tonight.


Two problems which can be avoided with one solution:

  • yes, as long as Markdown enthusiasts are not able to agree on one syntax, there is no chance in hell they would agree on it for the purposes of HTML specification. The only result will be that some randomly chosen syntax prevails (original Gruber?, Github?, something randomly chosen by currently present member of the committee?) and for the rest of the Universe proponents of other dialects will complain that this is solution of nothing because it lacks feature foo.

  • and of course: why Markdown? I prefer reStructuredText and the list of other simple-this-is-jus-ttext-not-markdown markdown formats is endless.

So, what is the MAGIC which saves us from all these problems?



You get all good parts (you have your <markdown> (or more likely <x-markdown>) element, and yet you don’t wait on the hell getting frozen, err, I mean, Markdown specification getting united (and of course don’t forget … the moment you create your standard, you just split the community even more). Actually, if your element is really succesful you may contribute to the world peace, err, I mean, Markdown unification.

You also don’t have to wait on the browser manufacturers to agree with your great idea. You can use Web Components right now ( or or some others).

And of course, if I want to create <x-reStructuredText>, nothing in the world stops. Just my laziness, lack of time, and lack of passion for the endeavor.


@jonathank I added this morning the other test suites efforts in the README


Get done a real specification for Markdown (plus extensions) or rather write a more generic specification for lightweight markup languages whereof Markdown is a valid profile. Get a MIME type assigned to it. Popularize it for use in e-mail, i.e. get mail clients to parse it. Get browsers to support it directly, i.e. as a file format. Make CSS apply to it. Don’t try to mix it with HTML – it’s been a bad idea in the first place for Markdown to allow one to mix it with HTML-like elements.


I know there are a couple of custom elements already made - for example


At the fear of this site turning into tumbleweed, I thought I would make another comment.

@karl are you accepting changes to this repo for the specification or are you waiting for the tests to indicate which features are supported in all parsers you are testing with?

I couldn’t see any of the popular Markdown parsers written in JavaScript as part of the testing suite; this obviously would be key to writing browser shims.

The other thing that I struggled to work out was which test were failing in which parsers too; if this was obvious (perhaps something that could be published in Markdown to Github pages with some JS to make it similar to a simple caniuse) then I think the parsers themselves could have bugs filed.

Anyway I appreciate the great waves you have made into standardising this so far.