![GitHub package.json version](https://img.shields.io/github/package-json/v/zerodevx/zero-md) ![jsDelivr hits (GitHub)](https://img.shields.io/jsdelivr/gh/hm/zerodevx/zero-md) # <zero-md> > Ridiculously simple zero-config markdown displayer A native markdown-to-html web component based on [Custom Elements V1 specs](https://www.w3.org/TR/custom-elements/) to load and display an external MD file. Under the hood, it uses [Marked](https://github.com/markedjs/marked) for super-fast markdown transformation, and [Prism](https://github.com/PrismJS/prism) for feature-packed syntax highlighting - automagically rendering into its own self-contained shadow DOM container, while encapsulating implementation details into one embarassingly easy-to-use package. **NOTE: This is the V2 branch. If you're looking for the older version, see the [V1 branch](https://github.com/zerodevx/zero-md/tree/v1).** Featuring: - [x] Automated hash-link scrolls - [x] Built-in FOUC prevention - [x] Automatically rewrite URLs relative to `src` - [x] Automatically re-render when `src` changes - [x] Automatically re-render when inline markdown or style template changes - [x] Support for >200 code languages with detection for unhinted code blocks - [x] Easy styling mechanism - [x] Highly extensible Documentation: https://zerodevx.github.io/zero-md/ **NOTE: Your markdown file(s) needs to be hosted! Browsers don't generally allow javascript to access files on the local hard drive because of security concerns. Standard [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) rules apply.** ## Installation ### Load via CDN (recommended) `zero-md` is designed to be zero-config with good defaults. For most use-cases, just importing the script from CDN and consuming the component directly should suffice. ```html ... ... ... ... ``` Latest stable: `https://cdn.jsdelivr.net/gh/zerodevx/zero-md@2/dist/zero-md.min.js` Latest beta: `https://cdn.jsdelivr.net/npm/zero-md@next/dist/zero-md.min.js` ### Install in web projects Install package with `npm` or `yarn`. Note that you'll need [Node.js](https://nodejs.org/) installed. ``` $ npm install --save zero-md ``` Import the class, register the element, and use anywhere. ```js // Import the element definition import ZeroMd from 'zero-md' // Register the custom element customElements.define('zero-md', ZeroMd) // Render anywhere app.render(``, target) ``` Or load the distribution directly in HTML. ```html ... ``` ## Basic Usage ### Display an external markdown file ```html ``` At its most basic, `` loads and displays an external MD file with **default stylesheets** - a Github-themed stylesheet paired with a light-themed one for code blocks, just like what you see in these docs. So internally, the above code block is semantically equivalent to the one below: ```html ``` ### Using your own styles To override the default theme, supply your own style template. ```html ``` ### Or your own stylesheets ```html ``` ### Or both ```html ``` ### Write markdown inline You can pass in your markdown inline too. ```html ``` By default, `` first tries to render `src`. If `src` is falsy (undefined, file not found, empty file etc), it **falls-back** to the contents inside the ` ``` ## API Advanced usage: https://zerodevx.github.io/zero-md/advanced-usage/ Attributes and helpers: https://zerodevx.github.io/zero-md/attributes-and-helpers/ Configuration: https://zerodevx.github.io/zero-md/configuration/ ## Migrating from V1 to V2 1. Support for `` tag is removed; use `<script type="text/markdown">` instead.  ```html  <zero-md> <template> <xmp> # `This` is my [markdown](example.md)

``` 2. Markdown source behaviour has changed. Think of ` ``` 3. The `css-urls` attribute is deprecated. Use `` instead. ```html

``` 4. The attributes `marked-url` and `prism-url` are deprecated. To load `marked` or `prism` from another location, simply load their scripts _before_ importing `zero-md`. ```html ... ``` 5. The global config object has been renamed from `ZeroMd.config` to `ZeroMdConfig`. ```html ``` 6. The convenience events `zero-md-marked-ready` and `zero-md-prism-ready` are removed and **will no longer fire**. Instead, the `zero-md-ready` event guarantees that everything is ready, and that render can begin. ## Contributing ### Noticed a bug? Have a feature request? Open a new [issue](https://github.com/zerodevx/zero-md/issues) in the Github repo, or raise a [PR](https://github.com/zerodevx/zero-md/pulls)! I'd be stoked to accept any contributions! ### Development Standard Github [contribution workflow](https://github.com/firstcontributions/first-contributions) applies. #### Run the dev server ``` $ npm run dev ``` Point your browser to `http://localhost:8000` and you should see the test suite running. #### Testing Tests are browser-based and run on [Mocha](https://mochajs.org/) with [Chai](https://www.chaijs.com/) asserts. If you're adding a new feature or bugfixing, please add the corresponding regression test into `test/index.spec.js` accordingly. #### Format and lint ``` $ npm run format $ npm run lint ``` Formatting and linting by [prettier](https://github.com/prettier/prettier) and [eslint](https://github.com/eslint/eslint) respectively. #### Making changes to docs Documentation is in the `/docs` folder in the form of `readme.md` files, and published on [Github Pages](https://pages.github.com/). This setup is based on [`zero-md-docs`](https://github.com/zerodevx/zero-md-docs). To make changes to docs, simply raise a PR on any `readme.md` files should suffice. ## Changelog Check out the [releases](https://github.com/zerodevx/zero-md/releases) page. ## License ISC ## Acknowledgement A big thank you to the following contributors and sponsors! :pray: ### Contributors [](https://github.com/alifeee) [](https://github.com/EmilePerron) [](https://github.com/bennypowers) [](https://github.com/TheUnlocked) [](https://github.com/ernsheong) ### Sponsors [](https://github.com/RootofalleviI)[](https://github.com/alifeee)