Create Your First Docusaurus Documentation Website

Docusaurus helps you spin up a modern documentation site in minutes. Think of Docusaurus as your personal documentation architect - it designs the structure, builds the framework, and lets you focus on what matters most: your content.

In this hands-on tutorial, you build your first Docusaurus documentation website and then convert it into a docs-only site

What You Learn

By the end of this tutorial, you are able to:

• Create a new Docusaurus project using the official CLI
• Configure Docusaurus for documentation-only mode
• Customize the site structure and navigation
• Deploy your documentation site to production
• Follow best practices for maintainable documentation

Prerequisites

Before we start our journey, let us make sure you have your tools ready:

• Node.js 18+ and npm installed. Download them from nodejs.org.
• A terminal (macOS Terminal, iTerm, Windows Terminal, or similar).
• A code editor such as Visual Studio Code.
• Basic knowledge of Markdown and JavaScript concepts.
• A GitHub account (optional, for deployment).

Do not worry if you are not an expert - we guide you through every step!

Create Docusaurus Project

• Create a new Docusaurus site:

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

  This command:

  • downloads the Docusaurus CLI
  • scaffolds a new project called my-docs-website
  • uses the classic template (docs + blog + pages)

• Move into the new folder:

  cd my-docs-website
  

• Open the project in VS Code:

  code .
  

  Now your folder looks roughly like this:

  📁 my-docs-website
  ├── 📁 blog/                  # blog posts
  ├── 📁 docs/                  # documentation pages
  ├── 📁 src/                   # components, pages, CSS
  ├── 📁 static/                # images and other static assets
  ├── 📄 docusaurus.config.js   # main Docusaurus config
  └── 📄 sidebars.js            # docs sidebar config
  

💡 Tip: In VS Code, you can expand/collapse these folders in the Explorer to match this structure as you follow the steps.

Run Dev Server

From the project root, start the development server:

npm start

After the build completes, Docusaurus opens your site at http://localhost:3000.

✅ You should now see:

• a home page with a hero section
• a Docs section with starter content
• a Blog section with example posts

Turn Site Into Docs-Only Mode

If you want your site to focus only on documentation, you can route the docs to the site root and disable the blog.

1. Update the docs preset

   In docusaurus.config.js, find the presets section and update the docs configuration:

   presets: [
     [
       'classic',
       {
         docs: {
           routeBasePath: '/', // serve docs at the site root
           sidebarPath: require.resolve('./sidebars.js'),
         },
         blog: false, // disable the blog
         theme: {
           customCss: require.resolve('./src/css/custom.css'),
         },
       },
     ],
   ];
   

2. Clean up navbar items

   Still in docusaurus.config.js, go to themeConfig.navbar.items and remove any entries that point to /blog or other pages you no longer need. For example, remove items such as:

   { to: '/blog', label: 'Blog', position: 'left' },
   

3. Clean up footer links

   In themeConfig.footer.links, remove any links that reference /blog or unused docs routes to avoid broken links.

4. Update the docs home page

   Open docs/intro.md (or the first page in your docs) and make it the root of your documentation:

   ---
   sidebar_position: 1
   slug: /
   ---
   
   # Introduction
   
   Welcome! Your first docs‑only Docusaurus website.
   

5. Rebuild and serve

   Build the production site:

   npm run build
   

   Serve the built site locally:

   npm run serve
   

   Your docs‑only Docusaurus site is now available at http://localhost:3000.

See Also

• Explore the full example in the GitHub repository: learn-docusaurus.
• View the live demo of creating your first Docusaurus website.

Conclusion

You’ve created a Docusaurus project, run it locally, and converted it into a docs‑only site. From here, you can customise the theme, structure your docs with sidebars, and integrate deployment to platforms such as GitHub Pages or Vercel.

Happy documenting!