@opral/markdown-wc
v0.5.0
Published
--- imports: - ./dist/walking-dinosaur.js - https://cdn.jsdelivr.net/npm/@opral/markdown-wc-doc-elements/dist/doc-video.js
Readme
imports:
- ./dist/walking-dinosaur.js
- https://cdn.jsdelivr.net/npm/@opral/markdown-wc-doc-elements/dist/doc-video.js
Opral Markdown WC
Enables writing documentation with web components in markdown.
---
imports:
- https://cdn.jsdelivr.net/npm/@opral/markdown-wc/dist/walking-dinosaur.js
---
# Opral Markdown WC
Enables writing documentation with web components in markdown.
<walking-dinosaur></walking-dinosaur>
<doc-video src="https://youtu.be/IMjJ1jvKsZU"></doc-video>
Why
- Enables writing documentation with components in markdown
- Interoperable with existing markdown parsers
- Doesn't depend on a framework like React MDX or Svelte MDsveX
- Doesn't introduce custom syntax like Markdoc
Comparison
| Feature | Markdown | @opral/markdown-wc | React MDX | Svelte MDsveX | Markdoc | |--------------------------------|----------|--------------------|-----------|---------------|---------| | Components in markdown | ❌ | ✅ | ✅ | ✅ | ✅ | | Framework agnostic | ✅ | ✅ | ❌ | ❌ | ✅ | | Portable | ✅ | ✅ | ❌ | ❌ | ❌ | | No custom syntax | ✅ | ✅ | ❌ | ❌ | ❌ |
Usage in browser
The <markdown-wc-embed> element can be used to embed markdown-wc in a webpage.
<script type="module" src="https://cdn.jsdelivr.net/npm/@opral/markdown-wc/dist/markdown-wc-embed.js"></script>
<body>
<markdown-wc-embed src="https://my-markdown-url.com/markdown.md"></markdown-wc-embed>
</body>Usage in another markdown file
The <markdown-wc-embed> element can be used to embed markdown-wc in markdown-wc.
---
imports:
- https://cdn.jsdelivr.net/npm/@opral/markdown-wc/dist/markdown-wc-embed.js
---
# Hello World
This is a markdown file that embeds another markdown file 🤯
<markdown-wc-embed src="https://cdn.jsdelivr.net/gh/opral/monorepo@latest/packages/markdown-wc/README.md"></markdown-wc-embed>Usage as libary
Enables SSR and more control over the rendering process.
import { parse } from '@opral/markdown-wc';
const markdown = `
# Hello World
// This is a web component
<doc-card>
<h1>Card Title</h1>
<p>Card content</p>
</doc-card>
`;
// Parse markdown
const parsed = parse(markdown);
// Register web components
for (const url of parsed.frontmatter.imports ?? []) {
// optionally sanitize the imported imported here
// by, for example, only trusting a specific domain
await import(url)
}
// render HTML
render(parsed.html);Limitations
- sanitzation of markdown as well as custom elements is not implemented atm
- SSR is DIY atm (use the
parsefunction and SSR the markdown with lit for example)
FAQ
Why not use React MDX or Svelte MDsveX?
React MDX and Svelte MDsveX are great tools but they introduce a dependency on a specific framework which is a no-go for portability.
Why not use a <script> tag to import the web components?
Markdown parsers don't remove the <script> tag from the output. This means that the script tag would be rendered in the final HTML. To increase interoperability, frontmatter is used to define imports.