Best example of mdxjs + nextjs?

kanishka · December 10, 2020, 7:19pm

Is rescriptlang.org the best example of mdxjs usage? Are there any other examples?

ryyppy · December 11, 2020, 7:58am

Can you be more specific on what you are trying to solve / what you are interested in? Do you mean basic Next / MDX usage, or how to write bindings for mdx components in ReScript?

kanishka · December 11, 2020, 2:42pm

I understand the basic features of mdxjs. I’m just curious to see different examples of people using it to build out complex features - auto generating table of contents/nav bar, other things that I might not have thought of.

Right now, I’m planning on using mdxjs for controlling styling of classic markdown files. I will start coming up with more ideas for using it soon after that.

kanishka · December 22, 2020, 4:08am

For anybody who copies rescriptlang.org mdx bindings in the future, the common/mdx.js bindings add some features particular to rescriptlang.org such “target” for “a” tags as well as more advanced features like “id” generated by “remark-slug”, “MdxChildren” type, “getMdxType” and “getMdxClassName” utilities, which won’t be necessary when first using mdxjs. Once you remove those, the bindings are quick to get going with.

I moved towards using next-mdx-remote within getStaticProps for now, to be able to easily access frontmatter without writing custom mdx bindings.

kanishka · December 25, 2020, 2:34am

From nextjs blog, this is clever:

// pages/posts/markdown-with-next.mdx

import Layout from '../components/Layout'

export const meta = {
  title: 'Markdown/MDX with Next.js',
  author: 'Lee Robinson'
}

I **love** using [Next.js](https://nextjs.org/)

export default ({ children }) => <Layout meta={meta}>{children}</Layout>

ryyppy · December 25, 2020, 8:34am

this one in particular turned out to be impractical for us. One of the big advantages of Markdown + frontmatter for meta data is that it is nicely displayed in github as well (github markdown displays frontmatter as a table)

kanishka · December 27, 2020, 6:09am

Ideally, I would like a layout to read the mdx file once, and then run the markdown through remark-slug, then TOC generation and let me feed that into a sidebar component to produce left nav bar, as well as run the same markdown through mdx rendering to place in a main content area. I might also generate reading time later and last updated stamp later.

Using the mdx loader feels too limiting for this.

Using next-mdx-remote feels inefficient, as I will have to duplicate some processing when adding TOC generation.

Using unified/remark/rehype directly for everything feels too low level. Also, unified is lightly documented currently.

This strikes me as very common task, so I am surprised there isn’t thorough documentation with unified/remark to do these. I see related plugins and will explore them soon

ryyppy · December 27, 2020, 7:24am

we essentially wrote our own mdx loader to e.g. parse the frontmatter and for creating the gh edit link, that is used on each page in the language manual:

github.com

reason-association/rescript-lang.org/blob/master/plugins/mdx-loader.js

const { getOptions } = require("loader-utils");
const mdx = require("@mdx-js/mdx");
const matter = require("gray-matter");
const stringifyObject = require("stringify-object");
const path = require("path");

const DEFAULT_RENDERER = `
import React from 'react'
import { mdx } from '@mdx-js/react'
`;


// This is used to inject some "Edit" link reference
// so we can point our users to the correct resource
// on github for editing
let PROJECT_DIR = path.join(__dirname, "..")
const EDIT_PREFIX = "https://github.com/reason-association/rescript-lang.org/blob/master/"
function createEditHref(filepath) {
  let rel = path.relative(PROJECT_DIR, filepath);
  return EDIT_PREFIX + rel;

This file has been truncated. show original

To me, the whole webpack loader apis feel like a huge hack, and i try not to overuse them tbh.

kanishka · January 2, 2021, 1:49am

https://github.com/rehypejs/rehype-react - this looks promising as an alternative to mdxjs, for simple markdown files

kanishka · April 21, 2021, 3:32am

After using the api and some plugins, it seems possible to express basic processing without that much effort. It would be nice if there are higher level traversals than unist-util-visit some day. I ran into one clash between es6 output, the unist-util-visit module format, and nextjs/webpack, which I haven’t solved yet.

The docusaurus v2 implementation helps supplement the docs in unifiedjs, when trying to figure out how to actually use the api.

Also, using node child-process has been working okay so far.

kanishka · April 24, 2021, 4:39pm

Here is a snippet for basic TOC generation which is exposed as a remark plugin: https://framagit.org/-/snippets/6208

Please ignore the code style and rough edges. I will update this thread with a link to a more polished snippet later. Hope this helps someone. The snippet relies on some bindings and other bits. If someone actually wants to use this, I can provide all the details if requested.

Also, I realized that I was looking for TOC plugins at the wrong abstraction level. rehype-toc is closer to what I wanted, but I don’t think its flexible enough for a robust mobile implementation of a TOC.