solid-marked

KO | EN

gitlite — search

#python #hacktoberfest #ai #typescript #golang #rust #deep-learning #docker #java #nodejs #cli #kubernetes #ios #openai

(★ 70)

MDX Compiler for SolidJS

solid-marked Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# solid-marked

> MDX/Markdown compiler for SolidJS

[![NPM](https://img.shields.io/npm/v/solid-marked.svg)](https://www.npmjs.com/package/solid-marked) [![JavaScript Style Guide](https://badgen.net/badge/code%20style/airbnb/ff5a5f?icon=airbnb)](https://github.com/airbnb/javascript)[![Open in StackBlitz](https://img.shields.io/badge/Open%20in-StackBlitz-blue?style=flat-square&logo=stackblitz)](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 `<MDXProvider>`

```js
import { MDXProvider } from 'solid-marked';

// ...
<MDXProvider
  builtins={{
    Heading(props) {
      return (
        <Dynamic component={`h${props.depth}`}>
          {props.children}
        </Dynamic>
      );
    },
  }}
>
  <App />
</MDXProvider>
```

Example custom module

```js
export function useMDX() {
  return {
    builtins: {
      Link(props) {
        return (
          <a href={props.url} title={props.title}>
            {props.children}
          </a>
        );
      },
    },
  };
}
```

## Features

### `<Root>`

`<Root>` 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)

#### `<Paragraph>`

```md
Lorem ipsum dolor.
```

```js
import { useMDX as _useMDX$ } from 'solid-marked';

#### `<Heading>`

> [!NOTE]
> Presence of a `<Heading>` allows the Markdown component to generate a `<TableOfContents>`.

```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 (
    <Dynamic component={_ctx$.builtins.Root}>
      <Dynamic component={_ctx$.builtins.Heading} depth={1} id={"heading-1"}>Heading 1</Dynamic>
      <Dynamic component={_ctx$.builtins.Heading} depth={2} id={"heading-2"}>Heading 2</Dynamic>
      <Dynamic component={_ctx$.builtins.Heading} depth={3} id={"heading-3"}>Heading 3</Dynamic>
      <Dynamic component={_ctx$.builtins.Heading} depth={4} id={"heading-4"}>Heading 4</Dynamic>
      <Dynamic component={_ctx$.builtins.Heading} depth={5} id={"heading-5"}>Heading 5</Dynamic>
      <Dynamic component={_ctx$.builtins.Heading} depth={6} id={"heading-6"}>Heading 6</Dynamic>
    </Dynamic>   
  );
}
```

#### `<ThematicBreak>`

```md
Lorem
***
Ipsum
***
Dolor
```

```js
import { useMDX as _useMDX$ } from 'solid-marked';

export default function Component(props) {
  const _ctx$ = _useMDX$();
  return (
    <Dynamic component={_ctx$.builtins.Root}>
      <Dynamic component={_ctx$.builtins.Paragraph}>Lorem</Dynamic>
      <Dynamic component={_ctx$.builtins.ThematicBreak} />
      <Dynamic component={_ctx$.builtins.Paragraph}>Ipsum</Dynamic>
      <Dynamic component={_ctx$.builtins.ThematicBreak} />
      <Dynamic component={_ctx$.builtins.Paragraph}>Dolor</Dynamic>
    </Dynamic>
  );
}
```

#### `<Blockquote>`

```md
> Lorem ipsum dolor.
```

```js
import { useMDX as _useMDX$ } from 'solid-marked';

export default function Component(props) {
  const _ctx$ = _useMDX$();
  return (
    <Dynamic component={_ctx$.builtins.Root}>
      <Dynamic component={_ctx$.builtins.Blockquote}>
        <Dynamic component={_ctx$.builtins.Paragraph}>
          Lorem ipsum dolor.
        </Dynamic>
      </Dynamic>
    </Dynamic>
  );
}
```

#### `<List>` and `<ListItem>`

##### 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 (
    <Dynamic component={_ctx$.builtins.Root}>
      <Dynamic component={_ctx$.builtins.List} ordered={true} spread={false} start={1}>
        <Dynamic component={_ctx$.builtins.ListItem} spread={false}>
          <Dynamic component={_ctx$.builtins.Paragraph}>Lorem</Dynamic>
        </Dynamic>
        <Dynamic component={_ctx$.builtins.ListItem} spread={false}>
          <Dynamic component={_ctx$.builtins.Paragraph}>Ipsum</Dynamic>
        </Dynamic>
        <Dynamic component={_ctx$.builtins.ListItem} spread={false}>
          <Dynamic component={_ctx$.builtins.Paragraph}>Dolor</Dynamic>
        </Dynamic>
      </Dynamic>
    </Dynamic>
  );
}
```

##### Unordered lists

```md
- Lorem
- Ipsum
- Dolor
```

```js
import { useMDX as _useMDX$ } from 'solid-marked';

export default function Component(props) {
  const _ctx$ = _useMDX$();
  return (
    <Dynamic component={_ctx$.builtins.Root}>
      <Dynamic component={_ctx$.builtins.List} ordered={false} spread={false}>
        <Dynamic component={_ctx$.builtins.ListItem} spread={false}>
          <Dynamic component={_ctx$.builtins.Paragraph}>Lorem</Dynamic>
        </Dynamic>
        <Dynamic component={_ctx$.builtins.ListItem} spread={false}>
          <Dynamic component={_ctx$.builtins.Paragraph}>Ipsum</Dynamic>
        </Dynamic>
        <Dynamic component={_ctx$.builtins.ListItem} spread={false}>
          <Dynamic component={_ctx$.builtins.Paragraph}>Dolor</Dynamic>
        </Dynamic>
      </Dynamic>
    </Dynamic>
  );
}
```

#### `<Code>`

````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 (
    <Dynamic component={_ctx$.builtins.Root}>
      <Dynamic component={_ctx$.builtins.Code} lang={"js"} meta={"highlight-line=\"2\""}>
        {"foo()\nbar()\nbaz()"}
      </Dynamic>
    </Dynamic>
  );
}
```

#### `<Definition>`

```md
[Github]: https://github.com
```

```js
import { useMDX as _useMDX$ } from 'solid-marked';

export default function Component(props) {
  const _ctx$ = _useMDX$();
  return (
    <Dynamic component={_ctx$.builtins.Root}>
      <Dynamic component={_ctx$.builtins.Definition}
        url={"https://github.com"}
        identifier={"github"}
        label={"Github"}
      />
    </Dynamic>
  );
}
```

#### `<Emphasis>`

```md
*alpha* _bravo_
```

```js
import { useMDX as _useMDX$ } from 'solid-marked';

export default function Component(props) {
  const _ctx$ = _useMDX$();
  return (
    <Dynamic component={_ctx$.builtins.Root}>
      <Dynamic component={_ctx$.builtins.Paragraph}>
        <Dynamic component={_ctx$.builtins.Emphasis}>alpha</Dynamic> <Dynamic component={_ctx$.builtins.Emphasis}>bravo</Dynamic>
      </Dynamic>
    </Dynamic>
  );
}
```

#### `<Strong>`

```md
**alpha** __bravo__
```

```js
import { useMDX as _useMDX$ } from 'solid-marked';

export default function Component(props) {
  const _ctx$ = _useMDX$();
  return (
    <Dynamic component={_ctx$.builtins.Root}>
      <Dynamic component={_ctx$.builtins.Paragraph}>
        <Dynamic component={_ctx$.builtins.Strong}>alpha</Dynamic> <Dynamic component={_ctx$.builtins.Strong}>bravo</Dynamic>
      </Dynamic>
    </Dynamic>
  );
}
```

#### `<InlineCode>`

```md
`foo()`
```

```js
import { useMDX as _useMDX$ } from 'solid-marked';

#### `<Break>`

```md
a  
b
```

```js
import { useMDX as _useMDX$ } from 'solid-marked';

#### `<Link>`

```md
[alpha](https://example.com "bravo")
```

```js
import { useMDX as _useMDX$ } from 'solid-marked';

#### `<Image>`

```md
![alpha](https://example.com/favicon.ico "bravo")
```

```js
import { useMDX as _useMDX$ } from 'solid-marked';

export default function Component(props) {
  const _ctx$ = _useMDX$();
  return (
    <Dynamic component={_ctx$.builtins.Root}>
      <Dynamic component={_ctx$.builtins.Paragraph}>
        <Dynamic
          component={_ctx$.builtins.Image}
          url={"https://example.com/favicon.ico"}
          title={"bravo"}
          alt={"alpha"}
        />
      </Dynamic>
    </Dynamic>
  );
}
```

#### `<LinkReference>`

Must be have an associated `<Definition>`.

```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 (
    <Dynamic component={_ctx$.builtins.Root}>
      <Dynamic component={_ctx$.builtins.Paragraph}>
        <Dynamic 
          component={_ctx$.builtins.LinkReference}
          identifier={"alpha"}
          label={"alpha"}
          referenceType={"full"}
        >
          This is an example
        </Dynamic>
      </Dynamic>
      <Dynamic
        component={_ctx$.builtins.Definition}
        url={"bravo"}
        identifier={"alpha"}
        label={"alpha"}
      />
    </Dynamic>
  );
}
```

#### `<ImageReference>`

Must be have an associated `<Definition>`.

```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 (
    <Dynamic component={_ctx$.builtins.Root}>
      <Dynamic component={_ctx$.builtins.Paragraph}>
        <Dynamic
          component={_ctx$.builtins.ImageReference}
          identifier={"alpha"}
          label={"alpha"}
          referenceType={"full"} 
          alt={"This is an example"}
        />
      </Dynamic>
      <Dynamic
        component={_ctx$.builtins.Definition}
        url={"bravo"}
        identifier={"alpha"}
        label={"alpha"}
      />
    </Dynamic>
  );
}
```

### Github-flavored Markdown

Based on [Github-flavored Markdown](https://github.github.com/gfm/)

#### `<FootnoteDefinition>`

```md
[^alpha]: bravo and charlie.
```

```js
import { useMDX as _useMDX$ } from 'solid-marked';

export default function Component(props) {
  const _ctx$ = _useMDX$();
  return (
    <Dynamic component={_ctx$.builtins.Root}>
      <Dynamic component={_ctx$.builtins.FootnoteDefinition} identifier={"alpha"} label={"alpha"}>
        <Dynamic component={_ctx$.builtins.Paragraph}>bravo and charlie.</Dynamic>
      </Dynamic>
    </Dynamic>
  );
}
```

#### `<FootnoteReference>`

Must have an associated `<FootnoteDefinition>`

```md
[^alpha]

[^alpha]: bravo and charlie.
```

```js
import { useMDX as _useMDX$ } from 'solid-marked';

export default function Component(props) {
  const _ctx$ = _useMDX$();
  return (
    <Dynamic component={_ctx$.builtins.Root}>
      <Dynamic component={_ctx$.builtins.Paragraph}>
        <Dynamic
          component={_ctx$.builtins.FootnoteReference}
          identifier={"alpha"}
          label={"alpha"}
        />
      </Dynamic>
      <Dynamic component={_ctx$.builtins.FootnoteDefinition} identifier={"alpha"} label={"alpha"}>
        <Dynamic component={_ctx$.builtins.Paragraph}>bravo and charlie.</Dynamic>
      </Dynamic>
    </Dynamic>
  );
}
```

#### `<Table>`, `<TableRow>` and `<TableCell>`

```md
| first | second | third |
| :---- | :----: | ----: |
| foo   |  bar   |   baz |
```

```js
import { useMDX as _useMDX$ } from 'solid-marked';

export default function Component(props) {
  const _ctx$ = _useMDX$();
  return (
    <Dynamic component={_ctx$.builtins.Root}>
      <Dynamic component={_ctx$.builtins.Table} align={["left","center","right"]}>
        <Dynamic component={_ctx$.builtins.TableRow} isHead={true}>
          <Dynamic component={_ctx$.builtins.TableCell}>first</Dynamic>
          <Dynamic component={_ctx$.builtins.TableCell}>second</Dynamic>
          <Dynamic component={_ctx$.builtins.TableCell}>third</Dynamic>
        </Dynamic>
        <Dynamic component={_ctx$.builtins.TableRow}>
          <Dynamic component={_ctx$.builtins.TableCell}>foo</Dynamic>
          <Dynamic component={_ctx$.builtins.TableCell}>bar</Dynamic>
          <Dynamic component={_ctx$.builtins.TableCell}>baz</Dynamic>
        </Dynamic>
      </Dynamic>
    </Dynamic>
  );
}
```

#### `<Delete>`

```md
~~alpha~~
```

```js
import { useMDX as _useMDX$ } from 'solid-marked';

### 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
<Example>Hello World</Example>
```

- if set to `true`, the output JSX will not use SolidJS' `<Dynamic>` 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>
          <Example>Hello World</Example>
        </_ctx$.builtins.Paragraph>
      </_ctx$.builtins.Root>
    );
  }
  ```
- if set to `false`, the output will use `<Dynamic>`. 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 (
      <Dynamic component={_ctx$.builtins.Root}>
        <Dynamic component={_ctx$.builtins.Paragraph}>
          <Dynamic component={typeof Example === 'undefined' ? _ctx$.components.Example : Example}>
            Hello World
          </Dynamic>
        </Dynamic>
      </Dynamic>
    );
  }
  ```
- if set to `only-mdx`, `<Dynamic>` is only used for builtin components while HTML/JSX expressions will be used directly.
  ```js
  import { useMDX as _useMDX$ } from 'solid-marked';

### `<TableOfContents>`

`<TableOfContents>` is automatically generated when `<Heading>` 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 (
    <Dynamic component={_ctx$.builtins.List} ordered={false} spread={true}>
      <Dynamic component={_ctx$.builtins.ListItem} spread={true}>
        <Dynamic component={_ctx$.builtins.Paragraph}>
          <Dynamic component={_ctx$.builtins.Link} url={"#foo"}>foo</Dynamic>
        </Dynamic>
        <Dynamic component={_ctx$.builtins.List} ordered={false} spread={true}>
          <Dynamic component={_ctx$.builtins.ListItem} spread={true}>
            <Dynamic component={_ctx$.builtins.Paragraph}>
              <Dynamic component={_ctx$.builtins.Link} url={"#bar"}>bar</Dynamic>
            </Dynamic>
            <Dynamic component={_ctx$.builtins.List} ordered={false} spread={false}>
              <Dynamic component={_ctx$.builtins.ListItem} spread={false}>
                <Dynamic component={_ctx$.builtins.Paragraph}>
                  <Dynamic component={_ctx$.builtins.Link} url={"#baz"}>baz</Dynamic>
                </Dynamic>
              </Dynamic>
            </Dynamic>
          </Dynamic>
        </Dynamic>
      </Dynamic>
      <Dynamic component={_ctx$.builtins.ListItem} spread={true}>
        <Dynamic component={_ctx$.builtins.Paragraph}>
          <Dynamic component={_ctx$.builtins.Link} url={"#alpha"}>alpha</Dynamic>
        </Dynamic>
        <Dynamic component={_ctx$.builtins.List} ordered={false} spread={true}>
          <Dynamic component={_ctx$.builtins.ListItem} spread={true}>
            <Dynamic component={_ctx$.builtins.Paragraph}>
              <Dynamic component={_ctx$.builtins.Link} url={"#bravo"}>bravo</Dynamic>
            </Dynamic>
            <Dynamic component={_ctx$.builtins.List} ordered={false} spread={false}>
              <Dynamic component={_ctx$.builtins.ListItem} spread={false}>
                <Dynamic component={_ctx$.builtins.Paragraph}>
                  <Dynamic component={_ctx$.builtins.Link} url={"#charlie"}>charlie</Dynamic>
                </Dynamic>
              </Dynamic>
            </Dynamic>
          </Dynamic>
        </Dynamic>
      </Dynamic>
    </Dynamic>       
  );
}
export default function Component(props) {
  const _ctx$ = _useMDX$();
  return (
    <Dynamic component={_ctx$.builtins.Root}>
      <Dynamic component={_ctx$.builtins.Heading} depth={1} id={"foo"}>foo</Dynamic>
      <Dynamic component={_ctx$.builtins.Heading} depth={2} id={"bar"}>bar</Dynamic>
      <Dynamic component={_ctx$.builtins.Heading} depth={3} id={"baz"}>baz</Dynamic>
      <Dynamic component={_ctx$.builtins.Heading} depth={1} id={"alpha"}>alpha</Dynamic>
      <Dynamic component={_ctx$.builtins.Heading} depth={2} id={"bravo"}>bravo</Dynamic>
      <Dynamic component={_ctx$.builtins.Heading} depth={3} id={"charlie"}>charlie</Dynamic>
    </Dynamic>
  );
}
```

### 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 (
    <Dynamic component={_ctx$.builtins.List} ordered={false} spread={false}>
      <Dynamic component={_ctx$.builtins.ListItem} spread={false}>
        <Dynamic component={_ctx$.builtins.Paragraph}>
          <Dynamic component={_ctx$.builtins.Link} url={"#frontmattertitle"}> 
            {frontmatter.title}
          </Dynamic>
        </Dynamic>
      </Dynamic>
    </Dynamic>
  );
}
export default function Component(props) {
  const _ctx$ = _useMDX$();
  return (
    <Dynamic component={_ctx$.builtins.Root}>
      <Dynamic component={_ctx$.builtins.Heading} depth={1} id={"frontmattertitle"}>
        {frontmatter.title}
      </Dynamic>
    </Dynamic>
  );
}
```

#### 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 (
    <Dynamic component={_ctx$.builtins.List} ordered={false} spread={false}>
      <Dynamic component={_ctx$.builtins.ListItem} spread={false}>
        <Dynamic component={_ctx$.builtins.Paragraph}>
          <Dynamic component={_ctx$.builtins.Link} url={"#frontmattertitle"}>
            {frontmatter.title}
          </Dynamic>
        </Dynamic>
      </Dynamic>
    </Dynamic>
  );
}
export default function Component(props) {
  const _ctx$ = _useMDX$();
  return (
    <Dynamic component={_ctx$.builtins.Root}>
      <Dynamic component={_ctx$.builtins.Heading} depth={1} id={"frontmattertitle"}>
        {frontmatter.title}
      </Dynamic>
    </Dynamic>
  );
}
```

## Typescript

```ts
/// <reference types="solid-marked/env">
```

## 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';

> [!NOTE]
> Markdown component only supports CommonMark and GFM. MDX and Frontmatter are considered "invalid".

## Sponsors

![Sponsors](https://github.com/lxsmnsyc/sponsors/blob/main/sponsors.svg?raw=true)

## License

solid-marked

solid-marked Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

solid-marked

solid-marked Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README