Documentation is an integral part of the software development lifecycle. Without documentation, a project can't reach its maximum potential but writing and maintaining documentation is very tough task , Docusaurus comes into the picture. Docusaurus helps to create and maintain static documentation websites with support for blogs, versioning, and custom pages. Docusaurus generates a static React.js website using MDX for docs and blogs. MDX is a markdown variant that allows the use of JSX inside markdown. This tutorial will use version 2 of Docusaurus. Docsaurus supports both the Dark and Light theme by default.
Node.js and NPM are required to install and use Docusaurus. Node.js is available on the official website. @docusaurus/init is the easiest method to scaffold a Docusaurus website. You can execute init command in any directory.
npx @docusaurus/init@next init my-website classic
This command will create a my-website named website in the current directory using the classic template. Docusaurus provides different templates. Start the project by running npm start in the project directory. You can now see project running on http://localhost:3000
Scaffold project has few scripts already present in package.json file. These scripts are used to manage the Docusaurus project. We will use two of these scripts:
npm start it is used to start dev server on localhost:3000. It detects changes to the project and reloads.
npm run build is used to create an optimized production build for the project. It will create a build folder that will have a compiled project.
src/pages/index.js is the homepage for the website. It exports a React.js component which is rendered between navbar and footer. You can create your component in index.js. preset-classic also includes a CSS framework built by Docusaurus team called Infima.
import React from "react";
import clsx from "clsx";
import Layout from "@theme/Layout"; // it is a sudo import, theme will be injected at build time
import Link from "@docusaurus/Link"; // docusaurus exports react-router
import useDocusaurusContext from "@docusaurus/useDocusaurusContext"; // get metadata about page
import useBaseUrl from "@docusaurus/useBaseUrl"; // gives link after concating website url and path
import styles from "./styles.module.css";
const features = [
{
title: <>Updated Regularly</>,
imageUrl: "img/updated.svg", // path to image with respect to staic dir
description: (
<>
Scrapping links and scripts are updated on daily bases. Scripts are well
tested and robust.
</>
),
},
{
title: <>Lighting Fast</>,
imageUrl: "img/fast.svg", // path to image with respect to staic dir
description: (
<>Lighting fast, built with speed in mind support caching by default.</>
),
},
{
title: <>Automated scripts</>,
imageUrl: "img/automated.svg", // path to image with respect to staic dir
description: (
<>
No manual work required just pass imdbId and get movies
and tvs shows scrapped.
</>
),
},
];
// Feature component
function Feature({ imageUrl, title, description }) {
Navbar is a part of preset-classic, it is not the part of @docusaurus/core. Configuration to the theme is passed as themeConfig object in docusaurus.config.js. navbar key in themeConfig holds the config for the navbar.
Adding logo
themeConfig: {
navbar: {
title: "Imdb Scrapper", // title
logo: {
alt: "My Site Logo",
src: "img/logo.svg", // path with respect to static dir
},
}
}
We can add a logo by providing src and alt. If the logo is not provided, it wouldn't be displayed.
Adding links
Docusaurus supports hyperlinks to other pages on the same domain by providing a path or to another domain by providing a URL.
navbar: {
title: "Imdb Scrapper",
links: [
{
to: "docs/", // path to page
activeBasePath: "docs", // active it url matches regex
label: "Docs",
position: "left",
},
{ to: "blog", label: "Blog", position: "right" },
{
href: "https://github.com/anshulrgoyal/imdb-scrapper", // to other domain
label: "GitHub",
position: "right",
},
],
If to is passed to links, then react-router will be used, where as, if href is passed, anchor tag is used.
All the documentation is added to the docs folder. We can change it in the docusaurus.config.js file. We will create api.md file in the docs folder. Docusaurus will render it automatically and create a table of content for .md file.
---
id: api
title: API
---
# My doc
id is used to reference this document in Docusaurus and /docs/{id} will be path to access documentation. title will be used as the page title for documentation and sidebar_label will be used as the label in the sidebar. Now we need to add our api to a sidebar. We edit sidebars.js to create a new entry.
The sidebar is created recursively i.e. it can have any level of nesting. For example, I can create another category in the IMDB Scrapper category called Examples with many items.
docs/
βββ api.md
βββ examples
βββ actors.md
βββ award.md
βββ image.md
βββ scraping.md
βββ search.md
βββ trending.md
βββ tv.md
This is example project structure, we can also create nested documents. For example, actors.md will have /docs/examples/actors as URL path and id to refer will be examples/actors.
module.exports = {
sidebar: {
"Imdb Scrapper": ["api",{
Examples:[ // nested sidebar with example as sub catogery
"examples/actor", // items
"examples/award",
"examples/image",
"examples/tv",
"examples/trending",
"examples/scraping",
"examples/search"
]
}],
},
};
If you try to access /docs/ it will give "404 not found". To solve this, we need to update the setting of preset-classic to use /docs/api as our home doc or entry point to docs.
presets: [
[
"@docusaurus/preset-classic",
{
docs: {
// It is recommended to set document id as docs home page (`docs/` path).
During development, there are many changes in every version. If your product supports different versions, it is difficult to maintain documentation for each version. Docusaurus supports versioning. Let's add a script in package.json for versioning.
"version": "docusaurus doc:version"
Now we can use npm run version <version> command for creating command.
.
βββ babel.config.js
βββ blog
β βββ 2019-05-28-hola.md
β βββ 2019-05-29-hello-world.md
β βββ 2019-05-30-welcome.md
βββ docs
β βββ api.md
β βββ examples
β βββ actors.md
β βββ award.md
β βββ image.md
β βββ scraping.md
β βββ search.md
β βββ trending.md
β βββ tv.md
βββ docusaurus.config.js
βββ package.json
βββ README.md
βββ sidebars.js
βββ src
β βββ css
β β βββ custom.css
β βββ pages
β βββ index.js
β βββ styles.module.css
βββ static
β βββ img
β βββ automated.svg
β βββ fast.svg
β βββ updated.svg
βββ versioned_docs
β βββ version-1.1.0
β βββ api.md
β βββ examples
β βββ actors.md
β βββ award.md
β βββ image.md
β βββ scraping.md
β βββ search.md
β βββ trending.md
β βββ tv.md
βββ versioned_sidebars
β βββ version-1.1.0-sidebars.json
βββ versions.json
This command will copy all the documents from docs/ to versioned_docs. sidebars.js is copied to versioned_sidebars. Now there are three versions:
next : all the documents in /doc folder. This version is available as docs/next/{id}.
latest(1.1.0) : all the documents in versioned_docs/version-1.1.0 folder are versioned latest. This version is available as docs/{id}
old documents: all the documents which are in any other folder will be versioned old. This version is available as /docs/{version}/{id}
versions.json is created which holds all the versions for documentation.
[
"1.1.0"
]
Docusaurus will be creating a snapshot of documentation for each version and saving it. Now letβs add a link to each version in the navbar for easy access. We can import versions.json in docusaurus.config.js and use it.
const versions = require("./versions.json");
We can provide items to convert Link to a dropdown.
Docusaurus has a nice feature that informs the user that the documentation belongs to an older version. If we create a new version of 1.1.1, we can see it in action.
It automatically adds a banner notifying the user that documentation is old. And the new version is automatically added to the navbar.
Now if we check versioned_docs we can see both of the versions there.
.
βββ babel.config.js
βββ blog
β βββ 2019-05-28-hola.md
β βββ 2019-05-29-hello-world.md
β βββ 2019-05-30-welcome.md
βββ docs // next or upcoming version
β βββ api.md
β βββ examples
β βββ actors.md
β βββ award.md
β βββ image.md
β βββ scraping.md
β βββ search.md
β βββ trending.md
β βββ tv.md
βββ docusaurus.config.js
βββ package.json
βββ README.md
βββ sidebars.js // next or upcoming version
βββ src
β βββ css
β β βββ custom.css
β βββ pages
β βββ index.js
β βββ styles.module.css
βββ static
β βββ img
β βββ automated.svg
β βββ fast.svg
β βββ updated.svg
βββ versioned_docs
β βββ version-1.1.0 // old version
β β βββ api.md
β β βββ examples
β β βββ actors.md
β β βββ award.md
β β βββ image.md
β β βββ scraping.md
β β βββ search.md
β β βββ trending.md
β β βββ tv.md
β βββ version-1.1.1 // latest version
β βββ api.md
β βββ examples
β βββ actors.md
β βββ award.md
β βββ image.md
β βββ scraping.md
β βββ search.md
β βββ trending.md
β βββ tv.md
βββ versioned_sidebars
β βββ version-1.1.0-sidebars.json // old version
β βββ version-1.1.1-sidebars.json // latest version
Docusaurus offers the option to create custom pages, by creating files in src/pages. If a file exports a React component, it will be rendered between navbar and footer. If you create a new page src/pages/team then it will be available at /team.
Docusaurus allows us to create and manage blogs. You can create blogs by adding a blog as a markdown file in the blog folder. The file name should follow the pattern {date}-{name}.md.
// file: ./blog/2020-07-06-my-blog
---
id: intro
title: Introducing Docusaurus // title for blog
author: Anshul Goyal // author name
tags: [docusaurus,tutorial] // tags for blog
---
# My blog
<!--truncate-->
<!--truncate--> is used to mark the summary of the blog. The content between --- and <!--truncate--> will be used as a summary for the blog.
Deploying the Docusaurus website is simple. Just npm run build and serve the build directory. For example, letβs deploy it to Netlify. Just connect your repo to Netlify and update settings.
We have gone through some of basics of Docusaurus. Docusaurus is great for creating a Documentation website. It is very customizable and supports a wide array of integration. Docusaurus supports different themes, search features, image optimization. We learned how to create basic documentation, manage different versions, creating custom pages, customizing the default website, and creating blogs.