DEV Community

Cover image for Site Builder: from one Markdown file to a deployed site in three commands
mrduguo
mrduguo

Posted on

Site Builder: from one Markdown file to a deployed site in three commands

#docusaurus #dac #mdx

If you have ever tried to spin up a Docusaurus site, you know the routine: scaffold the project, install dependencies, write a config, pick a theme, get the navbar right, and only then can you start writing the actual docs.

Dinghy collapses all of that setup into a single command.

Minimal setup 

mkdir -p src/pages
echo "# Welcome" > src/pages/INDEX.mdx
dinghy site start
Enter fullscreen mode Exit fullscreen mode

That is all the setup there is. One folder, one file, one command, and you have live preview running at http://localhost:3000 with hot reload.

There is no package.json, no node_modules, and no Docusaurus config to write. The Dinghy engine ships a fully configured Docusaurus inside its Docker image and points it at your src/ folder.

What you get

The defaults are designed to work without any further setup:

  • src/pages/: standalone MDX pages (the homepage lives at INDEX.mdx).
  • src/docs/: docs section with sidebar navigation generated from the directory tree.
  • src/blog/ or blog/: blog section with date-prefixed posts. Both the root-level blog/ and src/blog/ are picked up; this site uses the root-level blog/.
  • src/css/custom.css: custom theme overrides, loaded automatically.
  • static/: assets, served as-is.

If a folder is present, it is used. If it is not, Dinghy leaves it alone.

Customizing

When the defaults are not enough, drop a docusaurus.config.yml in the site root. Dinghy intercepts a set of top-level keys such as docs, blog, theme, themeConfig, navbar, footer, and sidebars, and merges everything else straight into the underlying Docusaurus config:

title: My Project
navbar:
  title: My Project
  items:
    - label: Guides
      to: /guides/getting-started
      position: left
Enter fullscreen mode Exit fullscreen mode

Set logo: false to drop the default logo. Set footer: false to drop the footer entirely. Anything Docusaurus supports, you can reach.

Deploying to S3

S3 is a built-in deploy target. Add it to your config:

deploy:
  s3Url: s3://my-bucket/path
  s3Region: us-east-1
Enter fullscreen mode Exit fullscreen mode

Then:

dinghy site deploy
Enter fullscreen mode Exit fullscreen mode

The deploy command is not a thin wrapper. It does the things you would otherwise do by hand:

  • Removes .html extensions so URLs look clean.
  • Gzip-compresses text files (HTML, JS, CSS, SVG, XML, TXT, JSON) before upload.
  • Sets cache-control headers that match the file type: public,max-age=2592000 (about 30 days) for content-hashed assets, and public,max-age=3600,must-revalidate (one hour) for mutable files.

If you have ever shipped a static site and found out months later that your HTML was being served with a one-year cache header, this is the kind of detail the deploy step handles for you.

The pattern

Dinghy's builders work the same way every time: sensible defaults that cover the common case, overrides for the rest, and a single command (start, build, deploy) for each step of the lifecycle.

Top comments (0)