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 startStarts the development server. -
npm run buildBundles your website into static files for production. -
npm run serveServes the built website locally. -
npm deployPublishes 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.
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
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).
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
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
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',
},
],
],
};