Skip to content

Latest commit

 

History

History
169 lines (122 loc) · 5.35 KB

README.md

File metadata and controls

169 lines (122 loc) · 5.35 KB
Raw

version license stars downloads old

<zero-md>

Ridiculously simple zero-config markdown displayer

A vanilla markdown-to-html web component based on Custom Elements V1 specs to load and display an external MD file. Under the hood, it uses marked for super-fast markdown transformation, and highlight.js for lightning-quick syntax highlighting - automagically rendering into its own self-contained shadow DOM container, while encapsulating implementation details into one embarrassingly easy-to-use package.

Featuring:

  • Math rendering via KaTeX
  • Mermaid diagrams
  • Syntax highlighting via highlight.js
  • Language detection for un-hinted code blocks
  • Hash-link scroll handling
  • FOUC prevention
  • Auto re-render on input changes
  • Light and dark themes
  • Spec-compliant extensibility

Important

Your markdown file(s) must be hosted! Browsers restrict local file access in javascript because security. Standard CORS rules apply.

Read the docs: https://zerodevx.github.io/zero-md/

Note

This is the V3 branch. If you're looking for the older version, see the V2 branch. If you're upgrading from V2, read the migration guide.

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.

<head>
  ...
  <!-- Import element definition and auto-register -->
  <script type="module" src="https://cdn.jsdelivr.net/npm/zero-md@3?register"></script>
</head>
<body>
  ...
  <!-- Profit! -->
  <zero-md src="example.md"></zero-md>
</body>

Use in web projects

Install the package.

$ npm i zero-md

Import the class, register the element, and use anywhere.

// Import the element definition
import ZeroMd from 'zero-md'

// Register the custom element
customElements.define('zero-md', ZeroMd)

// Render anywhere
app.render(`<zero-md src=${src}></zero-md>`, target)

Basic usage

<!-- Simply set the `src` attribute and win -->
<zero-md src="https://example.com/markdown.md"></zero-md>

<!-- Or write markdown inline -->
<zero-md>
  <!-- Write your markdown inside a `<script type="text/markdown">` tag -->
  <script type="text/markdown">
# **This** is my [markdown](https://example.com)
  </script>
</zero-md>

<!-- Or update the style -->
<zero-md src="https://example.com/markdown.md">
  <!-- Wrap `style` tags inside `template` -->
  <template data-append>
    <style>
      p { color: red; }
    </style>
  </template>
</zero-md>

Read the docs: https://zerodevx.github.io/zero-md/

Contributing

Noticed a bug? Have a feature request?

Open a new issue in the Github repo, or raise a PR - I'd be stoked to hear from you!

Development

Standard Github contribution workflow applies.

Run the dev server

$ npm run dev

We use Vite for tooling. Point your browser to http://localhost:5173 and you should see the test page. Library code in src/lib/.

Testing

$ npm test

Tests via Playwright. Test specs in src/index.spec.js. Be sure tests pass in your PR.

Updating docs

Documentation is in the docs/ folder. Submit PRs onto the .md files directly and changes will be automatically published upon merge. Documentation website uses zero-md-docs to instantly publish markdown from the Github docs/ folder.

Changelog

Check out the releases page.

License

ISC

Acknowledgement

A big thank you to the following contributors and sponsors! 🙏

Contributors

Sponsors