How to Use Docusaurus From Scratch

Do you want to build a beautiful website to share your documentation or project guide? Maybe you're a developer or writer who wants a space online to organize your ideas. Well, meet Docusaurus, a tool that helps you do just that, and it's super friendly for beginners.

In this guide, I’ll show you step-by-step how to use Docusaurus from scratch using simple language. If this is your first attempt, don’t be scared. This guide provides every detail you need from installation to deployment. You’ll be able to follow along.

What Is Docusaurus?

Docusaurus is a tool made by Facebook (now Meta). It helps people create websites for documentation. These websites are fast, pretty, and easy to use.

Think of it like this: if your documentation is a book, Docusaurus is the bookshelf that displays it neatly.

What You Need Before Starting

Before we begin, make sure you have these:

• A computer (Windows, Mac, or Linux)

• Internet connection

• Node.js installed (version 16.14 or later)

• A basic understanding of how to use your computer’s terminal or command prompt

Tip: To check if Node.js is installed, open your terminal and type:

node -v

If you see a number like v16.14.2, you’re good to go.

Step 1: Create a New Docusaurus Project

Let’s start by making a new Docusaurus website. Here’s how:

1. Open your terminal.

2. Type this command:

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

• npx is a command that lets us run packages easily.

• my-docs-site is the folder where your site will be.

• classic is the template we’re using. It comes with docs, a blog, and a homepage.

3. The terminal will ask you a few questions:

• Choose a language: Pick JavaScript for now.

• Wait while it installs the needed files.

Step 2: Go Into Your New Project

Now that your project is ready, move into it. Type the following commands on your terminal:

cd my-docs-site

Step 3: Start the Development Server

This is how you see your website on your browser:

yarn start

If you didn’t install Yarn, try:

npm run start

This will open your new site at:

http://localhost:3000

Boom! Your site is live on your computer.

Using Yarn Instead of npm

Sometimes npm can be slow or may get stuck during installation. Yarn is a faster, more reliable package manager. Here’s how to use Docusaurus with Yarn from the start.

Step 1: Install Yarn (if you haven’t already)

npm install --global yarn

Check that it's installed:

yarn -v

Step 2: Create a New Docusaurus Site with Yarn

yarn create docusaurus my-docs-site classic

When prompted, choose JavaScript.

Move Into Your Project

cd my-docs-site

Start the Development Server

yarn start

Your site will be live at:

http://localhost:3000

Build Your Site for Production

yarn build

This creates a production-ready version of your site in the build/ folder.

(Optional) Deploy Your Site

Follow the official deployment guides for GitHub Pages, Netlify, or Vercel.

Step 4: Understand the Project Structure

Let’s peek into the folders and files:

• docs/: This is where you add your documentation files like getting-started.md.

• blog/: This is where your blog posts go.

• src/pages/: These are custom pages like About or Contact, CSS styline, etc[.

  ](https://docusaurus.io/docs/deployment#deploying-to-vercel)

• docusaurus.config.js: This is your settings file. You can change the site name, logo, links, etc.

Step 5: Add Your First Doc Page

Let’s make your first documentation page.

1. Go to the docs folder[.

   ](https://docusaurus.io/docs/deployment#deploying-to-netlify)

2. Create a new file called hello.md.
   

3. Add this conten[t:

   ](https://docusaurus.io/docs/deployment#deploying-to-vercel)

--- id: hello title: Hello, Docusaurus! --- Welcome to your first Docusaurus doc page.

The lines between the --- at the top of your .md file are called frontmatter. They give Docusaurus important information like the page ID, title, and how to organize it in the sidebar. Think of it like a name tag for your file so Docusaurus knows where and how to display it. It also helps with SEO. It tells search engines the page’s title and helps organize your site for better visibility online.

Now visit your browser again and go to:

http://localhost:3000/docs/hello

You’ll see your new page!

Step 6: Autogenerate the Sidebar

Docusaurus can automatically make a sidebar from the docs folder. Just keep your .md files organized in folders.

If you're using the default setup, the sidebar is already set to autogenerate. You’ll find the settings in sidebars.js:

const sidebars = {   tutorialSidebar: [{type: 'autogenerated', dirName: '.'}], };

This means: "Look in the docs folder and create the sidebar from there."

Step 7: Customize the Homepage

To change what the homepage says:

1. Open src/pages/index.js

2. Look for the title and subtitle.

3. Change them to match your project.

Example:

<Heading as="h1" className="herotitle">   Refract Documentation </Heading> <p className="herosubtitle">A fictional UI framework with real-world docs.</p>

You can also change the button link to go to your first doc page:

<Link   className="button button--secondary button--lg"   to="/docs/hello">   Get Started </Link>

Step 8: Build Your Site

When you're ready to publish your site, run:

yarn build

This makes a build/ folder with your full site inside, ready to be uploaded anywhere (like Netlify or GitHub Pages).

Step 9: Deploy Your Site (Optional)

If you want to publish your site online, Docusaurus has many guides:

• [Deploy to GitHub Pages

  ](https://docusaurus.io/docs/deployment#deploying-to-github-pages)

• [Deploy to Netlify

  ](https://docusaurus.io/docs/deployment#deploying-to-netlify)

Just pick the one you like best.

Best Practices

• Always write your docs in docs/ using .md (Markdown) files.

• Use folders to group topics.

• Let Docusaurus build your sidebar automatically.

• Customize the homepage to match your project.

• Build and deploy your site when you're ready

Congratulations! You just built a working documentation website with Docusaurus. It looks professional, loads fast, and is easy to update. Whether you’re documenting code, a product, or just writing tutorials, Docusaurus makes your life easier.

Want to go further? Try these next:

• Add a logo to your site.

• Create a blog post in the blog/ folder.

• Add links to your GitHub or Twitter in the navbar.

Happy documenting!