Docusaurus is a powerful static site generator that helps you build a documentation website quickly. This tutorial will guide you through creating your first Docusaurus website using the latest version. Let's dive in!
Prerequisites
Before starting, make sure you have:
Node.js and npm: Download and install Node.js from nodejs.org.
Terminal: Use your preferred terminal.
Visual Studio Code (VS Code): Install Visual Studio Code or another code editor of your choice.
Create your Docusaurus Doc Website
Follow these steps to create your first Docusaurus website:
Open your terminal and run the below command. The below command creates a basic scaffold for your Docusaurus website and uses the latest version of Docusaurus to create a new project named my-docs-website with the classictheme.
npx create-docusaurus@latest my-docs-website classicType y to proceed with the installation. You’ll see output similar to:
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.
Once opened in Visual studio code editor, open the explorer to review the project directory structure. Your project will have the following structure:
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.
Run the below command in the terminal within VS code editor in the root directory:
npm startThis command starts a development server and makes your Docusaurus site accessible at localhost:3000.
🎉 Congratulations! Your basic Docusaurus website 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 docusaurus.config.js and adjust the presets section:
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 blog link from items and adjust footer items to avoid broken links.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 the blog, tutorial-basics, and tutorial-extras folders, as well as unwanted files under src/pages and src/components/HomepageFeatures. Deleting these files ensures that there are no unwanted files in your project directory.
Update the `intro.md` under the docs folder and replace its content with:
---
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 serveAfter the server is up and running, Your Docs-only Docusaurus website is now live at localhost:3000
See also
Before we wrap up, check out the GitHub repository to explore the complete codebase and contribute. You can see the project live by visiting the live demo of creating your first Docusaurus website.
Conclusion
This tutorial has guided you through creating your first Docusaurus website, from setup to running a Docs-only site. You now have a basic Docusaurus website ready for customisation.
Feedback
We’d love to hear your thoughts! If you have any questions, comments, or suggestions, feel free to leave a comment below or start a discussion on the GitHub repository. Your feedback helps us improve and provide better resources.
Happy documenting!