@readme/markdown 7.6.6 → 7.7.0

package/README.md

@@ -1,129 +1,110 @@
-# @readme/markdown
+# <img align="right" width="26%" src="https://owlbertsio-resized.s3.amazonaws.com/Reading.psd.full.png"> `@readme/markdown`
 
-<img align="right" width="26%" src="https://owlbertsio-resized.s3.amazonaws.com/Reading.psd.full.png">
+<img align=right src=https://github.com/readmeio/markdown/workflows/CI/badge.svg alt="RDMD CI Status"> ReadMe's MDX rendering engine and custom component collection.
+<br/>  *(Use ReadMe? [Learn more about our upcoming move to MDX](https://docs.readme.com/rdmd/page/mdx-engine)!)*
 
-ReadMe's MDX rendering engine and custom component collection. <img align=center src=https://github.com/readmeio/markdown/workflows/CI/badge.svg alt="RDMD CI Status">
+## Getting Started
+
+To use the engine, install it from NPM:
 
 ```
 npm install --save @readme/markdown
 ```
 
-## Usage
+Then [`compile`](#compile) and [`run`](#run) your MDX:
 
 ```jsx
-import React from 'react';
-import rmdx from '@readme/markdown';
+import RMDX from '@readme/markdown';
 
-export default ({ body }) => <div className="markdown-body">{run(compile(body))}</div>;
+export default ({ body }) => (
+  <div className="markdown-body">
+    {RMDX.run(RMDX.compile(body))}
+  </div>
+);
 ```
 
-### API
+## API
 
-#### `compile`
+### `compile`
 
-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.
+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
+#### Parameters
 
-- `string` (`string`) -- an MDX document
-- `opts` ([`CompileOpts`](#compileopts), optional) -- a configuration object
+- **`string`** (`string`)—an MDX document
+- **`opts`** ([`CompileOpts`](#compileopts), optional)—a configuration object
 
-###### Returns
+#### Returns
 
-compiled code (`string`)
+A string of compiled Javascript module code.
 
-#### `run`
+### `run`
 
 > [!CAUTION]
-> **This will `eval` the compiled MDX**! Essentially a wrapper around [`mdx.run`](https://mdxjs.com/packages/mdx/#runcode-options).
-
-###### 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.
-
-###### Parameters
-
-Extends [`remark-stringify` options](https://github.com/remarkjs/remark/tree/main/packages/remark-stringify#options).
-
-###### Returns
+> 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.
 
-An mdx string.
+### `mdx`
 
-#### `mdast`
+Compiles an AST to a string of MDX syntax.
 
-Parses mdx to an mdast.
+#### Parameters
 
-#### `hast`
+- **`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.
 
-Parses mdx to an hast.
+#### Returns
 
-#### `plain`
+An MDX string.
 
-Parses mdx to a plain string. (This **does** not `eval` the doc.)
+### Other Methods
 
-#### `tags`
+- **`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.
 
-Returns a list of tag names from the doc. (This **does** not `eval` the doc.)
-
-#### `utils`
-
-Additional defaults, helpers, components, etc.
+## Types
 
 ### `CompileOpts`
 
 Extends [`CompileOptions`](https://mdxjs.com/packages/mdx/#compileoptions)
 
-###### Additional Properties
+##### 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) — add a copy button to code blocks
+- **`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) — add a copy button to code blocks
 
 ### `RunOpts`
 
 Extends [`RunOptions`](https://mdxjs.com/packages/mdx/#runoptions)
 
-###### Additional Properties
+##### Additional Properties
 
-- `components` (`Record<string, MDXModule>`, optional) -- a set of custom MDX components
-- `imports` (`Record<string, unknown>`, optional) -- an set of modules to import globally
-- `terms` (`GlossaryTerm[]`, optional)
-- `variables` (`Variables`, optional) -- an object containing [user variables](https://github.com/readmeio/variable)
+- **`components`** (`Record<string, MDXModule>`, optional)—a set of custom MDX components
+- **`imports`** (`Record<string, unknown>`, 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
+##### Properties
 
-## Flavored Syntax
+- **`default`** (`() => MDXContent`)—the MDX douments default export
+- **`toc`** (`HastHeading[]`)—a list of headings in the document
+- **`Toc`** (`() => MDCContent`)—a table of contents component
 
-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
+## 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`!
 
-### Environment setup
-
-Running the 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).
-
-### Running visual regression tests
-
-If you make changes to the docs or how the markdown is rendered, you may need to update the visual regression snapshots. You can run the visual regression tests in a docker container with:
-
-```
-make updateSnapshot
-```
+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).

package/components/Code/index.tsx

@@ -16,20 +16,20 @@ if (typeof window !== 'undefined') {
 
 function CopyCode({ codeRef, rootClass = 'rdmd-code-copy', className = '' }) {
   const copyClass = `${rootClass}_copied`;
-  const button = createRef<HTMLButtonElement>();
+  const buttonRef = createRef<HTMLButtonElement>();
 
   const copier = () => {
     const code = codeRef.current.textContent;
 
     if (copy(code)) {
-      const el = button.current;
+      const el = buttonRef.current;
       el.classList.add(copyClass);
 
       setTimeout(() => el.classList.remove(copyClass), 1500);
     }
   };
 
-  return <button ref={button} aria-label="Copy Code" className={`${rootClass} ${className}`} onClick={copier} />;
+  return <button ref={buttonRef} aria-label="Copy Code" className={`${rootClass} ${className}`} onClick={copier} />;
 }
 
 interface CodeProps {
@@ -57,6 +57,10 @@ const Code = (props: CodeProps) => {
   const code = value ?? (Array.isArray(children) ? children[0] : children) ?? '';
   const highlightedCode = syntaxHighlighter && code ? syntaxHighlighter(code, language, codeOpts, { mdx: true }) : code;
 
+  if (language === 'mermaid') {
+    return code;
+  }
+
   return (
     <>
       {copyButtons && <CopyCode className="fa" codeRef={codeRef} />}

package/components/Code/style.scss

@@ -84,6 +84,12 @@
     word-wrap: normal;
   }
 
+  pre.mermaid {
+    &_single {
+      background: var(--color-bg-page, white);
+    }
+  }
+
   kbd {
     background-color: $background;
     background-color: var(--d-code-background, $background);

package/components/CodeTabs/index.tsx

@@ -1,9 +1,17 @@
 import { uppercase } from '@readme/syntax-highlighter';
-import React from 'react';
+import React, { useEffect } from 'react';
+import mermaid from 'mermaid';
 
 const CodeTabs = props => {
   const { children, theme } = props;
 
+  // set Mermaid theme
+  useEffect(() => {
+    mermaid.initialize({
+      theme: theme === 'dark' ? 'dark' : 'default',
+    });
+  }, [theme])
+
   function handleClick({ target }, index: number) {
     const $wrap = target.parentElement.parentElement;
     const $open = [].slice.call($wrap.querySelectorAll('.CodeTabs_active'));
@@ -14,6 +22,21 @@ const CodeTabs = props => {
     codeblocks[index].classList.add('CodeTabs_active');
 
     target.classList.add('CodeTabs_active');
+
+    if (target.value === 'mermaid') {
+      const $openMermaid = [].slice.call($wrap.querySelectorAll('.mermaid'));
+      $openMermaid.forEach((el: Element) => el.classList.remove('mermaid'));
+      codeblocks[index].classList.add('mermaid');
+      mermaid.contentLoaded();
+    }
+  }
+
+  // render single Mermaid diagram
+  if (!Array.isArray(children) && children.props?.children.props.lang === 'mermaid') {
+    const value = children.props.children.props.value;
+    return (
+      <pre className="mermaid mermaid_single">{value}</pre>
+    )
   }
 
   return (
@@ -24,7 +47,7 @@ const CodeTabs = props => {
 
           /* istanbul ignore next */
           return (
-            <button key={i} onClick={e => handleClick(e, i)} type="button">
+            <button key={i} onClick={e => handleClick(e, i)} type="button" value={lang}>
               {meta || `${!lang ? 'Text' : uppercase(lang)}`}
             </button>
           );

package/components/Image/style.scss

@@ -28,15 +28,19 @@
     outline: none !important;
     vertical-align: middle;
 
+    &.img-align-right,
     &[align='right'],
     &[alt~='align-right'] {
       @extend %img-align-right;
     }
 
+    &.img-align-left,
     &[align='left'],
     &[alt~='align-left'] {
       @extend %img-align-left;
+
     }
+    &.img-align-center,
     &[align='middle'], // hack to fix Firefox; see: https://stackoverflow.com/a/45901819/1341949
     &[align='center'],
     &[alt~='align-center'] {
@@ -65,8 +69,10 @@
     }
   }
 
+  > .img,
   > img,
   figure > img {
+    display: block;
     @extend %img-align-center;
   }
 
@@ -97,16 +103,13 @@
       content: '\f00d';
       cursor: pointer;
       display: inline-block;
-      font: normal normal normal 2em/1 FontAwesome;
+      font-family: var(--fa-style-family, 'Font Awesome 6 Pro');
       font-size: inherit;
-      -webkit-font-smoothing: antialiased;
-      -moz-osx-font-smoothing: grayscale;
       opacity: 1;
       position: fixed;
       right: 1em;
       text-rendering: auto;
       top: 1em;
-      transform: translate(0, 0);
       transform: scale(1.5);
       transition: 0.3s 0.3s ease-in;
     }