Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/readmeio/markdown
ReadMe's flavored Markdown parser and React-based rendering engine.
https://github.com/readmeio/markdown
gfm markdown mdx rdmd react
Last synced: 4 days ago
JSON representation
ReadMe's flavored Markdown parser and React-based rendering engine.
- Host: GitHub
- URL: https://github.com/readmeio/markdown
- Owner: readmeio
- License: isc
- Created: 2020-07-28T18:07:41.000Z (over 4 years ago)
- Default Branch: next
- Last Pushed: 2025-01-23T23:21:52.000Z (15 days ago)
- Last Synced: 2025-01-24T00:13:51.946Z (15 days ago)
- Topics: gfm, markdown, mdx, rdmd, react
- Language: TypeScript
- Homepage: https://rdmd.readme.io
- Size: 111 MB
- Stars: 34
- Watchers: 18
- Forks: 9
- Open Issues: 16
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# 
`@readme/markdown`
ReadMe's MDX rendering engine and custom component collection.
*(Use ReadMe? [Learn more about our upcoming move to MDX](https://docs.readme.com/rdmd/page/mdx-engine)!)*
## Getting Started
To use the engine, install it from NPM:
```
npm install --save @readme/markdown
```
Then [`compile`](#compile) and [`run`](#run) your MDX:
```jsx
import RMDX from '@readme/markdown';
export default ({ body }) => (
{RMDX.run(RMDX.compile(body))}
);
```
## API
### `compile`
Compiles MDX to JS. Essentially a wrapper around [`mdx.compile`](https://mdxjs.com/packages/mdx/#compilefile-options). Used before calling [`run`](#run); it has been left as a seperate method for potential caching opportunities.
#### Parameters
- **`string`** (`string`)—an MDX document
- **`opts`** ([`CompileOpts`](#compileopts), optional)—a configuration object
#### Returns
A string of compiled Javascript module code.
### `run`
> [!CAUTION]
> This is essentially a wrapper around [`mdx.run`](https://mdxjs.com/packages/mdx/#runcode-options) and **it will `eval` the compiled MDX**. Make sure you only call `run` on safe syntax from a trusted author!
>
> #### Parameters
> - **`string`** (`string`)—a compiled mdx document
> - **`opts`** (`RunOpts`, optional)—configuration
>
> #### Returns
> An [`RMDXModule`](#rmdxmodule) of renderable components.
### `mdx`
Compiles an AST to a string of MDX syntax.
#### Parameters
- **`tree`** (`object`)—an abstract syntax tree
- **`opts`** ([`Options`](https://github.com/remarkjs/remark/tree/main/packages/remark-stringify#options "`remark-stringify` Options type"))—`remark-stringify` configuration.
#### Returns
An MDX string.
### Other Methods
- **`mdast`**: parse MDX syntax to MDAST.
- **`hast`**: parse MDX syntax to HAST.
- **`plain`**: parse MDX to a plaintext string with all Markdown syntax removed. (This *does not* `eval` the doc.)
- **`tags`**: get a list of tag names from the doc. (This *does not* `eval` the doc.)
- **`utils`**: additional defaults, helper methods, components, and so on.
## Types
### `CompileOpts`
Extends [`CompileOptions`](https://mdxjs.com/packages/mdx/#compileoptions)
##### Additional Properties
- **`lazyImages`** (`boolean`, optional)—load images lazily
- **`safeMode`** (`boolean`, optional)—extract script tags from `HTMLBlock`s
- **`components`** (`Record`, optional)—an object of tag names to mdx.
- **`copyButtons`** (`Boolean`, optional) — add a copy button to code blocks
### `RunOpts`
Extends [`RunOptions`](https://mdxjs.com/packages/mdx/#runoptions)
##### Additional Properties
- **`components`** (`Record`, optional)—a set of custom MDX components
- **`imports`** (`Record`, optional)—an set of modules to import globally
- **`terms`** (`GlossaryTerm[]`, optional)
- **`variables`** (`Variables`, optional)—an object containing [user variables](https://github.com/readmeio/variable)
### `RMDXModule`
##### Properties
- **`default`** (`() => MDXContent`)—the MDX douments default export
- **`toc`** (`HastHeading[]`)—a list of headings in the document
- **`Toc`** (`() => MDCContent`)—a table of contents component
## Local Development and Testing
To make changes to the RDMD engine locally, run the local development server. Clone the repo, `cd` in to it, `npm install`, and `npm run start`!
If you make changes to the docs or how the markdown is rendered, you may need to update the visual regression snapshots by running `make updateSnapshot`. Running these browser tests requires `docker`. Follow the docker [install instructions for mac](https://docs.docker.com/docker-for-mac/install/). You may want to increase the [memory usage](https://docs.docker.com/docker-for-mac/#resources). If you have not already, you'll need to create an account for `docker hub` and [sign-in locally](https://docs.docker.com/docker-for-mac/#docker-hub).