@readme/markdown 6.75.0-beta.49 → 6.75.0-beta.51

package/README.md

@@ -10,42 +10,100 @@ npm install --save @readme/markdown
 
 ## Usage
 
-By default, the updated markdown package exports a function which takes a string of [ReadMe-flavored markdown](https://docs.readme.com/rdmd/docs/syntax-extensions) and returns a tree of React components:
-
 ```jsx
 import React from 'react';
-import rdmd from '@readme/markdown';
+import rmdx from '@readme/markdown';
 
-export default ({ body }) => <div className="markdown-body">{rdmd(body)}</div>;
+export default ({ body }) => <div className="markdown-body">{run(compile(body))}</div>;
 ```
 
-### Export Methods
+### API
+
+#### `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.
+
+###### Parameters
+
+- `string` (`string`) -- An mdx document
+- `opts` ([`CompileOpts`](#compileopts), optional) -- configuration
+
+###### Returns
+
+compiled code (`string`)
+
+#### `run`
+
+Run compiled code. A wrapper around [`mdx.run`](https://mdxjs.com/packages/mdx/#runcode-options)
+
+> [!CAUTION]
+> This `eval`'s JavaScript.
+
+###### Parameters
+
+- `string` (`string`) -- A compiled mdx document
+- `opts` (`RunOpts`, optional) -- configuration
+
+###### Returns
+
+A module ([`RMDXModule`](#rmdxmodule)) of renderable components
+
+#### `mdx`
+
+Compiles an ast to mdx.
+
+#### `mdast`
+
+Parses mdx to an mdast.
+
+#### `hast`
+
+Parses mdx to an hast.
+
+#### `plain`
+
+> [!NOTE]
+> unimplemented
+
+#### `utils`
+
+Additional defaults, helpers, components, etc.
+
+### `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<string, string>`, 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 `<code>` elements.
+
+### `RunOpts`
+
+Extends [`RunOptions`](https://mdxjs.com/packages/mdx/#runoptions)
 
-In addition to the default React processor, the package exports some other methods for transforming ReadMe-flavored markdown:
+###### Additional Properties
 
-|    Export | Description                                    | Arguments         |
-| --------: | :--------------------------------------------- | :---------------- |
-| _`react`_ | _(default)_ returns a VDOM tree object         | `text`, `options` |
-|    _`md`_ | transform mdast in to ReadMe-flavored markdown | `tree`, `options` |
-|  _`html`_ | transform markdown in to HTML                  | `text`, `options` |
-| _`mdast`_ | transform markdown to an mdast object          | `text`, `options` |
-|  _`hast`_ | transform markdown to HAST object              | `text`, `options` |
-| _`plain`_ | transform markdown to plain text               | `text`, `options` |
-| _`utils`_ | contexts, defaults, helpers, etc.              | N/A               |
+- `components` (`Record<string, MDXModule>`, optional) -- An object of tag names to executed components.
+- `imports` (`Record<string, unknown>`, optional) -- An object of modules to import.
+- `terms` (`GlossaryTerm[]`, optional)
+- `variables` (`Variables`, optional)
 
-### Settings & Options
+### `RMDXModule`
 
-Each processor method takes an options object which you can use to adjust the output HTML or React tree. These options include:
+###### Properties
 
-- **`compatibilityMode`** — Enable [compatibility features](https://github.com/readmeio/api-explorer/issues/668) from our old markdown engine.
-- **`copyButtons`** — Automatically insert a button to copy a block of text to the clipboard. Currently used on `<code>` elements.
-- **`correctnewlines`** — Render new line delimeters as `<br>` tags.
-- **`markdownOptions`** — Remark [parser options](https://github.com/remarkjs/remark/tree/main/packages/remark-stringify#processorusestringify-options).
-- **`safeMode`** — Render html blocks as `<pre>` elements. We normally allow all manner of html attributes that could potentially execute JavaScript.
+- `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.
+~~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)
 

package/dist/index.d.ts

@@ -1,15 +1,12 @@
 import * as Components from './components';
-import { compile, run, mdx } from './lib';
+import { compile, hast, run, mdast, mdx, plain } from './lib';
 import './styles/main.scss';
 declare const utils: {
     readonly options: any;
     getHref: any;
     calloutIcons: {};
 };
-export { compile, run, mdx, Components, utils };
 export declare const reactProcessor: (opts?: {}) => import("unified").Processor<import("mdast").Root, import("estree").Program, import("estree").Program, import("estree").Program, string>;
 export declare const html: (text: string, opts?: {}) => void;
-export declare const mdast: any;
-export declare const hast: (text: string, opts?: {}) => import("hast").Root;
 export declare const esast: (text: string, opts?: {}) => void;
-export declare const plain: (text: string, opts?: {}) => void;
+export { compile, hast, run, mdast, mdx, plain, Components, utils };

package/dist/lib/compile.d.ts

@@ -1,9 +1,8 @@
 import { CompileOptions } from '@mdx-js/mdx';
-import { VFileWithToc } from '../types';
 export type CompileOpts = CompileOptions & {
-    components?: Record<string, VFileWithToc>;
     lazyImages?: boolean;
     safeMode?: boolean;
+    components?: Record<string, string>;
 };
-declare const compile: (text: string, opts?: CompileOpts) => VFileWithToc;
+declare const compile: (text: string, { components, ...opts }?: CompileOpts) => string;
 export default compile;

package/dist/lib/hast.d.ts

@@ -0,0 +1,5 @@
+interface Options {
+    components?: Record<string, string>;
+}
+declare const hast: (text: string, opts?: Options) => import("hast").Root;
+export default hast;

package/dist/lib/index.d.ts

@@ -1,6 +1,9 @@
 import astProcessor, { MdastOpts, remarkPlugins } from './ast-processor';
 import compile from './compile';
+import hast from './hast';
+import mdast from './mdast';
 import mdx from './mdx';
+import plain from './plain';
 import run from './run';
 export type { MdastOpts };
-export { astProcessor, compile, mdx, run, remarkPlugins };
+export { astProcessor, compile, hast, mdast, mdx, plain, run, remarkPlugins };

package/dist/lib/mdast.d.ts

@@ -0,0 +1,2 @@
+declare const mdast: any;
+export default mdast;

package/dist/lib/plain.d.ts

@@ -0,0 +1,3 @@
+import { Nodes } from 'hast';
+declare const plain: (node: Nodes, opts?: {}) => string | number | true | (string | number)[];
+export default plain;

package/dist/lib/run.d.ts

@@ -1,7 +1,7 @@
 import React from 'react';
 import { RunOptions } from '@mdx-js/mdx';
-import { VFileWithToc } from '../types';
 import { GlossaryTerm } from '../contexts/GlossaryTerms';
+import { CustomComponents } from '../types';
 interface Variables {
     user: Record<string, string>;
     defaults: {
@@ -10,15 +10,15 @@ interface Variables {
     }[];
 }
 export type RunOpts = Omit<RunOptions, 'Fragment'> & {
-    components?: ComponentOpts;
+    components?: CustomComponents;
     imports?: Record<string, unknown>;
     baseUrl?: string;
     terms?: GlossaryTerm[];
     variables?: Variables;
 };
-type ComponentOpts = Record<string, (props: any) => React.ReactNode>;
-declare const run: (stringOrFile: string | VFileWithToc, _opts?: RunOpts) => Promise<{
+declare const run: (string: string, _opts?: RunOpts) => Promise<{
     default: () => React.JSX.Element;
-    toc: () => React.JSX.Element;
+    toc: import("../types").IndexableElements[];
+    Toc: () => React.JSX.Element;
 }>;
 export default run;