Skip to content

πŸ“ Write raw Markdown in .html files that gets auto-rendered on page load

License

Notifications You must be signed in to change notification settings

jcbhmr/ezmdpage

Folders and files

NameName
Last commit message
Last commit date

Latest commit

Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation

Easy self-rendering Markdown pages

πŸ“ Write raw Markdown in .html files that gets auto-rendered everywhere
πŸ’‘ Inspired by markdeep

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

Installation

unpkg.com jsDelivr

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 .md.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

Markdown Browser

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

JavaScript CSS Vite

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.