https://github.com/cycraft/starkdown
🦾 Tiny <3kb Markdown parser written, almost as fast and smart as Tony Stark
https://github.com/cycraft/starkdown
Last synced: about 1 year ago
JSON representation
🦾 Tiny <3kb Markdown parser written, almost as fast and smart as Tony Stark
- Host: GitHub
- URL: https://github.com/cycraft/starkdown
- Owner: CyCraft
- License: other
- Created: 2022-09-09T12:28:44.000Z (almost 4 years ago)
- Default Branch: main
- Last Pushed: 2025-02-19T19:01:23.000Z (over 1 year ago)
- Last Synced: 2025-03-22T23:51:13.138Z (over 1 year ago)
- Language: TypeScript
- Homepage:
- Size: 1.92 MB
- Stars: 8
- Watchers: 1
- Forks: 0
- Open Issues: 7
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
# Starkdown 🦾
Starkdown is a Tiny <4kb Markdown parser written, almost as fast and smart as Tony Stark.
```sh
npm i starkdown
```
## Motivation
It is a continuation on a similar package called [Snarkdown](https://github.com/developit/snarkdown), which had stopped development at 1kb, but doesn't include basic support for paragraphs, tables, fenced divs, etc.
Starkdown stays around 1.6kb and adds these additional enhancements:
- [Paragraphs](#paragraphs)
- [Tables](#tables)
- [Fenced Divs](#fenced-divs)
- [Escaping snake_case words](#escaping-snake_case-words)
Package size wise, compared to other Markdown parsers, it's **8 ~ 18 times smaller!** See the [Package Size Comparison Chart](#package-size-comparison-chart)
## Usage
Starkdown is really easy to use, a single function which parses a string of Markdown and returns a String of HTML. Couldn't be simpler.
```js
import { starkdown } from 'starkdown'
const str = '_This_ is **easy** to `use`.'
const html = starkdown(str)
```
The `html` returned will look like:
```html
This is easy to use.
```
### Paragraphs
With most Markdown implementations, paragraphs are wrapped in `
` tags. With Starkdown, this is no different.
- All paragraphs and "inline" elements are wrapped in a `
` tags
(See [List of "inline" elements](https://developer.mozilla.org/en-US/docs/Web/HTML/Inline_elements#list_of_inline_elements) on MDN)
- Eg. a standalone image will still be wrapped in a `
` tag, because it's an inline element.
- All non-inline elements will not be wrapped in `
` tags
- Eg. a table will not be wrapped in a `
` tag.
```md
Check [github](https://github.com)
Img: 
```
converts to
```html
Check github
Img: 
```
But also, when _just_ using images and links:
```md
[github](https://github.com)
```
converts to
```html
```
In contrast, non-inline elements won't get a `
` tag:
```md
### Code
\`\`\`js
const a = 1
\`\`\`
```
converts to
```html
Code
const a = 1
```
### Links
Usual markdown for links works, i.e
```md
[github](https://github.com)
```
becomes
```html
```
But you can also add properties and classes to links using attribute lists like so:
```md
[github](https://github.com){:target="\_blank" .foo .bar #baz}
```
becomes
```html
```
### Tables
```md
| My | Table |
```
converts to
```html
My
Table
```
### Fenced Divs
```md
:::
this is some info
:::
```
converts to
```html
this is some info
```
**Or with a custom class.**
```md
::: info
this is some info
:::
```
converts to
```html
this is some info
```
### Escaping snake_case words
You need to escape your formatting with `\` in order to correctly convert sentences like these:
```md
snake*case is \_so-so*
```
will convert to:
```html
snakecase is so-so
```
Instead you should write
```md
snake*case is \_so-so*
```
which will convert to:
```html
snake_case is so-so
```
## Disable MarkDown Features
Starkdown comes built in with several "parsers" that each are responsible to convert a part of the markdown to HTML. You can filter out certain parsers to get different results.
The list of enabled default parsers can be inspected at [./src/defaultParsers.ts](./src/defaultParsers.ts).
```js
import { starkdown, defaultParsers } from 'starkdown'
const str = '_This_ is **easy** to `use`.'
// implicitly uses defaultParsers
const html = starkdown(str)
// this is a quick way to parse the string without the table tokeniser
// however, even though the parser is not used, it will not get tree-shaked
const htmlWithoutTables = starkdown(str, {
plugins: defaultParsers.filter((x) => x.name !== 'table'),
})
```
You can also add your own parsers this way. See [#Custom Parsers](#custom-parsers) below.
## Tree-Shaking
You can slim down the import & bundle size of Starkdown if you don't need all of the parsers provided in Starkdown by default.
The list of default parsers can be inspected at [./src/defaultParsers.ts](./src/defaultParsers.ts).
```js
import { createTokenizerParser } from 'starkdown'
import { escape, boldItalicsStrikethrough, codeblocks, inlineCode, quote } from 'starkdown/parsers'
const str = '_This_ is **easy** to `use`.'
// This will tree-shake out any parser that is not used
const mdDiscordPlugins = [escape, boldItalicsStrikethrough, codeblock, inlineCode, quote]
const mdDiscord = createTokenizerParser(mdDiscordPlugins)
const html = mdDiscord(str, { plugins: mdDiscordPlugins })
// Note: These are in order of priority so the order can matter, e.g `escape` must come first to escape markdown
```
You can also add your own parsers this way. See [#Custom Parsers](#custom-parsers) below.
## Custom Parsers
Parsers are defined as objects that match the following TypeScript definition.
```ts
import type { ParserDef } from 'starkdown'
// use this to create your custom parser
```
- Check the source code of [`ParserDef`](./src/types.ts) for more info.
- Examples can be found in the [parsers folder](./src/parsers/).
## Security
**Note on XSS:** Starkdown doesn't sanitize HTML. Please bring your own HTML sanitation for any place where user input will be converted into HTML.
## Package Size Comparison Chart
