Skip to main content
Version: 2.0

Chapter 1: Introduction and Installation

Docusaurus is an open-source static site generator developed by Meta (formerly Facebook). It follows the principle of “docs as code” and helps users build a documentation site from the ground up.

So, as a Technical Writer, how exactly can Docusaurus help you? Well, you can create a complete documentation website from scratch and host it online — all without using any commercial documentation tools. On top of that, you can implement key docs-as-code principles, like keeping documentation in sync with product updates, improving collaboration with developers, supporting documentation versioning, and more. In addition to organizational documentation, you can also use Docusaurus to host your personal blog — completely free. It offers far more customization options than traditional blogging platforms.

Some of the features that make Docusaurus a real game changer include:

  • Customization Options: A Docusaurus site is not a typical blog with limited customization options. It provides you with a variety of tools to modify the look and feel of your site to match your organization's color palette.

  • Versioning: Docusaurus supports documentation versioning — a feature missing in many paid documentation tools. You can maintain multiple versions of your documentation, each representing a product version, allowing customers to select the appropriate documentation for their needs.

  • Search Bar: Docusaurus includes a fully customizable search bar. You can customize not just the layout and location, but also the search engine itself. You can choose between browser-based search or Algolia integration.

  • Plugins: Docusaurus offers a range of plugins to enhance your site. You can easily add them by inserting small snippets of code. If you’re tech-savvy, you can even develop your own plugins.

  • Monolithic Repository (Monorepo): Docusaurus advocates for a monorepo structure, where both documentation and code reside in a single repository (under different directories). With this setup, whenever a change request is created, the technical writer is notified. Writers can then collaborate with developers to understand the changes and determine if documentation updates are needed — ensuring that the docs stay in sync with the product.

  • Markdown Support: Markdown is widely used in technical writing for creating formatted text, API docs, and more. It enables you to style plain text using elements like bullet points, headings, numbered lists, hyperlinks, and so on.

Prerequisites​

  • Ensure that you have the Node.js package installed on your system. You can download it from the official website.

Installation​

The Docusaurus installation process is simple and straightforward. Just run a few commands in the command prompt, and you’re set up.

  1. Run the following command to ensure that Node.js is installed on your system:
node -v

If this command returns a Node.js version, it means Node.js is installed. If not, refer to the prerequisites section.

  1. Run the following command to create a new Docusaurus project in classic mode:
npx create-docusaurus@latest my-website classic
note

  • During installation, you’ll be asked to choose between JavaScript and TypeScript. Choose JavaScript unless you're already comfortable with TypeScript.

  • The Docusaurus project will be created in a directory named my-website. To use a different name, replace my-website in the command above with your preferred project name.

  • Once installed, navigate into your project directory:

cd my-website
note

If you chose a different name for your directory in step 2, replace my-website with that name here.

  1. Start the Docusaurus site by running:
npm run start

This command launches the Docusaurus site in your browser. The default port is 3000. The session remains active as long as the command prompt is open. If you close the tab or the browser, simply type localhost:3000 in the address bar to reopen the site.

The my-website (or the custom name used in step 2) directory is created under Users/<logged-in-user>. This applies to both macOS and Windows systems. The project structure looks like this:

alt text

  • blog (optional): If you enable the blog feature, this folder will store your blog posts.

  • docs: Contains all your documentation pages (written in Markdown or MDX). These files automatically appear in the sidebar.

  • src: This folder holds the React components, pages, and styling.

  • src/pages: Contains static custom pages like index.js (home page) or an About page.

  • src/components: Holds reusable custom React components (e.g., Tile, Card, HeroBanner).

  • src/css: Contains custom CSS. Modify these files to change the site’s appearance.

  • static: Files here are directly copied to the site root. This is where you store images, icons, PDFs, favicons, etc. By default, it includes an img folder used by the default Docusaurus site.

  • node_modules: This folder stores all Node.js dependency packages. You can use them in your project via require() or import. Avoid editing this folder directly.

  • docusaurus.config.js: The main configuration file (JavaScript). It controls site details like the navbar, footer, plugins, themes, routes, metadata (title, tagline), and more.

  • sidebars.js: This file defines the structure and order of documents in the sidebar.

  • package.json: Contains project metadata and manages dependencies and scripts. Commands like start, build, and deploy are defined here.

  • package-lock.json: Locks exact versions of installed packages, ensuring consistency in the dependency tree.

  • README.md: Provides setup instructions and project information for developers.