Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/humanspeak/svelte-markdown
A markdown renderer for Svelte
https://github.com/humanspeak/svelte-markdown
markdown svelte sveltekit
Last synced: 4 days ago
JSON representation
A markdown renderer for Svelte
- Host: GitHub
- URL: https://github.com/humanspeak/svelte-markdown
- Owner: humanspeak
- License: mit
- Created: 2024-10-29T22:38:46.000Z (10 days ago)
- Default Branch: main
- Last Pushed: 2024-11-04T18:55:11.000Z (4 days ago)
- Last Synced: 2024-11-04T19:03:20.149Z (4 days ago)
- Topics: markdown, svelte, sveltekit
- Language: Svelte
- Homepage: https://sveltemarkdown.com
- Size: 1010 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
README
# Svelte Markdown
A markdown parser that renders into Svelte Components. Inspired by [ReactMarkdown](https://github.com/remarkjs/react-markdown).
## Installation
You can install it with
```console
npm i -S @humanspeak/svelte-markdown
```
## Usage
```svelte
import SvelteMarkdown from '@humanspeak/svelte-markdown'
const source = `
# This is a header
This is a paragraph.
* This is a list
* With two items
1. And a sublist
2. That is ordered
* With another
* Sublist inside
| And this is | A table |
|-------------|---------|
| With two | columns |`
```
This would render something like
```html
This is a header
This is a paragraph.
- This is a list
-
With two items
- And a sublist
-
That is ordered
- With another
- Sublist inside
And this is
A table
With two
columns
```
## Note
Just like with React Markdown, this package doesn't use `{@html ...}` unless you need to render HTML.
## Props
The SvelteMarkdown component accepts the following props:
- `source` - _string_ or _array_ The Markdown source to be parsed, or an array of tokens to be rendered directly.
- `renderers` - _object (optional)_ An object where the keys represent a node type and the value is a Svelte component. This object will be merged with the default renderers. For now you can check how the default renderers are written in the source code at `src/renderers`.
- `options` - _object (optional)_ An object containing [options for Marked](https://marked.js.org/using_advanced#options)
## Renderers
To create custom renderer for an element, you can create a Svelte component with the default props ([you can check them here](https://marked.js.org/using_pro#renderer)), for example:
_`ImageComponent.svelte`_
```svelte
export let href = ''
export let title = undefined
export let text = ''
```
So you can import the component and pass to the `renderers` props:
```svelte
import SvelteMarkdown from '@humanspeak/svelte-markdown'
import ImageComponent from './renderers/ImageComponent.svelte'
export let content
```
## Rendering From Tokens
For greater flexibility, an array of tokens may be given as `source`, in which case parsing is skipped and the tokens will be rendered directly. This alows you to generate and transform the tokens freely beforehand. Example:
```html
import SvelteMarkdown from '@humanspeak/svelte-markdown'
import { marked } from 'marked'
const tokens = marked.lexer('this is an **example**')
marked.walkTokens(tokens, (token) => {
if (token.type == 'strong') token.type = 'em'
token.raw = token.raw.toUpperCase()
})
```
This will render the following:
```html
THIS IS AN EXAMPLE
```
## Events
A `parsed` event will be fired when the final tokens have been calculated, allowing you to access the raw token array if needed for things like generating Table of Contents from headings.
```html
import SvelteMarkdown from '@humanspeak/svelte-markdown'
const source = `# This is a header`
const handleParsed = async (parsedTokens: Token[] | TokensList) => {
console.log('displaying tokens', parsedTokens)
}
```
## Available renderers
These would be the property names expected by the `renderers` option.
- `text` - Text rendered inside of other elements, such as paragraphs
- `paragraph` - Paragraph (`
`)
- `em` - Emphasis (``)
- `strong` - Strong/bold (``)
- `hr` - Horizontal rule / thematic break (`
`)
- `blockquote` - Block quote (``)
- `del` - Deleted/strike-through (``)
- `link` - Link (``)
- `image` - Image (``)
- `table` - Table (``)
- `tablehead` - Table head (``)
- `tablebody` - Table body (``)
- `tablerow` - Table row (``)
- `tablecell` - Table cell (``/``)
- `list` - List (``/`
`)
- `listitem` - List item (`
- `heading` - Heading (``-`
`)
- `codespan` - Inline code (``)
- `code` - Block of code (``)
- `html` - HTML node
### Optional List Renderers
For fine detail styling of lists, it can be useful to differentiate between ordered and un-ordered lists.
If either key is missing, the default `listitem` will be used. There are two
optional keys in the `renderers` option which can provide this:
- `orderedlistitem` - A list item appearing inside an ordered list
- `unorderedlistitem` A list item appearing inside an un-ordered list
As an example, if we have an `orderedlistitem`:
```html
li::marker {
color: blue;
}
```
Then numbers at the start of ordered list items would be colored blue. Bullets at the start of unordered list items
would remain the default text color.
### Inline Markdown
To use [inline markdown](https://marked.js.org/using_advanced#inline), you can assign the prop `isInline` to the component.
```html
```
## HTML rendering
While the most common flavours of markdown let you use HTML in markdown paragraphs, due to how Svelte handles plain HTML it is currently not possible to do this with this package. A paragraph must be either _all_ HTML or _all_ markdown.
```markdown
This is a **markdown** paragraph.
This is an HTML paragraph
```
Note that the HTML paragraph must be enclosed within `
` tags.
## Developing
Some tests have been added to the `tests` folder. You can clone this repo and create another svelte app and link it to this repo to try modifying it.
You can clone this repo and do the following:
```console
yarn
yarn link
yarn dev
```
This will watch all changes and make the project linkable. Now on the app you created you can link it with:
```console
yarn link @humanspeak/svelte-markdown
```
And then import it like in the example above.
As of now the only external dependency of this project is `marked`.
## Related
- [ReactMarkdown](https://github.com/remarkjs/react-markdown) - React library to render markdown using React components. Inspiration for this library.
- [Svelte](https://svelte.dev) - JavaScript front-end framework.
- [Marked](https://marked.js.org/) - Markdown parser
- [Original](https://github.com/pablo-abc/svelte-markdown) - Original component