top of page
Post: Blog2 Post
  • Writer's pictureNikhila Jain

Create your First Docusaurus Documentation Website

Updated: Jan 27


Create your docs website with Docusaurus

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:

  1. Open the terminal, and run the below command to create the basic scaffold using Docusaurus:

npx create-docusaurus@latest my-docs-website classic

In 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.
  1. Go to the project directory by using a `cd` command:

cd my-docs-website
  1. Open 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.


Docusaurus project structure
Docusaurus Project Structure
  1. You’ll see a folder structure as below:

  2. blog - a directory that hosts all your blog posts

  3. docs - a directory that hosts all your documentation

  4. src - a directory that hosts components, pages and css of your Docusaurus website

  5. static - a directory that hosts all static assets like images, files and more

  6. 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.

  7. sidebar.js - the configuration file used by Docusaurus to create the documentation navigation hierarchy.

  8.  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 start

The 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:


Docusaurus website
Docusaurus Website with Default configuration

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 build
  • Run 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


Docusaurus Docs-only website
Docusaurus Docs-only website

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!



コメント


bottom of page