@readme/markdown 6.87.1 → 6.88.0

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) -- An object containing [user variables}(https://github.com/readmeio/variable).
 
-### 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/components/Anchor.jsx

@@ -1,11 +1,11 @@
-const PropTypes = require('prop-types');
-const React = require('react');
+import { string, node } from 'prop-types';
+import React from 'react';
 
-const BaseUrlContext = require('../contexts/BaseUrl');
+import BaseUrlContext from '../contexts/BaseUrl';
 
 // Nabbed from here:
 // https://github.com/readmeio/api-explorer/blob/0dedafcf71102feedaa4145040d3f57d79d95752/packages/api-explorer/src/lib/markdown/renderer.js#L52
-function getHref(href, baseUrl) {
+export function getHref(href, baseUrl) {
   const [path, hash] = href.split('#');
   const hashStr = hash ? `#${hash}` : '';
 
@@ -18,7 +18,7 @@ function getHref(href, baseUrl) {
 
   const ref = path.match(/^ref:([-_a-zA-Z0-9#]*)$/);
   if (ref) {
-    return `${base}/reference/${ref[1]}${hashStr}`;
+    return `${base}/reference-link/${ref[1]}${hashStr}`;
   }
 
   // we need to perform two matches for changelogs in case
@@ -49,7 +49,9 @@ function docLink(href) {
 }
 
 function Anchor(props) {
-  const { baseUrl, children, href, target, title, ...attrs } = props;
+  const { children, href, target, title, ...attrs } = props;
+  const baseUrl = useContext(BaseUrlContext);
+
   return (
     // eslint-disable-next-line react/jsx-props-no-spreading
     <a {...attrs} href={getHref(href, baseUrl)} target={target} title={title} {...docLink(href)}>
@@ -59,12 +61,12 @@ function Anchor(props) {
 }
 
 Anchor.propTypes = {
-  baseUrl: PropTypes.string,
-  children: PropTypes.node.isRequired,
-  download: PropTypes.string,
-  href: PropTypes.string,
-  target: PropTypes.string,
-  title: PropTypes.string,
+  baseUrl: string,
+  children: node.isRequired,
+  download: string,
+  href: string,
+  target: string,
+  title: string,
 };
 
 Anchor.defaultProps = {
@@ -74,17 +76,4 @@ Anchor.defaultProps = {
   title: '',
 };
 
-const AnchorWithContext = props => (
-  <BaseUrlContext.Consumer>{baseUrl => <Anchor baseUrl={baseUrl} {...props} />}</BaseUrlContext.Consumer>
-);
-
-AnchorWithContext.sanitize = sanitizeSchema => {
-  // This is for our custom link formats
-  sanitizeSchema.protocols.href.push('doc', 'target', 'ref', 'blog', 'changelog', 'page');
-
-  return sanitizeSchema;
-};
-
-module.exports = AnchorWithContext;
-
-AnchorWithContext.getHref = getHref;
+export default Anchor;

package/components/Callout/index.tsx

@@ -0,0 +1,41 @@
+import * as React from 'react';
+
+interface Props extends React.PropsWithChildren<React.HTMLAttributes<HTMLQuoteElement>> {
+  attributes?: {};
+  icon: string;
+  theme?: string;
+  empty?: boolean;
+}
+
+const themes: Record<string, string> = {
+  '\uD83D\uDCD8': 'info',
+  '\uD83D\uDEA7': 'warn',
+  '\u26A0\uFE0F': 'warn',
+  '\uD83D\uDC4D': 'okay',
+  '\u2705': 'okay',
+  '\u2757\uFE0F': 'error',
+  '\u2757': 'error',
+  '\uD83D\uDED1': 'error',
+  '\u2049\uFE0F': 'error',
+  '\u203C\uFE0F': 'error',
+  '\u2139\uFE0F': 'info',
+  '\u26A0': 'warn',
+};
+
+const Callout = (props: Props) => {
+  const { attributes, children, icon, empty } = props;
+  let theme = props.theme || themes[icon] || 'default';
+
+  return (
+    // @ts-ignore
+    <blockquote {...attributes} className={`callout callout_${theme}`} theme={icon}>
+      <h3 className={`callout-heading${empty ? ' empty' : ''}`}>
+        <span className="callout-icon">{icon}</span>
+        {empty || React.Children.toArray(children)[0]}
+      </h3>
+      {React.Children.toArray(children).slice(1)}
+    </blockquote>
+  );
+};
+
+export default Callout;

package/components/Callout/style.scss

@@ -1,19 +1,16 @@
-/* stylelint-disable no-descending-specificity */
-/* stylelint-disable font-family-no-missing-generic-family-keyword */
-/* stylelint-disable order/properties-alphabetical-order */
-/* stylelint-disable order/order */
 @mixin callout($l-offset: 1.33rem) {
   --background: #{lighten(#dfe2e5, 8.75%)};
   --border: #{lighten(#6a737d, 12.5%)};
 
-  background: var(--background);
-  border-color: var(--border);
-  color: var(--text);
-  padding: $l-offset;
+  & {
+    background: var(--background);
+    border-color: var(--border);
+    color: var(--text);
+    padding: $l-offset;
+  }
 
   &_info {
     $color: #46b8da;
-
     --background: #e3edf2;
     --title: #{$color};
     --border: #{lighten($color, 5%)}; // should be #5bc0de
@@ -22,7 +19,6 @@
   &_warn,
   &_warning {
     $color: #eea236;
-
     --background: #fcf8f2;
     --title: #{$color};
     --border: #{lighten($color, 5%)};
@@ -32,7 +28,6 @@
   &_okay,
   &_success {
     $color: #489e49;
-
     --background: #f3f8f3;
     --title: #{$color};
     --border: #{lighten($color, 5%)}; // should be #50af51
@@ -41,7 +36,6 @@
   &_err,
   &_error {
     $color: #d43f3a;
-
     --background: #fdf7f7;
     --title: #{$color};
     --border: #{lighten($color, 5%)}; // should be #d9534f
@@ -51,7 +45,6 @@
     margin-left: $l-offset;
     position: relative;
   }
-
   ul,
   ol {
     padding-left: 1.3em;
@@ -60,11 +53,9 @@
   a {
     color: inherit;
   }
-
   hr {
     border-color: var(--border, var(--markdown-edge, #eee));
   }
-
   blockquote {
     color: var(--text);
     border-color: var(--border);
@@ -74,10 +65,6 @@
 
   .callout-heading {
     color: var(--title, --text);
-    font-size: 1.25em; // match h3
-    font-family: var(--markdown-title-font); // match h3
-    font-weight: var(--markdown-title-weight, 600); // match h3
-    line-height: 1.25; // match h3
     margin-bottom: calc(#{$l-offset} * 0.5);
 
     &:only-child {
@@ -87,18 +74,15 @@
     &.empty {
       float: left;
       margin-top: calc(#{$l-offset} * 0.5);
-
       .callout-icon {
         line-height: 0;
       }
     }
-
     > * {
       color: inherit;
       margin: 0;
     }
-
-    &::before {
+    &:before {
       position: absolute;
       right: 100%;
       width: 2.4em;
@@ -106,24 +90,20 @@
       font: normal normal normal 1em/1 FontAwesome;
     }
   }
-
   .callout-icon {
     float: left;
     margin-left: calc(-#{$l-offset} - 0.5em);
     margin-right: -0.25rem;
   }
 }
-
-@mixin callout-custom-icons($R: callout) {
+@mixin calloutCustomIcons($R: callout) {
   --emoji: 1em;
-  --icon-font: fontawesome;
-
+  --icon-font: FontAwesome;
   &-icon {
     font-size: var(--emoji, 0);
     color: var(--icon-color, inherit) !important;
   }
-
-  &-icon::before {
+  &-icon:before {
     content: var(--icon);
     font-family: var(--icon-font);
     font-size: var(--icon-size, 1rem);
@@ -136,30 +116,24 @@
     -webkit-font-smoothing: antialiased;
     -moz-osx-font-smoothing: grayscale;
   }
-
   @at-root .rdmdCallouts--useIconFont & {
     --emoji: unset;
-
     &_okay {
       /* thumbs up */
       --icon: '\f164';
     }
-
     &_info {
       /* info circle */
       --icon: '\f05a';
     }
-
     &_warn {
       /* warning triangle */
       --icon: '\f071';
     }
-
     &_error {
       /* warning circle */
       --icon: '\f06a';
     }
-
     &_default {
       /* warning circle */
       --emoji: 1rem;
@@ -172,9 +146,7 @@
     // bump specificity
     @include callout;
   }
-
-  @include callout-custom-icons;
-
+  @include calloutCustomIcons;
   border-top-right-radius: var(--markdown-radius);
   border-bottom-right-radius: var(--markdown-radius);
 }

package/components/CardsGrid/index.tsx

@@ -0,0 +1,18 @@
+import React from 'react';
+
+import './style.scss';
+
+const Card = ({ children }) => <div className="Card">{children}</div>;
+
+const CardsGrid = ({ columns = 2, children }) => {
+  columns = columns >= 2 ? columns : 2;
+  return (
+    <div className="CardsGrid" style={{ gridTemplateColumns: `repeat(${columns}, 1fr)` }}>
+      {React.Children.map(children, e => (
+        <Card>{e}</Card>
+      ))}
+    </div>
+  );
+};
+
+export default CardsGrid;

package/components/CardsGrid/style.scss

@@ -0,0 +1,12 @@
+.CardsGrid {
+  display: grid;
+  gap: 20px;
+
+  .Card {
+    padding: 10px;
+    backdrop-filter: blur(20px);
+    border: 1px solid rgba(black, 0.1);
+    border-radius: 5px;
+    box-shadow: 0 1px 2px #{rgba(black, 0.05)}, 0 2px 5px #{rgba(black, 0.02)};
+  }
+}

package/components/Code/index.tsx

@@ -0,0 +1,75 @@
+import copy from 'copy-to-clipboard';
+import React, { createRef } from 'react';
+
+// Only load CodeMirror in the browser, for SSR
+// apps. Necessary because of people like this:
+// https://github.com/codemirror/CodeMirror/issues/3701#issuecomment-164904534
+let syntaxHighlighter;
+let canonicalLanguage = _ => '';
+
+if (typeof window !== 'undefined') {
+  import('@readme/syntax-highlighter').then(module => {
+    syntaxHighlighter = module.default;
+    canonicalLanguage = module.canonical;
+  });
+}
+
+function CopyCode({ codeRef, rootClass = 'rdmd-code-copy', className = '' }) {
+  const copyClass = `${rootClass}_copied`;
+  const button = createRef<HTMLButtonElement>();
+
+  const copier = () => {
+    const code = codeRef.current.textContent;
+
+    if (copy(code)) {
+      const el = button.current;
+      el.classList.add(copyClass);
+
+      setTimeout(() => el.classList.remove(copyClass), 1500);
+    }
+  };
+
+  return <button ref={button} aria-label="Copy Code" className={`${rootClass} ${className}`} onClick={copier} />;
+}
+
+interface CodeProps {
+  children?: string[] | string;
+  copyButtons?: boolean;
+  lang?: string;
+  meta?: string;
+  theme?: string;
+  value?: string;
+}
+
+const Code = (props: CodeProps) => {
+  const { children, copyButtons, lang, theme, value } = props;
+
+  const language = canonicalLanguage(lang);
+
+  const codeRef = createRef<HTMLElement>();
+
+  const codeOpts = {
+    inline: !lang,
+    tokenizeVariables: true,
+    dark: theme === 'dark',
+  };
+
+  const code = value ?? (Array.isArray(children) ? children[0] : children) ?? '';
+  const highlightedCode = syntaxHighlighter && code ? syntaxHighlighter(code, language, codeOpts, { mdx: true }) : code;
+
+  return (
+    <>
+      {copyButtons && <CopyCode className="fa" codeRef={codeRef} />}
+      <code
+        ref={codeRef}
+        className={['rdmd-code', `lang-${language}`, `theme-${theme}`].join(' ')}
+        data-lang={language}
+        suppressHydrationWarning={true}
+      >
+        {highlightedCode}
+      </code>
+    </>
+  );
+};
+
+export default Code;

package/components/Code/style.scss

@@ -1,16 +1,16 @@
-/* stylelint-disable no-duplicate-selectors */
-/* stylelint-disable no-descending-specificity */
-/* stylelint-disable font-family-no-missing-generic-family-keyword */
-/* stylelint-disable declaration-property-value-disallowed-list */
-/* stylelint-disable scss/selector-no-redundant-nesting-selector */
-/* stylelint-disable order/properties-alphabetical-order */
-@mixin gfm-code-base-styles($background: #f6f8fa, $background-dark: #242e34, $text: inherit) {
+@mixin gfmCodeBaseStyles($background: #f6f8fa, $background-dark: #242e34, $text: inherit) {
   --font-size: 90%;
 
   code,
   kbd,
   pre {
-    font-family: SFMono-Regular, Consolas, 'Liberation Mono', Menlo, Courier, monospace;
+    font-family:
+      SFMono-Regular,
+      Consolas,
+      Liberation Mono,
+      Menlo,
+      Courier,
+      monospace;
     font-family: var(--md-code-font, SFMono-Regular, Consolas, Liberation Mono, Menlo, Courier, monospace);
     font-size: 1em;
   }
@@ -23,7 +23,6 @@
   pre {
     margin-bottom: 0;
     margin-top: 0;
-    word-wrap: normal;
   }
 
   code {
@@ -40,6 +39,10 @@
     }
   }
 
+  pre {
+    word-wrap: normal;
+  }
+
   pre > code {
     background: 0 0;
     border: 0;
@@ -97,29 +100,32 @@
   }
 }
 
-@mixin copy-code-button {
+@mixin copyCodeButton {
   button.rdmd-code-copy {
-    appearance: unset;
-    background: inherit;
-    background: var(--md-code-background, inherit);
-    border: none;
-    border-radius: 3px;
-    box-shadow:
-      inset 0 0 0 1px rgba(#aaa, 0.66),
-      -1px 2px 6px -3px rgba(black, 0.1);
-    color: inherit;
-    color: var(--md-code-text, inherit);
-    cursor: copy;
     display: none !important; // hide by default
-    font: inherit;
-    margin: 0.5em 0.6em 0 0;
-    outline: none !important;
-    padding: 0.25em 0.7em;
-    transition: 0.15s ease-out;
+
+    & {
+      -webkit-appearance: unset;
+      margin: 0.5em 0.6em 0 0;
+      padding: 0.25em 0.7em;
+      cursor: copy;
+      font: inherit;
+      color: inherit;
+      color: var(--md-code-text, inherit);
+      border: none;
+      border-radius: 3px;
+      outline: none !important;
+      background: inherit;
+      background: var(--md-code-background, inherit);
+      box-shadow:
+        inset 0 0 0 1px rgba(#aaa, 0.66),
+        -1px 2px 6px -3px rgba(black, 0.1);
+      transition: 0.15s ease-out;
+    }
 
     &:not(:hover) {
-      &::before,
-      &::after {
+      &:before,
+      &:after {
         opacity: 0.66;
       }
     }
@@ -137,41 +143,42 @@
         inset 0 0 0 1px rgba(#8b8b8b, 0.5),
         inset 1px 4px 6px -2px rgba(0, 0, 0, 0.175);
 
-      &::before,
-      &::after {
+      &:before,
+      &:after {
         opacity: 0.75;
       }
     }
 
-    &::before,
-    &::after {
+    &:before,
+    &:after {
       display: inline-block;
       font:
         normal normal normal 1em/1 'Font Awesome 5 Free',
-        FontAwesome;
-      font-family: ReadMe-Icons;
-      font-feature-settings: 'liga';
-      font-variant-ligatures: discretionary-ligatures;
-      line-height: 2;
+        'FontAwesome';
       text-rendering: auto;
       -webkit-font-smoothing: antialiased;
+
+      line-height: 2;
+      font-family: 'ReadMe-Icons';
+      font-variant-ligatures: discretionary-ligatures;
+      font-feature-settings: 'liga';
     }
 
-    &::before {
+    &:before {
       content: '\e6c9';
       font-weight: 800;
       transition: 0.3s 0.15s ease;
     }
 
-    &::after {
+    &:after {
       // @todo why are these !important @rafe, you dumbell?
       content: '\e942' !important;
       font-weight: 900 !important;
-      left: 50%;
-      opacity: 0 !important;
       position: absolute;
       top: 50%;
+      left: 50%;
       transform: translate(-50%, -50%) scale(0.33);
+      opacity: 0 !important;
       transition: 0.3s 0s ease;
     }
 
@@ -185,16 +192,16 @@
         opacity: 1;
       }
 
-      &::before {
-        opacity: 0 !important;
+      &:before {
         transition: 0.3s 0s ease;
         transform: scale(0.33);
+        opacity: 0 !important;
       }
 
-      &::after {
-        opacity: 1 !important;
+      &:after {
         transition: 0.3s 0.15s ease;
         transform: translate(-50%, -50%) scale(1);
+        opacity: 1 !important;
       }
     }
   }
@@ -245,6 +252,6 @@
 
 .markdown-body {
   // --md-code-background: #F6F8FA;
-  @include gfm-code-base-styles;
-  @include copy-code-button;
+  @include gfmCodeBaseStyles;
+  @include copyCodeButton;
 }