Docusaurus is a powerful static site generator, that allows you to build your documentation website in minutes. This guide will walk you through how to create your first Docusaurus website using the latest Docusaurus version, let’s get started.
Prerequisites
Before we begin, make sure you have the following installed:
Node.js and npm: Download and install Node.js.
Terminal: Use the terminal of your choice.
Visual Studio Code editor: Install Visual Studio Code or your preferred code editor.
Create your Docusaurus Doc Website
Follow these steps to create your first Docusaurus website:
Open the terminal, and run the below command to create the basic scaffold using Docusaurus:
npx create-docusaurus@latest my-docs-website classicIn the above command, we are using the `@latest` version of Docusaurus, and asks to install a `create-docusaurus@3.1.0` where 3.0.1 is the latest Docusaurus version. Type `y` to proceed. The command creates a parent directory with the name `my-docs-website` and uses `classic` theme provided by Docusaurus to generate the basic website.
You’ll see a similar output as below:
npx create-docusaurus@latest my-docs-website classic
Need to install the following packages:
create-docusaurus@3.1.0
Ok to proceed? (y) y
npm WARN deprecated stable@0.1.8: Modern JS already guarantees Array#sort() is a stable sort, so this library is deprecated. See the
compatibility table on MDN: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/
sort#browser_compatibility
[INFO] Creating new Docusaurus project...
[INFO] Installing dependencies with npm...
npm WARN deprecated stable@0.1.8: Modern JS already guarantees Array#sort() is a stable sort, so this library is deprecated. See the
compatibility table on MDN: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/
sort#browser_compatibility
added 1210 packages, and audited 1211 packages in 2m
293 packages are looking for funding
run `npm fund` for details
found 0 vulnerabilities
[SUCCESS] Created my-docs-website.Go to the project directory by using a `cd` command:
cd my-docs-websiteOpen the project in Visual Studio code (VS Code) editor either by opening the folder in VS code editor or typing `code .` in the terminal in the project directory my-docs-website.
You’ll see a folder structure as below:
blog - a directory that hosts all your blog posts
docs - a directory that hosts all your documentation
src - a directory that hosts components, pages and css of your Docusaurus website
static - a directory that hosts all static assets like images, files and more
docusaurus.config.js - the configuration file used by Docusaurus. It is the heart of your website. It holds essential settings and customisation options of your website.
sidebar.js - the configuration file used by Docusaurus to create the documentation navigation hierarchy.
Execute the below command to run the website. You can run this command in your projects parent directory, or in the terminal within VS code editor:
npm startThe above command, starts the development server and you’ll be able to access the Docusaurus website on localhost:3000.
🎉 Congratulations! The Docusaurus website with basic configuration is up and running. You’ll see the website with default configuration as below:
Configure Docusaurus for Docs-only mode
Now, that you’ve the Docusaurus website running locally with the default configuration, let’s modify the configuration to host a docs-only website. What this means is that when you access your website, you’ll not see a landing page, but will be taken straight to your documentation. Follow the steps below to modify the configuration:
Open the `docusaurus.config.js`, scroll down to `presets` which looks like below:
presets: [
[
'classic',
/** @type {import('@docusaurus/preset-classic').Options} */
({
docs: {
sidebarPath: './sidebars.js',
// Please change this to your repo.
// Remove this to remove the "edit this page" links.
editUrl:
'https://github.com/facebook/docusaurus/tree/main/packages/create-docusaurus/templates/shared/',
},
blog: {
showReadingTime: true,
// Please change this to your repo.
// Remove this to remove the "edit this page" links.
editUrl:
'https://github.com/facebook/docusaurus/tree/main/packages/create-docusaurus/templates/shared/',
},
theme: {
customCss: './src/css/custom.css',
},
}),
],
],Remove the content of attribute blog and set it to `false`, and add a `routeBasePath` to the docs attribute to point to root. The configuration should like:
presets: [
[
'classic',
/** @type {import('@docusaurus/preset-classic').Options} */
({
docs: {
routeBasePath: ‘/‘, //set the path to root
sidebarPath: './sidebars.js',
// Please change this to your repo.
// Remove this to remove the "edit this page" links.
editUrl:
'https://github.com/facebook/docusaurus/tree/main/packages/create-docusaurus/templates/shared/',
},
blog: false, // set the blog to false
theme: {
customCss: './src/css/custom.css',
},
}),
],
],Scroll down to `items` under `themeConfig` and remove the code:
{to: '/blog', label: 'Blog', position: 'left’},
title: 'My Site',
logo:
{
alt: 'My Site Logo',
src: 'img/logo.svg',
},
{
type: 'docSidebar',
sidebarId: 'tutorialSidebar',
position: 'left',
label: 'Tutorial',
},Scroll down to `items` under `footer` and remove the code. Removing these code blocks ensures that there are no broken links on your website.
{ label: 'Blog', to: '/blog', },
{
title: 'Docs',
items:
[
{ label: 'Tutorial', to: '/docs/intro',
},
],
},`Delete these folders and files from the project directory: blog, tutorial-basics, and tutorial-extras, pages under `src`, HomepageFeatures under `src > components`. Deleting these files ensures that there are no unwanted files in your project directory.
Open `intro.md` under the docs folder and remove all the content. Add the below content:
---
sidebar_position: 1
slug: /
---
# Introduction
Welcome! Your first Docs-only Docusaurus website.Run the below command to build the website:
npm run buildRun the below command to host the website from the local build:
npm run serve🥳 Congratulations! Your docs-only first Docusaurus website is ready. You’ll a page as below rendered on localhost:3000
In conclusion, this guide has equipped you with the knowledge to effortlessly create your first Docusaurus documentation website. From setting up prerequisites to running your first website, you've learned step-by-step procedures. Whether following the default configuration or opting for a docs-only mode, you now possess a foundational Docusaurus website, ready for further customization. This guide aimed to make the process easy, providing a seamless introduction to building your first documentation website with Docusaurus.
📣 Check out the Code!Interested in seeing the actual code? All the projects and examples discussed in this blog are available in my GitHub repository. Explore the code, experiment with it, and feel free to contribute!
As you embark on your documentation journey, stay tuned for the next blog post. I'm excited to share that we will delve into more configuration options for your Docusaurus website.
Happy documenting!