Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/lxsmnsyc/solid-marked
MDX Compiler for SolidJS
https://github.com/lxsmnsyc/solid-marked
markdown solid-js
Last synced: 13 days ago
JSON representation
MDX Compiler for SolidJS
- Host: GitHub
- URL: https://github.com/lxsmnsyc/solid-marked
- Owner: lxsmnsyc
- License: mit
- Created: 2022-01-08T03:03:46.000Z (almost 3 years ago)
- Default Branch: main
- Last Pushed: 2024-01-28T06:10:10.000Z (10 months ago)
- Last Synced: 2024-10-20T01:11:31.132Z (25 days ago)
- Topics: markdown, solid-js
- Language: TypeScript
- Homepage:
- Size: 826 KB
- Stars: 67
- Watchers: 3
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# solid-marked
> MDX/Markdown compiler for SolidJS
[](https://www.npmjs.com/package/solid-marked) [](https://github.com/airbnb/javascript)[](https://stackblitz.com/github/LXSMNSYC/solid-marked/tree/main/examples/vite-demo)
## Install
```bash
npm i solid-js solid-marked
```
```bash
yarn add solid-js solid-marked
```
```bash
pnpm add solid-js solid-marked
```
## Integrations
- [Unplugin](https://github.com/LXSMNSYC/solid-marked/tree/main/packages/unplugin)
- [Vite](https://github.com/LXSMNSYC/solid-marked/tree/main/packages/vite)
### Using the compiler
```js
import { compile } from 'solid-marked/compiler';
const { map, code } = await compile(
'my-file.md', // Name of the file
'# Hello World', // Markdown code
{
// Where to import the builtin components
// Default: solid-marked
mdxImportSource: 'mdx-provider',
// If solid-marked should use the Dynamic component
// or not.
// Possible values:
// - true: completely disables Dynamic component
// - false: enables Dynamic component
// - 'only-mdx': Dynamic component is only enabled for MDX
noDynamicComponents: 'only-mdx',
}
);
console.log(code);
```
### `useMDX` and `MDXProvider`
Components generated by `solid-marked` uses the fundamental components from an MDX provider, this is through the use of `useMDX` which is imported from the module. By default, `useMDX` comes from `solid-marked` and needs to be used in conjunction with ``
```js
import { MDXProvider } from 'solid-marked';
// ...
{props.children}
);
},
}}
>
```
Example custom module
```js
export function useMDX() {
return {
builtins: {
Link(props) {
return (
{props.children}
);
},
},
};
}
```
## Features
### ``
`` is the top-most component in a Markdown component. It serves as the container for the markdown content.
### Markdown
The following components (and their prop definitions) are derived from [`mdast`](https://github.com/syntax-tree/mdast#nodes)
#### ``
```md
Lorem ipsum dolor.
```
```js
import { useMDX as _useMDX$ } from 'solid-marked';
export default function Component(props) {
const _ctx$ = _useMDX$();
return (
Lorem ipsum dolor.
);
}
```
#### ``
> [!INFO]
> Presence of a `` allows the Markdown component to generate a ``.
```md
# Heading 1
## Heading 2
### Heading 3
#### Heading 4
##### Heading 5
###### Heading 6
```
```js
import { useMDX as _useMDX$ } from 'solid-marked';
export default function Component(props) {
const _ctx$ = _useMDX$();
return (
Heading 1
Heading 2
Heading 3
Heading 4
Heading 5
Heading 6
);
}
```
#### ``
```md
Lorem
***
Ipsum
***
Dolor
```
```js
import { useMDX as _useMDX$ } from 'solid-marked';
export default function Component(props) {
const _ctx$ = _useMDX$();
return (
Lorem
Ipsum
Dolor
);
}
```
#### `
`
```md
> Lorem ipsum dolor.
```
```js
import { useMDX as _useMDX$ } from 'solid-marked';
export default function Component(props) {
const _ctx$ = _useMDX$();
return (
Lorem ipsum dolor.
);
}
```
#### `` and ``
##### Ordered lists
```md
1. Lorem
2. Ipsum
3. Dolor
```
```js
import { useMDX as _useMDX$ } from 'solid-marked';
export default function Component(props) {
const _ctx$ = _useMDX$();
return (
Lorem
Ipsum
Dolor
);
}
```
##### Unordered lists
```md
- Lorem
- Ipsum
- Dolor
```
```js
import { useMDX as _useMDX$ } from 'solid-marked';
export default function Component(props) {
const _ctx$ = _useMDX$();
return (
Lorem
Ipsum
Dolor
);
}
```
#### ``
````md
```js highlight-line="2"
foo()
bar()
baz()
```
````
```js
import { useMDX as _useMDX$ } from 'solid-marked';
export default function Component(props) {
const _ctx$ = _useMDX$();
return (
{"foo()\nbar()\nbaz()"}
);
}
```
#### ``
```md
[Github]: https://github.com
```
```js
import { useMDX as _useMDX$ } from 'solid-marked';
export default function Component(props) {
const _ctx$ = _useMDX$();
return (
);
}
```
#### ``
```md
*alpha* _bravo_
```
```js
import { useMDX as _useMDX$ } from 'solid-marked';
export default function Component(props) {
const _ctx$ = _useMDX$();
return (
alpha bravo
);
}
```
#### ``
```md
**alpha** __bravo__
```
```js
import { useMDX as _useMDX$ } from 'solid-marked';
export default function Component(props) {
const _ctx$ = _useMDX$();
return (
alpha bravo
);
}
```
#### ``
```md
`foo()`
```
```js
import { useMDX as _useMDX$ } from 'solid-marked';
export default function Component(props) {
const _ctx$ = _useMDX$();
return (
{"foo()"}
);
}
```
#### ``
```md
a
b
```
```js
import { useMDX as _useMDX$ } from 'solid-marked';
export default function Component(props) {
const _ctx$ = _useMDX$();
return (
ab
);
}
```
#### ``
```md
[alpha](https://example.com "bravo")
```
```js
import { useMDX as _useMDX$ } from 'solid-marked';
export default function Component(props) {
const _ctx$ = _useMDX$();
return (
alpha
);
}
```
#### ``
```md
```
```js
import { useMDX as _useMDX$ } from 'solid-marked';
export default function Component(props) {
const _ctx$ = _useMDX$();
return (
);
}
```
#### ``
Must be have an associated ``.
```md
[This is an example][alpha]
[alpha]: bravo
```
```js
import { useMDX as _useMDX$ } from 'solid-marked';
export default function Component(props) {
const _ctx$ = _useMDX$();
return (
This is an example
);
}
```
#### ``
Must be have an associated ``.
```md
![This is an example][alpha]
[alpha]: bravo
```
```js
import { useMDX as _useMDX$ } from 'solid-marked';
export default function Component(props) {
const _ctx$ = _useMDX$();
return (
);
}
```
### Github-flavored Markdown
Based on [Github-flavored Markdown](https://github.github.com/gfm/)
#### ``
```md
[^alpha]: bravo and charlie.
```
```js
import { useMDX as _useMDX$ } from 'solid-marked';
export default function Component(props) {
const _ctx$ = _useMDX$();
return (
bravo and charlie.
);
}
```
#### ``
Must have an associated ``
```md
[^alpha]
[^alpha]: bravo and charlie.
```
```js
import { useMDX as _useMDX$ } from 'solid-marked';
export default function Component(props) {
const _ctx$ = _useMDX$();
return (
bravo and charlie.
);
}
```
#### ``, `` and ``
```md
| first | second | third |
| :---- | :----: | ----: |
| foo | bar | baz |
```
```js
import { useMDX as _useMDX$ } from 'solid-marked';
export default function Component(props) {
const _ctx$ = _useMDX$();
return (
first
second
third
foo
bar
baz
);
}
```
#### ``
```md
~~alpha~~
```
```js
import { useMDX as _useMDX$ } from 'solid-marked';
export default function Component(props) {
const _ctx$ = _useMDX$();
return (
alpha
);
}
```
### MDX
`solid-marked` supports [MDX](https://mdxjs.com/), with three compilation modes for the HTML/JSX expressions based on the `noDynamicImports` option for the compiler.
Let's take this example code:
```js
Hello World
```
- if set to `true`, the output JSX will not use SolidJS' `` component and instead outputs the target JSX component directly to the markup.
```js
import { useMDX as _useMDX$ } from 'solid-marked';
export default function Component(props) {
const _ctx$ = _useMDX$();
return (
<_ctx$.builtins.Root>
<_ctx$.builtins.Paragraph>
Hello World
);
}
```
- if set to `false`, the output will use ``. If an HTML or JSX expression is encountered, the element will be checked if it's not declared, in which it will use its counterpart component from `useMDX`, otherwise it will use the component/element directly.
```js
import { useMDX as _useMDX$ } from 'solid-marked';
export default function Component(props) {
const _ctx$ = _useMDX$();
return (
Hello World
);
}
```
- if set to `only-mdx`, `` is only used for builtin components while HTML/JSX expressions will be used directly.
```js
import { useMDX as _useMDX$ } from 'solid-marked';
export default function Component(props) {
const _ctx$ = _useMDX$();
return (
Hello World
);
}
```
### ``
`` is automatically generated when `` elements are detected. It is automatically exported and can also be used in the Markdown/MDX.
```md
# foo
## bar
### baz
# alpha
## bravo
### charlie
```
```js
import { useMDX as _useMDX$ } from 'solid-marked';
export function TableOfContents(props) {
const _ctx$ = _useMDX$();
return (
foo
bar
baz
alpha
bravo
charlie
);
}
export default function Component(props) {
const _ctx$ = _useMDX$();
return (
foo
bar
baz
alpha
bravo
charlie
);
}
```
### Frontmatter
`solid-marked` supports YAML and TOML frontmatter for Markdown/MDX. The data can be accessed through the `frontmatter` variable and also exported automatically. Frontmatter can only be used directly at the first line of the file.
#### YAML
```mdx
---
title: Hi, World!
---
# {frontmatter.title}
```
```js
export const frontmatter = ({title:"Hi, World!"});
import { useMDX as _useMDX$ } from 'solid-marked';
export function TableOfContents(props) {
const _ctx$ = _useMDX$();
return (
{frontmatter.title}
);
}
export default function Component(props) {
const _ctx$ = _useMDX$();
return (
{frontmatter.title}
);
}
```
#### TOML
```md
+++
title = "Hi, World!"
+++
# {frontmatter.title}
```
```js
export const frontmatter = Object.assign(Object.create(null),{title:"Hi, World!"});
import { useMDX as _useMDX$ } from 'solid-marked';
export function TableOfContents(props) {
const _ctx$ = _useMDX$();
return (
{frontmatter.title}
);
}
export default function Component(props) {
const _ctx$ = _useMDX$();
return (
{frontmatter.title}
);
}
```
## Typescript
```ts
///
```
## Component
The features above are compile-time Markdown rendering. For runtime rendering, `solid-marked` provides the `Markdown` component:
```js
import Markdown from 'solid-marked/component';
const content = (
{props.children}
);
},
Blockquote(props) {
return (
{props.children}
);
},
}}
>
{'> This is a blockquote.'}
);
```
> [!INFO]
> Markdown component only supports CommonMark and GFM. MDX and Frontmatter are considered "invalid".
## Sponsors
## License
MIT © [lxsmnsyc](https://github.com/lxsmnsyc)