docs: add syntax highlighting example

quantizor · Jan 1, 2024 · f665b00 · f665b00
1 parent c68b1fb
commit f665b00
Show file tree

Hide file tree

Showing 5 changed files with 103 additions and 20 deletions.
diff --git a/README.md b/README.md
@@ -46,7 +46,7 @@ The most lightweight, customizable React markdown component.
 
 - GFM task list support.
 
-- Fenced code blocks with [highlight.js](https://highlightjs.org/) support.
+- Fenced code blocks with [highlight.js](https://highlightjs.org/) support; see [Syntax highlighting](#syntax-highlighting) for instructions on setting up highlight.js.
 
 All this clocks in at around 6 kB gzipped, which is a fraction of the size of most other React markdown components.
 
@@ -503,20 +503,58 @@ compiler('This text has <span>html</span> in it but it won't be rendered', { dis
 
 ### Syntax highlighting
 
-Some syntax highlighters require you to specify the language. The language of the code fence is
-forwarded in the className prop of the element used for `<code>`:
+When using [fenced code blocks](https://www.markdownguide.org/extended-syntax/#syntax-highlighting) with language annotation, that language will be added to the `<code>` element as `class="lang-${language}"`. For best results, you can use `options.overrides` to provide an appropriate syntax highlighting integration like this one using `highlight.js`:
 
-```jsx
-const Code = ({ className, children }) => {
-  const language = className.replace('lang-', '')
+````jsx
+import { Markdown, RuleType } from 'markdown-to-jsx'
+
+const mdContainingFencedCodeBlock = '```js\nconsole.log("Hello world!");\n```\n'
 
+function App() {
   return (
-    <SyntaxHighlighter language={language}>
-      <code>{children}</code>
-    </SyntaxHighlighter>
+    <Markdown
+      children={mdContainingFencedCodeBlock}
+      options={{
+        overrides: {
+          code: SyntaxHighlightedCode,
+        },
+      }}
+    />
   )
 }
-```
+
+/**
+ * Add the following tags to your page <head> to automatically load hljs and styles:
+
+  <link
+    rel="stylesheet"
+    href="https://unpkg.com/@highlightjs/[email protected]/styles/nord.min.css"
+  />
+
+  * NOTE: for best performance, load individual languages you need instead of all
+          of them. See their docs for more info: https://highlightjs.org/
+
+  <script
+    crossorigin
+    src="https://unpkg.com/@highlightjs/[email protected]/highlight.min.js"
+  ></script>
+ */
+
+function SyntaxHighlightedCode(props) {
+  const ref = (React.useRef < HTMLElement) | (null > null)
+
+  React.useEffect(() => {
+    if (ref.current && props.className?.includes('lang-') && window.hljs) {
+      window.hljs.highlightElement(ref.current)
+
+      // hljs won't reprocess the element unless this attribute is removed
+      ref.current.removeAttribute('data-highlighted')
+    }
+  }, [props.className, props.children])
+
+  return <code {...props} ref={ref} />
+}
+````
 
 ### Getting the smallest possible bundle size
 

diff --git a/docs/index.html b/docs/index.html
@@ -12,6 +12,10 @@
       href="https://unpkg.com/[email protected]/dist/katex.min.css"
       rel="stylesheet"
     />
+    <link
+      rel="stylesheet"
+      href="https://unpkg.com/@highlightjs/[email protected]/styles/nord.min.css"
+    />
     <script
       crossorigin
       src="https://unpkg.com/react@18/umd/react.production.min.js"
@@ -28,6 +32,10 @@
       crossorigin
       src="https://unpkg.com/[email protected]/dist/katex.js"
     ></script>
+    <script
+      crossorigin
+      src="https://unpkg.com/@highlightjs/[email protected]/highlight.min.js"
+    ></script>
   </head>
 
   <body>
@@ -55,6 +63,14 @@
 \mathbb{N} = \{ a \in \mathbb{Z} : a > 0 \}
 ```
 
+Or any other typical language, using [`highlight.js`](https://highlightjs.org/):
+
+```javascript
+function App() {
+  return <div>Hello world!</div>;
+}
+```
+
 You can even include custom React components if you declare them in the [`overrides` option](https://github.com/quantizor/markdown-to-jsx/blob/main/README.md#optionsoverrides---rendering-arbitrary-react-components).
 
 <MyComponent>Isn't that cool?</MyComponent>