Installing Docusaurus
This document aims to provide a step-by-step guide along with a practical example of how to get started with the Docusaurus Static Site Generator.
Pre-requisites​
- I am running this on Windows 11
- I have PowerShell
v7.4.5 - I am using VSCode
v1.91.1
Useful Links​
Installing dependencies​
This section outlines the steps needed to set up your environment.
Install Node.js​
Install Node.js v18.0 or above.
# installs fnm (Fast Node Manager)
winget install Schniz.fnm
# download and install Node.js
fnm use --install-if-missing 20
# verifies the right Node.js version is in the environment
node -v # should print `v20.15.0`
# verifies the right NPM version is in the environment
npm -v # should print `10.7.0`
Creating a scaffold project website​
Once the dependencies are installed, create your static website.
npx create-docusaurus@latest digital-reflections classic
More information about the scaffold project structure and the
--classicflag can be found in the Docusaurus documentation:
Select the language that you would like to use for you project.
Navigate to the folder of the docusaurus website.
cd .\digital-reflections
Updating npm Dependencies for Docusaurus Project​
If you get npm warn deprecated messages, update those dependencies to the latest version.
To ensure your Docusaurus project benefits from the latest features, performance improvements, and security patches, follow these steps to update your npm dependencies:
-
Install npm-check-updates Globally:
powershell npm install -g npm-check-updates -
Check for Available Updates: Run the following command to list all dependencies with newer versions available:
powershell ncu -
Update package.json with Latest Versions: Update the package.json file to use the latest versions of the dependencies:
powershell ncu -u -
Install Updated Dependencies: After updating package.json, install the updated dependencies:
powershell npm install -
Test Your Project: Start your Docusaurus site to ensure everything works as expected:
powershell npm start -
Handle Any Issues: If you encounter any issues: - Check the documentation or release notes for the updated packages. - Make necessary changes to your code to accommodate any breaking changes.
By following these steps, you can keep your Docusaurus project dependencies up-to-date while minimizing the risk of breaking your project.
Npm audit​
Well, that was just an hour of my life that I won't get back. Upon installing Docusaurus, you will be greeted by this scary message.
I just installed my new site, haven't even taken the wrapping off, and I already have 15 HIGH vulnerabilities. Well, ain't that a head scratcher.
What is npm audit?​
npm audit is a tool that helps you identify security vulnerabilities in your project's dependencies. It scans your node_modules folder and reports any known vulnerabilities, along with their severity levels.
Investigating the Vulnerabilities​
Ok, well, looks like I need to roll my sleeves up and investigate, after all, no one wants to buy a submarine with holes in the screen door, am I right?"
I've never really used npm before, so it's probably a good opportunity to learn how to manage and resolve vulnerabilities if possible. I do what the command tells me and I run npm audit fix to get an npm audit report. Below is the output.
path-to-regexp 2.0.0 - 3.2.0
Severity: high
path-to-regexp outputs backtracking regular expressions - https://github.com/advisories/GHSA-9wv6-86v2-598j
No fix available
node_modules/serve-handler/node_modules/path-to-regexp
serve-handler *
Depends on vulnerable versions of path-to-regexp
node_modules/serve-handler
@docusaurus/core *
Depends on vulnerable versions of serve-handler
node_modules/@docusaurus/core
@docusaurus/plugin-content-blog *
Depends on vulnerable versions of @docusaurus/core
Depends on vulnerable versions of @docusaurus/plugin-content-docs
Depends on vulnerable versions of @docusaurus/theme-common
node_modules/@docusaurus/plugin-content-blog
@docusaurus/plugin-content-docs *
Depends on vulnerable versions of @docusaurus/core
Depends on vulnerable versions of @docusaurus/theme-common
node_modules/@docusaurus/plugin-content-docs
@docusaurus/theme-common *
Depends on vulnerable versions of @docusaurus/plugin-content-docs
node_modules/@docusaurus/theme-common
@docusaurus/plugin-content-pages *
Depends on vulnerable versions of @docusaurus/core
node_modules/@docusaurus/plugin-content-pages
@docusaurus/plugin-debug *
Depends on vulnerable versions of @docusaurus/core
node_modules/@docusaurus/plugin-debug
@docusaurus/plugin-google-analytics *
Depends on vulnerable versions of @docusaurus/core
node_modules/@docusaurus/plugin-google-analytics
@docusaurus/plugin-google-gtag *
Depends on vulnerable versions of @docusaurus/core
node_modules/@docusaurus/plugin-google-gtag
@docusaurus/plugin-google-tag-manager *
Depends on vulnerable versions of @docusaurus/core
node_modules/@docusaurus/plugin-google-tag-manager
@docusaurus/preset-classic *
Depends on vulnerable versions of @docusaurus/core
Depends on vulnerable versions of @docusaurus/plugin-content-blog
Depends on vulnerable versions of @docusaurus/plugin-content-docs
Depends on vulnerable versions of @docusaurus/plugin-content-pages
Depends on vulnerable versions of @docusaurus/plugin-debug
Depends on vulnerable versions of @docusaurus/plugin-google-analytics
Depends on vulnerable versions of @docusaurus/plugin-google-gtag
Depends on vulnerable versions of @docusaurus/plugin-google-tag-manager
Depends on vulnerable versions of @docusaurus/plugin-sitemap
Depends on vulnerable versions of @docusaurus/theme-classic
Depends on vulnerable versions of @docusaurus/theme-common
Depends on vulnerable versions of @docusaurus/theme-search-algolia
node_modules/@docusaurus/preset-classic
@docusaurus/plugin-sitemap *
Depends on vulnerable versions of @docusaurus/core
node_modules/@docusaurus/plugin-sitemap
@docusaurus/theme-classic *
Depends on vulnerable versions of @docusaurus/core
Depends on vulnerable versions of @docusaurus/plugin-content-blog
Depends on vulnerable versions of @docusaurus/plugin-content-docs
Depends on vulnerable versions of @docusaurus/plugin-content-pages
Depends on vulnerable versions of @docusaurus/theme-common
node_modules/@docusaurus/theme-classic
@docusaurus/theme-search-algolia *
Depends on vulnerable versions of @docusaurus/core
Depends on vulnerable versions of @docusaurus/plugin-content-docs
Depends on vulnerable versions of @docusaurus/theme-common
node_modules/@docusaurus/theme-search-algolia
15 high severity vulnerabilities
Understanding the Vulnerability​
It looks like the 15 vulnerabilities belong to one package called path-to-regexp. However, it says that no fix is available for this vulnerability. I turn to Google and do some searching, and I found this blog post, and I am very grateful to the author as it provided a detailed explanation on what these error messages mean and how important the context of the vulnerabilities is.
It was a really informative read and probably saved me from spending entirely too long at the start of a new personal project diving into topics that are probably not for a beginner. As a beginner, I would agree with the author's sentiments.
Conclusion​
Long story short, this particular vulnerability should not affect our project as this is a static site generated by Docusaurus. To exploit this vulnerability, a malicious actor would require access to the source code and the build process of Docusaurus, where the markdown files are converted to HTML files. Those static HTML files are published to our website, and changing regex at that point won't have any impact on our site because the site serves only static content.
Lets run our first Docusaurus Static Site​
Okay, enough shenanigans, Lets start this puppy up. Run the local web server.
npm run start
Enjoy your new website :D. Now you can visit http://localhost:3000 in your web browser to see your Docusaurus site in action. Congratulations on setting up your new Docusaurus site!
