Andrew's Engineer Blog
[OSD600 Series] Lab 06 - Adding static files to SSG

Photo by Jon Tyson on Unsplash

[OSD600 Series] Lab 06 - Adding static files to SSG

Andrew Nguyen's photo
Andrew Nguyen
·

2 min read

Table of contents

Docusaurus

Docusaurus out-of-the-box blogs and docs are simply amazing. Markdown supports MDX with elegant built-in components for common cases like Tabs, Admonitions, etc. It is also highly customizable via docusaurus.config.js.

Setting up a Docusaurus is as fast as running one script. Everything is ready to deploy, just need to replace some name and links.

npm init docusaurus@latest my-website classic

Docusaurus also has an exhaustive guide for deployment. However, resolving static assets was a bit tricky. Static assets were automatically rewrited correctly in markdown files. In JSX, with the sample template homepage, the documentation said there were three ways to import assets, but the only usable option is useBaseUrl. The require and import only work with images, not svgs.

Add static images to paper

As I was struggling a bit with Docusaurus static assets, I decided to give it a try.

It was pretty straightforward from what I had imagined.

  1. Parse the markdown syntax into tag img.

  2. Copy everything in static directory to dist folder.

  3. Point sources in markdown files to the static folder now inside the dist folder.

The first and second steps are pure coding so it wasn't complicated. The last step was quite confusing. At first, I had planned to work with relative path: going backwards from files until reach the root of dist folder, then go into /static. That was obviously not simple, as files could be nested multi-level down. So, I decided to give absolute path a try, and it just magically resolved on vercel (not working locally) by using href="/static/1.jpg".

At the moment, the project only supports images. Moving forward, it should read assets extensions and generates approriate html tags. I'm also finding a way to test this feature locally.

Additional Resources

osd600seneca-college