Skip to main content

Docusaurus Introduction

Docusaurus is a static-site generator. It builds a single-page application with fast client-side navigation, leveraging the full power of React to make your site interactive. It provides out-of-the-box documentation features but can be used to create any kind of site (personal website, product, blog, marketing landing pages, etc).

Scaffold your website

The easiest way to install Docusaurus is to use the command line tool that helps you scaffold a skeleton Docusaurus website. You can run this command anywhere in a new empty repository or within an existing repository, it will create a new directory containing the scaffolded files:

sudo npm install -g create-docusaurus@latest
create-docusaurus my-docs classic

The classic template contains @docusaurus/preset-classic which includes standard documentation, a blog, custom pages, and a CSS framework (with dark mode support).

To run the application:

cd my-docs
npm start

Inside that directory, you can run several commands:

  • npm start Starts the development server.

  • npm run build Bundles your website into static files for production.

  • npm run serve Serves the built website locally.

  • npm deploy Publishes the website to GitHub pages.

Plugins

Redirects

This plugin will write additional HTML pages to your static site that redirect the user to your existing Docusaurus pages with JavaScript.

plugin-client-redirects

npm install -f @docusaurus/plugin-client-redirects

Plugin Options

docusaurus.config.js

module.exports = {
plugins: [
[
'@docusaurus/plugin-client-redirects',
{
fromExtensions: ['html', 'htm'], // /myPage.html -> /myPage
toExtensions: ['exe', 'zip'], // /myAsset -> /myAsset.zip (if latter exists)
redirects: [
// /docs/oldDoc -> /docs/newDoc
{
to: '/docs/newDoc',
from: '/docs/oldDoc',
},
// Redirect from multiple old paths to the new path
{
to: '/docs/newDoc2',
from: ['/docs/oldDocFrom2019', '/docs/legacyDocFrom2016'],
},
],
createRedirects(existingPath) {
if (existingPath.includes('/community')) {
// Redirect from /docs/team/X to /community/X and /docs/support/X to /community/X
return [
existingPath.replace('/community', '/docs/team'),
existingPath.replace('/community', '/docs/support'),
];
}
return undefined; // Return a falsy value: no redirect created
},
},
],
],
};

Google GTag

plugin-google-gtag

npm install -f @docusaurus/plugin-google-gtag

Get your Tracking ID

The Google tag (gtag.js) is a JavaScript tagging framework and API that allows you to send event data to Google Analytics, Google Ads, and Google Marketing Platform.

Plugin Options

module.exports = {
plugins: [
[
'@docusaurus/plugin-google-gtag',
{
trackingID: 'G-226F0LR9KE',
anonymizeIP: true,
},
],
],
};

Ideal Image

Docusaurus Plugin to generate an almost ideal image (responsive, lazy-loading, and low quality placeholder).

plugin-ideal-image

npm install -f @docusaurus/plugin-ideal-image 

Plugin Options

docusaurus.config.js

module.exports = {
plugins: [
[
'@docusaurus/plugin-ideal-image',
{
quality: 70,
max: 1030, // max resized image's size.
min: 640, // min resized image's size. if original is lower, use that size.
steps: 2, // the max number of images generated between min and max (inclusive)
disableInDev: false,
},
],
],
};

Progressive Web App

plugin-pwa

npm install -f @docusaurus/plugin-pwa

Manifest

Create a PWA manifest at ./static/manifest.json

{
"name": "Mike Polinowski :: Dev Notebook",
"short_name": "DevNotes",
"description": "Research notes for web development, devOps, the Internet-of-Things and machine learning.",
"theme_color": "#25c2a0",
"background_color": "#212121",
"display": "standalone",
"scope": "/",
"start_url": "/Search?source=pwa",
"related_applications": [
{
"platform": "webapp",
"url": "https://mpolinowski.github.io/manifest.json"
}
],
"shortcuts": [
{
"name": "Notebook",
"short_name": "DevNotes",
"description": "Research notes for web development, devOps, the Internet-of-Things and machine learning.",
"url": "/docs?source=pwa",
"icons": [{ "src": "/img/icons/icon-192x192.png", "sizes": "192x192" }]
},
{
"name": "Blog Posts",
"short_name": "Blog",
"description": "Blog post for web development, devOps, the Internet-of-Things and machine learning.",
"url": "/blog?source=pwa",
"icons": [{ "src": "/img/icons/icon-192x192.png", "sizes": "192x192" }]
}
],
"icons": [
{
"src": "/img/icons/icon-72x72.png",
"sizes": "72x72",
"type": "image/png"
},
{
"src": "/img/icons/icon-96x96.png",
"sizes": "96x96",
"type": "image/png"
},
{
"src": "/img/icons/icon-128x128.png",
"sizes": "128x128",
"type": "image/png"
},
{
"src": "/img/icons/icon-144x144.png",
"sizes": "144x144",
"type": "image/png"
},
{
"src": "/img/icons/icon-152x152.png",
"sizes": "152x152",
"type": "image/png"
},
{
"src": "/img/icons/icon-192x192.png",
"sizes": "192x192",
"type": "image/png"
},
{
"src": "/img/icons/icon-384x384.png",
"sizes": "384x384",
"type": "image/png"
},
{
"src": "/img/icons/icon-512x512.png",
"sizes": "512x512",
"type": "image/png"
}
],
"screenshots": [
{
"src": "/img/worldmap.png",
"type": "image/png",
"sizes": "1300x867"
},
{
"src": "/img/worldmap.jpg",
"type": "image/jpg",
"sizes": "540x360"
}
]
}

Plugin Options

docusaurus.config.js

module.exports = {
plugins: [
[
'@docusaurus/plugin-pwa',
{
pwaHead: [
{
tagName: 'link',
rel: 'icon',
href: '/img/angular_momentum.png',
},
{
tagName: 'link',
rel: 'manifest',
href: '/manifest.json',
},
{
tagName: 'meta',
name: 'theme-color',
content: 'rgb(37,194,160)',
},
{
tagName: 'meta',
name: 'apple-mobile-web-app-capable',
content: 'yes',
},
{
tagName: 'meta',
name: 'apple-mobile-web-app-status-bar-style',
content: '#000',
},
{
tagName: 'link',
rel: 'apple-touch-icon',
href: '/img/angular_momentum.png',
},
{
tagName: 'link',
rel: 'mask-icon',
href: '/img/angular_momentum.png',
color: 'rgb(33,33,33)',
},
{
tagName: 'meta',
name: 'msapplication-TileImage',
content: '/img/angular_momentum.png',
},
{
tagName: 'meta',
name: 'msapplication-TileColor',
content: '#000',
},
],
},
],
],
};

Sitemap

plugin-sitemap

npm install -f @docusaurus/plugin-sitemap

Plugin Options

docusaurus.config.js

module.exports = {
plugins: [
[
'@docusaurus/plugin-sitemap',
{
changefreq: 'weekly',
priority: 0.5,
ignorePatterns: ['/tags/**'],
filename: 'sitemap.xml',
},
],
],
};