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
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
import only work with images, not svgs.
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.
Parse the markdown syntax into tag
Copy everything in static directory to
Point sources in markdown files to the
staticfolder now inside the
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
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.