Ridiculously simple markdown displayer - a native web component based on Custom Elements v1 specs to load and display an external MD file.
Instantly create beautiful HTML pages from Markdown. Like it isn't easy enough.
While it's already remarkably trivial to render markdown into HTML (Marked) and syntax-highlight (Prism),
<zero-md> does this better, automagically rendering into its own self-contained Shadow DOM container, while encapsulating implementation details into one embarassingly easy-to-use package.
Because web components. All in ~100 lines of code.
Let's get this money
Basic usage via CDN (recommended)
- Import webcomponents-loader.js.
<!-- Lightweight client-side loader that feature-detects and load polyfills only when necessary -->
Note: It seems there has been a regression in
webcomponentsjs that broke support for Firefox
v60 as reported in #19. If you need to support super old Firefoxes, it's recommended to pin
<!-- Load the element definition -->
<!-- Simply set the `src` attribute to your MD file and win -->
- Use your own markdown and highlight stylesheets instead.
<!-- Pass in an array of CSS URLs via the `css-urls` attribute in valid JSON format -->
- Or pass markdown strings directly into the element.
<!-- Declare `<template>` element as a child of `<zero-md>` --><!-- Wrap your markdown string inside an `<xmp>` tag --># `This` is my [markdown]()H~~ell~~o *W*o**r**l***d***!
- Or pass your own CSS definitions directly into the element.
<!-- Declare `<template>` element as a child of `<zero-md>` --><!-- Wrap your own CSS styles inside a `<style>` tag -->
- Or put it all together.
<!-- Declare `<template>` element as a child of `<zero-md>` --><!-- Wrap your CSS styles inside a `<style>` tag -->
Instantly publish HTML from Markdown
Create a beautiful HTML web page from Markdown in literally 1 minute. Copy and paste the below boilerplate code into an empty
index.html file, edit, and it's ready to be served from any static host.
<!-- Edit your site info here -->EXAMPLE SITE TITLE<!-- Edit your Markdown URL file location here --><!-- Edit your header title here -->EXAMPLE HEADER TITLE<!-- Edit your Github ribbon here () -->
<zero-md> works fantastically well for publishing quick project pages, info, news, homepages etc. It doesn't get easier than this.
- Install via NPM.
npm install --save zero-md
npm install --save @webcomponents/webcomponentsjs prismjs marked
- Use locally.
Develop and contribute
- Clone the repo.
git clone https://github.com/zerodevx/zero-md.git && cd zero-md
- Install dependencies.
npm install && bower install
- Start your favourite web server.
python -m SimpleHTTPServer 8000
- Run tests from your browser.
- Lint your code.
npm run lint
- And build it if you wish to.
npm run build
In order of priority,
<zero-md> first tries to retrieve the markdown string from its
<template><xmp>...</xmp></template> child; if none is defined,
<zero-md> next attempts to retrieve from the URL defined in the
src attribute via ajax.
Likewise, for CSS styles,
<zero-md> first tries to retrieve the styles defined in
<template><style>...</style></template>; if none,
<zero-md> next attempts to retrieve all the external stylesheets defined in the
css-urls attribute array.
By default, each
<zero-md> instance has the following styles applied to itself.
These are sensible defaults that should apply to most use-cases and also help normalise behavior across browsers - since the
contain CSS property is only implemented in Chrome. The beauty of web components is that you can easily override these defaults from outside the element to suit your needs.
<zero-md> loads the (Marked) JS library from CDN here; and the (Prism) JS library from here. These URL locations can be overridden by setting the
prism-url attributes respectively.
For styles, by default the
css-urls attribute contains a list of Github markdown stylesheet from here, and a light-themed highlight stylesheet from here. The defaults can be overridden by setting that attribute with an array of URLs in valid JSON format.
These defaults can be overridden globally by setting the
ZeroMd.config global. Note that setting the global config will apply to all instances of
<zero-md> in the document.
......<!-- So we don't have to repeat `css-urls='["a.css","b.css"]'` over and over again. -->......
When setting global config, ensure that the
window.ZeroMd.configobject is defined before importing the
The following configs are exposed (in camelCase):
|src||String||URL location to
|manual-render||Boolean||If set, disables auto-rendering of this instance. Call the
|marked-url||String||URL of the Marked JS library.|
|prism-url||String||URL of the Prism JS library.|
|css-urls||String||An array of stylesheet URLs to apply to this instance in valid JSON.|
|no-shadow||Boolean||If set, renders and stamps this instance into Light DOM instead. Please know what you're doing.|
css-urls, please ensure that the value is an Array in valid JSON format. For example:
<!-- Note the double-quotes ""! -->
|render()||none||Starts the markdown conversion and stamps into DOM.|
By default, each instance automatically calls the
render() method on start-up. To prevent this behavior, add the attribute
manual-render to your
<zero-md> element, and manually call this method to begin rendering. For example:
Note that if changes are made to
<zero-md> attributes or
<template> children dynamically, call the
render() method on that instance to force a re-render.
|zero-md-marked-ready||Fired after Marked JS library has loaded.|
|zero-md-prism-ready||Fired after Prism JS library has loaded.|
|zero-md-rendered||Fired after markdown converted, syntax highlighted, and contents stamped to DOM.|
Themes are just standard CSS stylesheets that can be applied to an instance of
<zero-md>. One of the coolest feature of web components is encapsulation - so these styles will not bleed out of its shadow DOM and affect the rest of the document.
Load your theme stylesheets by setting the
css-urls attribute. Check out the published attributes API.
<xmp> tag is deprecated!
In short, don't worry about it. Though the tag has been deprecated for 20 years, browser vendors (generally) try their hardest not to break the web. It is still implemented in modern browsers today. It's the only tag that suits such purpose, by allowing true pre-formatted content to be written as-is within the confines of the HTML document without endless escaping. Use it.
v1.x is completely different!
Yes it is. v1.x is absolutely breaking and not compatible with previous versions. Code is entirely re-written based on the new Custom Elements v1 specs with lots of ES6 goodness. It runs natively in modern browsers and is incredibly light and performant. This serves as a great showcase for how far we've come with Custom Elements, Web Components, its ideas, usage and patterns.
Anchor links support added!
Referencing this Github issue, a shout-out to @alexroseb for raising this. So the native browser handler for an
<a> link that points to an element
id doesn't pierce through shadow DOM - and I missed it. It's a feature, not a bug. Really!
v1.3.3 - 2020-01-07
- Fixed typo that broke C syntax highlighting - thanks @TheUnlocked! (ref: PR#21)
- Add usage note on webcomponentsjs polyfill regression in FFv60. (ref: #19)
- Update dependencies.
v1.3.2 - 2019-07-31
- Maintenance update of dev dependencies.
v1.3.1 - 2019-04-22
- Actually build for v1.3.1 (fixes #15).
- Automate the chore of version bumping else I keep missing things.
v1.3.0 - 2019-04-21
- Exposes the
ZeroMd.configglobal to set default values applying to all instances of
<zero-md>in the document. (Ref: PR#12) - thanks @bennypowers!
- Update default host CSS to help normalise behavior across browsers. Fixes #13 - thanks @bennypowers!
- Publish on NPM to support modern workflows per #11.
v1.2.2 - 2019-02-03
v1.2.1 - 2019-01-31
- Patch anchor links to support CMD+clicks.
v1.2.0 - 2018-11-26
- The community-agreed standard pattern of importing webcomponents is now via ES Modules. Consequently,
HTMLImportswill soon be deprecated from Chrome. Don't worry - your old code still works since
HTMLImportsfalls-back to polyfill. For better performance however, do update your existing code to load using ES Modules instead.
- Update all CDN links to jsDelivr and pin with semver.
- Per #6, use
getElementByIdinstead to prevent DOM exception error messages.
v1.1.0 - 2018-05-17
- Add anchor links feature.
- Update boilerplate to correct layout in Firefox.
- Update CDN links for
markedjsto v0.3.19 and
v1.0.0 - 2018-04-06
- Breaking changes, major release and incompatible with earlier v0.x versions.
- Completely re-written, updated to 2018 patterns, removes the need for Polymer and runs natively for a no-sugar, low-fat diet. Please read the docs and upgrade accordingly.
v0.2.0 - 2015-10-23
- Breaking changes and is incompatible with earlier versions.
style-moduleusage - instead mandate a child container element with
class="md-html"for simpler styling.
reload()method to dynamically reload content inside
- Completely rewrite rendering algorithm. Smaller, lighter and faster!
v0.1.1 - 2015-09-04
- Minor patches to default markdown theme.
v0.1.0 - 2015-09-01
- Initial commit.