From 0b5f89b86d4866fbe04b7c5f569becb443e0855d Mon Sep 17 00:00:00 2001 From: Rafe Goldberg Date: Thu, 29 Aug 2024 13:43:28 -0400 Subject: [PATCH] docs: update readme for MDX (#957) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## 🧰 Changes - [x] update the repo's readme for an MDX world - [x] some minor housekeeping edits for consistency --------- Co-authored-by: Mansa --- README.md | 53 ++++++++++++++++++----------------------------------- 1 file changed, 18 insertions(+), 35 deletions(-) diff --git a/README.md b/README.md index 0dfd0bebb..42b25d269 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ -ReadMe's flavored Markdown parser and MDX rendering engine. RDMD CI Status +ReadMe's MDX rendering engine and custom component collection. RDMD CI Status ``` npm install --save @readme/markdown @@ -21,14 +21,12 @@ export default ({ body }) =>
{run(compile(body))} #### `compile` -Compiles mdx to js. A wrapper around [`mdx.compile`](https://mdxjs.com/packages/mdx/#compilefile-options) - -You usually only need this when calling `run` as well. It's been left as a seperate step as a potential caching opportunity. +Compiles MDX to JS. Essentially a wrapper around [`mdx.compile`](https://mdxjs.com/packages/mdx/#compilefile-options). You usually only need this when calling `run` as well. It's been left as a seperate step as a potential caching opportunity. ###### Parameters -- `string` (`string`) -- An mdx document -- `opts` ([`CompileOpts`](#compileopts), optional) -- configuration +- `string` (`string`) -- an MDX document +- `opts` ([`CompileOpts`](#compileopts), optional) -- a configuration object ###### Returns @@ -36,10 +34,8 @@ compiled code (`string`) #### `run` -Run compiled code. A wrapper around [`mdx.run`](https://mdxjs.com/packages/mdx/#runcode-options) - > [!CAUTION] -> This `eval`'s JavaScript. +> **This will `eval` the compiled MDX**! Essentially a wrapper around [`mdx.run`](https://mdxjs.com/packages/mdx/#runcode-options). ###### Parameters @@ -64,17 +60,11 @@ Parses mdx to an hast. #### `plain` -Parses mdx to a plain string. - -> [!WARNING] -> This **does** not `eval` the doc. +Parses mdx to a plain string. (This **does** not `eval` the doc.) #### `tags` -Returns a list of tag names from the doc. - -> [!WARNING] -> This **does** not `eval` the doc. +Returns a list of tag names from the doc. (This **does** not `eval` the doc.) #### `utils` @@ -86,10 +76,10 @@ 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) — Automatically insert a button to copy a block of text to the clipboard. Currently used on `` elements. +- `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` @@ -97,24 +87,22 @@ Extends [`RunOptions`](https://mdxjs.com/packages/mdx/#runoptions) ###### Additional Properties -- `components` (`Record`, optional) -- An object of tag names to executed components. -- `imports` (`Record`, optional) -- An object of modules to import. +- `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). +- `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 +- `default` (`() => MDXContent`) -- the MDX douments default export +- `toc` (`HastHeading[]`) -- a list of headings in the document +- `Toc` (`() => MDCContent`) -- a table of contents component ## Flavored Syntax -~~Our old editor rendered "Magic Block" components from a custom, JSON-based syntax. To provide seamless backwards-compatibility, our new processor ships with built in support for parsing this old format, and transpiles it straight in to our new, flavored Markdown.~~ - -We've also sprinkled a bit of our own syntactic sugar on top to let you supercharge your docs. [**Learn more about ReadMe's flavored syntax!**](https://docs.readme.com/rdmd/docs/syntax-extensions) +We've also sprinkled a bit of our own custom components in to help you supercharge your docs. [**Learn more about ReadMe's new MDX engine!**](https://docs.readme.com/rdmd/page/mdx-engine) ## Local Development @@ -131,8 +119,3 @@ If you make changes to the docs or how the markdown is rendered, you may need to ``` make updateSnapshot ``` - -## Credits - -- **License**: MIT -- **Authors**: [Dom Harrington](https://github.com/domharrington/), [Rafe Goldberg](https://github.com/rafegoldberg)