Document Site Generator

There are a lot of tools already to transform markdown content into static html, this by itself is not interesting. With access to runtime javascript, we can use all of the browser tools and render some pretty neat things.

Like rendering 3d Objects

import cube from './companion_cube.stl';

<Stl url={cube}/>

What does this do?

A command line interface to read markdown text, and produce the static assets necessary to render the content in a browser.


graph LR

md[Your Markdown Text]
js[Runtime Javascript]
static[Static HTML content]

md --> js 
md --> static

This is mostly done by webpack and existing tooling. Once the markdown has been separated into these two base components, we build a html file that gets sent to users. This is a fairly basic template:

<html>
<body>
<div id="root">
    {{{Static HTML content}}}
</div>
<script>
    const mdx = main.mdx;
    {{{Runtime Javascript}}}
    main.Entrypoint(MDXContent, "root")
</script>
</body>
</html>

This webpack config is shipped as a standalone CLI tool, distributed by npm.

npx document-site-builder -h

to run a local dev server to preview md files from your docs folder

npx document-site-builder dev docs

to build static content suitable for hosting on any static content deliver service.

npx document-site-builder build docs