# Markdown and MDX Pipelines

## Requirements for Tabula

- Markdown render functions, block and inline
- MDX compile/render functions, block and inline
- preset remark and rehype plugins in each, with option hook to add more
- appropriate element replacement in each
- custom remark/rehype plugins
  - rehype-figure
  - rehype-abbr

## About Remark

- starting with unified, after the .use(remark) step, you can insert remark plugins, such as
  - remark-slug
  - remark-toc
  - remark-github
  - remark-react

## About Rehype

- remark-html is just a wrapper around remark-rehype and rehype-stringify; by using these libs directly, you have an opportunity to run [rehype plugins](https://github.com/rehypejs/awesome-rehype#plugins) in between, such as
  - rehype-document: wrap in a document
  - rehype-format: make pretty
  - rehype-minify: make minimal
  - rehype-react
  - rehype-highlight

## About MDX Compilation

Places to look for patterns
- https://github.com/gatsbyjs/gatsby/blob/master/packages/gatsby-plugin-mdx/mdx-renderer.js

Tips picked up
- babel transform
  - look at `@mdx-js/runtime` and `@mdx-js/react` packages for patterns
    - use `transformAsync`
  - set up babel transform for modern browsers, and newest JSX runtime (React >=17)
    - see https://babeljs.io/repl/#?browsers=defaults%2C%20not%20ie%2011%2C%20not%20ie_mob%2011&build=&builtIns=usage&spec=false&loose=false&code_lz=GYVwdgxgLglg9mABACwKYBt1wBQEpEDeAUIogE6pQhlIA8AJjAG4B8AEhlogO5xnr0AhLQD0jVgG4iAXyJA&debug=false&forceAllTransforms=false&shippedProposals=true&circleciRepo=&evaluate=false&fileSize=false&timeTravel=false&sourceType=module&lineWrap=true&presets=env%2Creact&prettier=false&targets=Node-12&version=7.12.12&externalPlugins=
  - NB: might also need a local babel plugin, to remove certain parts from the compiled JSX

## Other Features

- [ ] consider [MDX Embed](https://gatsby-mdx-embed.netlify.app/?path=/story/getting-stared--page)
- [ ] consider using something other than prismjs for highlighting: [andrewbranch/gatsby-remark-vscode](https://github.com/andrewbranch/gatsby-remark-vscode)
- [ ] create a way to downgrade the headings in the MDX file

## Core Plugins

- images
  - remarkjs/remark-unwrap-images, to remove surrounding paragraph