Using Markdoc with React

Markdoc supports rendering Markdoc syntax with React out-of-the-box.

To get started with React, check out this example repo for how to use Markdoc with create-react-app and express.

Follow these steps to build a Markdoc app with create-react-app and express.

1. Follow the create-react-app getting started steps to create your initial app

2. Set up a Markdoc schema

   schema/ ├── Callout.markdoc.js └── heading.markdoc.js 

   // [schema/Callout.markdoc.js](https://github.com/markdoc/docs/blob/dcba1a62be92097e3fd50c21e05fd6d2ea709312/examples/react-nodejs/schema/Callout.markdoc.js#L1-L18) module.exports = { render: 'Callout', children: ['paragraph', 'tag', 'list'], attributes: { type: { type: String, default: 'note', matches: ['check', 'error', 'note', 'warning'] } } }; 

   // [schema/heading.markdoc.js](https://github.com/markdoc/docs/blob/dcba1a62be92097e3fd50c21e05fd6d2ea709312/examples/react-nodejs/schema/heading.markdoc.js#L1-L22) const { nodes } = require('@markdoc/markdoc'); function generateID(children, attributes) { if (attributes.id && typeof attributes.id === 'string') { return attributes.id; } return children .filter((child) => typeof child === 'string') .join(' ') .replace(/[?]/g, '') .replace(/\s+/g, '-') .toLowerCase(); } module.exports = { ...nodes.heading, transform(node, config) { const base = nodes.heading.transform(node, config); base.attributes.id = generateID(base.children, base.attributes); return base; } }; 

3. Parse your Markdoc documents on the server

   // [...](https://github.com/markdoc/docs/blob/main/examples/react-nodejs/createContentManifest.js#L13) const rawText = fs.readFileSync(file, 'utf-8'); const ast = Markdoc.parse(rawText); 

4. Call Markdoc.transform on the server

   // [server.js](https://github.com/markdoc/docs/blob/main/examples/react-nodejs/server.js) const express = require('express'); const app = express(); const callout = require('./schema/callout.markdoc'); const heading = require('./schema/heading.markdoc'); // [...](https://github.com/markdoc/docs/blob/dcba1a62be92097e3fd50c21e05fd6d2ea709312/examples/react-nodejs/server.js#L8-L14) app.get('/markdoc', (req, res) => { const ast = contentManifest[req.query.path]; const config = { tags: { callout }, nodes: { heading }, variables: {} }; const content = Markdoc.transform(ast, config); return res.json(content); }); app.listen(4242, () => { console.log(`Example app listening on port ${4242}`); }); 

5. Call Markdoc.renderers.react on the client

   // src/App.js import React from 'react'; import Markdoc from '@markdoc/markdoc'; import { Callout } from './Callout'; export default function App() { const [content, setContent] = React.useState(null); React.useEffect(() => { (async () => { const response = await fetch( `/markdoc?` + new URLSearchParams({ path: window.location.pathname }), { headers: { Accept: 'application/json' } } ); if (response.status === 404) { setContent('404'); return; } const content = await response.json(); setContent(content); })(); }, []); if (content === '404') { return <p>Page not found.</p>; } if (!content) { return <p>Loading...</p>; } const components = { Callout }; return Markdoc.renderers.react(content, React, { components }); } 

6. Start up the client and server

   npm run start:client 

   and

   npm run start:server 

Or, clone this starter repo and follow the directions in the README.