ezmdpage

Easy self-rendering Markdown pages

📝 Write raw Markdown in .html files that gets auto-rendered everywhere
💡 Inspired by markdeep

Test page | ezmdpage & Alpine.js | ezmdpage & Vue.js

📂 Works with file:///document.html documents
📜 Failsafe text fallback when JavaScript is disabled
🎨 Styled using GitHub's Markdown CSS
🏝️ Works offline!

Installation

You can Ctrl+S the ezmdpage.min.js file to download it and load it locally (for offline use) or use an npm CDN like unpkg.com or jsDelivr to load it from the web:

<script src="ezmdpage.min.js"></script><plaintext>
<script src="https://unpkg.com/ezmdpage@2"></script><plaintext>
<script src="https://cdn.jsdelivr.net/npm/ezmdpage@2"></script><plaintext>

💡 You may also configure your formatter & editor

To get the best editing experience, you can configure Prettier or your other favorite formatter to use its Markdown parser/beautifier on .html files.

// package.json
{
  "prettier": {
    "overrides": [
      {
        "files": ["*.html"],
        "options": {
          "parser": "markdown"
        }
      }
    ]
  }
}

💡 You can also use a custom suffix like .ezmdpage.html or something if you have other non-ezmdpage HTML content in your workspace too.

⚛️ To get proper syntax highlighting in VS Code, you'll need to configure it to use its Markdown mode for .html files. You can do this by adding this to your .vscode/settings.json file:

{
  "files.associations": {
    "*.html": "markdown"
  }
}

⚠️ This project is intended to be used on a plain HTML page. It may not work with other non-Markdown content on the page.

Usage

After adding the magic <script> to your .md.html file, you can get started editing your document in ernest! You can use any relgular old text editor to compose your markdown; even Windows Notepad works great! ezmdpage even works with local file: URLs: you can just email or share a plain .html file with someone, and they will be able to open and view it.

<script src="https://unpkg.com/ezmdpage@2"></script><plaintext>

# Hello world!

This is my **Markdown document**! There's some <mark>HTML</mark> elements in
here <u>too</u> since Markdown supports _inline HTML_.

| Look at this cool 😎 GFM table! | Wow!                |
| ------------------------------- | ------------------- |
| We can even do math!            | $ax^2 + bx + c = 0$ |

```js
console.log("Code highlighting works too!");
```

> All other Markdown features work as expected.

<script>
  // You can even use <script> tags! There's NO SAFETY FILTER for HTML elements.
  const html = `<p>It's ${new Date().toLocaleTimeString()}!</p>`;
  document.body.append(document.createRange().createContextualFragment(html));
</script>

🤩 For more cool examples like using Alpine.js with ezmdpage, check out the GitHub Pages site which hosts the test/ folder demos!

Development

This project uses Vite to create a IIFE bundle of all the CSS and JavaScript that gets injected into the page. It's basically just Marked & HighlightJS. We use vite-plugin-css-injected-by-js to inline the CSS into the JavaScript bundle.

ℹ Note that we use the main field in package.json and not the new exports field. This is because unpkg.com doesn't support the new exports field. See mjackson/unpkg#265. unpkg.com is the most popular CDN for non-ESM npm packages, so it makes sense to bend over backwards to support it.