Esbuild as a static site generator for MDX

11ty and Github pages

The last post summarized how the Contentful-Gatsby-Netlify trio could be simplified by using Github pages and 11ty.

Jacco Meijer
|
Mar 18, 2024

11ty and Github pages

Simplifying the Contentful-Gatsby-Netlfy trio.

This post continues the quest for simplicity from there.

The proposition is, if only Esbuild can be used to generate static HTML, this would be even simpler than using 11ty.

Javascript bundler landscape

Nobody really liked solving the Webpack and Babel configuration puzzles. Occasionally they blocked the actual project.

The bundler landscape matured with the rise of Parcel and Rollup and in 2020 Evan Wallace, one of the co-founders of Figma, released Esbuild.

Written in Go and 100 times faster than Webpack it is a welcome addition to the Javascript bundler landscape

Jacco Meijer
|
Mar 11, 2022

Javascript history

In 1986 David Ungar and Randall B. Smith developed Self at Xerox PARC. Inspired by Java, Scheme and Self Brendan Eich created Javascript in 1995.

Jacco Meijer
|
Mar 10, 2022

On Javascript transpilers, bundlers and modules

There's Javascript transpilers, modules, bundles and bundlers. This is a brief overview of all of these.

Esbuild

Esbuild supports TypeScript, JSX and tree-shaking. Besides that, Esbuild contains a live reloading webserver that triggers a full rebuild on a browser refresh.

Esbuild generates Javascript bundles but a static site generator generates HTML. The extensible nature of Esbuild allows for a simple plugin to take care of transforming the final bundle to HTML.

MDX

Setting up Esbuild and @mdx-js/esbuild is straightforward and clearly explained on mdxjs.com.

This Esbuild/MDX setup makes Esbuild transform MDX to JSX/Javascript bundles. Additional functionality can be added by using plugins from the rich MDX ecosystem. The example below shows how to add support for:

Front Matter (as described in previous post)
Code highlighting
GitHub Flavored Markdown Spec

import mdx from '@mdx-js/esbuild'
import rehypeHighlight from 'rehype-highlight'
import remarkFrontmatter from 'remark-frontmatter'
import remarkMdxFrontmatter from 'remark-mdx-frontmatter'
import remarkGfm from 'remark-gfm'

const plugins = [
  mdx({
    jsxImportSource: 'preact',
    remarkPlugins: [
      [remarkGfm],
      [remarkFrontmatter, ['yaml', 'toml']],
      [remarkMdxFrontmatter, { name: 'frontmatter' }],
    ],
    rehypePlugins: [rehypeHighlight],
  }),
]

Live reloading webserver

Setting up the Esbuild webserver is explained here. For live reloading a line of Javascript must be added to the page template.

Using Javascript the Esbuild webserver is started like this:

const ctx = await esbuild.context({
  entryPoints: ['index.js'],
  format: 'esm',
  outdir: 'build',
  plugins: [mdx({/** options **/})]
})

await ctx.watch()
const { port } = await ctx.serve({ servedir: 'build' })

console.log(`Live reload server started at http://localhost:${port}\n`)

Conclusion

Esbuild is a fantastic tool. It is fast, capable and extendable. With 'something' that renders JSX bundles to static HTML Esbuild could act as a simple static site generator.