Start and deploy Docusaurus Documentation Static Site on your own server

Docusaurus is a modern static website generator developed by Meta (formerly Facebook). It excels at creating documentation websites with versioning, search, and internationalization support out of the box. It uses React for themes and components, making it highly customizable.

In this tutorial, I'll show you how to create a documentation site with Docusaurus, customize it, and deploy it using Appliku.

Table of Contents

Requirements
Source code
Create a Docusaurus Project
Project Structure
Configure Docusaurus
Create Content
Customize Styling
Preview Your Site
Build Your Site
Commit and Push to GitHub
Deploy with Appliku

Requirements¶

For this tutorial you need:

Node.js 20 or higher
git
GitHub account
Appliku Account

Source code¶

The source code for this tutorial is available on GitHub repository appliku/docusaurustutorial

Create a Docusaurus Project¶

Initialize a new Docusaurus project:

npx create-docusaurus@latest docusaurustutorial classic
cd docusaurustutorial

When asked, choose the language between JavaScript and TypeScript. This tutorial assumes you picked JavaScript. Edit .gitignore file:

node_modules/
build/
.docusaurus/
.DS_Store
.env.local
.env.development.local
.env.test.local
.env.production.local
npm-debug.log*
yarn-debug.log*
yarn-error.log*
.idea/
.vscode/

Project Structure¶

After initialization, you'll have this structure:

├── README.md
├── blog
│   ├── 2019-05-28-first-blog-post.md
│   ├── 2019-05-29-long-blog-post.md
│   ├── 2021-08-01-mdx-blog-post.mdx
│   ├── 2021-08-26-welcome
│   │   ├── docusaurus-plushie-banner.jpeg
│   │   └── index.md
│   ├── authors.yml
│   └── tags.yml
├── docs
│   ├── intro.md
│   ├── tutorial-basics
│   │   ├── _category_.json
│   │   ├── congratulations.md
│   │   ├── create-a-blog-post.md
│   │   ├── create-a-document.md
│   │   ├── create-a-page.md
│   │   ├── deploy-your-site.md
│   │   └── markdown-features.mdx
│   └── tutorial-extras
│       ├── _category_.json
│       ├── manage-docs-versions.md
│       └── translate-your-site.md
├── docusaurus.config.js
├── package-lock.json
├── package.json
├── sidebars.js
├── src
│   ├── components
│   │   └── HomepageFeatures
│   │       ├── index.js
│   │       └── styles.module.css
│   ├── css
│   │   └── custom.css
│   └── pages
│       ├── index.js
│       ├── index.module.css
│       └── markdown-page.md
└── static

Configure Docusaurus¶

Edit docusaurus.config.js to configure your site, for example site name, tagline, url:

const config = {
  title: 'Docusaurus tutorial deployed with Appliku',
  tagline: 'Static site generator', favicon: 'img/favicon.ico',
  // Set the production url of your site here
  url: 'https://docusaurustutorial.applikuapp.com',
  baseUrl: '/',
  organizationName: 'appliku',
  projectName: 'docusaurustutorial',
// ... the rest of the code is truncated

Create Content¶

Create docs/intro.md:

---
sidebar_position: 1
---

# Welcome to Docusaurus tutorial

This is a very simple demo of our amazing documentation site.

Create docs/about.md:

---
sidebar_position: 2
---

# About authors

This demo is brought to you by Appliku.

Customize Styling¶

Edit src/css/custom.css:

:root {
  --ifm-color-primary: #2e8555;
  --ifm-color-primary-dark: #29784c;
  --ifm-color-primary-darker: #277148;
  --ifm-color-primary-darkest: #205d3b;
  --ifm-color-primary-light: #33925d;
  --ifm-color-primary-lighter: #359962;
  --ifm-color-primary-lightest: #3cad6e;
}

[data-theme='dark'] {
  --ifm-color-primary: #25c2a0;
  --ifm-color-primary-dark: #21af90;
  --ifm-color-primary-darker: #1fa588;
  --ifm-color-primary-darkest: #1a8870;
  --ifm-color-primary-light: #29d5b0;
  --ifm-color-primary-lighter: #32d8b4;
  --ifm-color-primary-lightest: #4fddbf;
}

You can also edit the main page of the documentation site in src/pages/index.js which by default looks like this:

import clsx from 'clsx';
import Link from '@docusaurus/Link';
import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
import Layout from '@theme/Layout';
import HomepageFeatures from '@site/src/components/HomepageFeatures';

import Heading from '@theme/Heading';
import styles from './index.module.css';

function HomepageHeader() {
  const {siteConfig} = useDocusaurusContext();
  return (
    <header className={clsx('hero hero--primary', styles.heroBanner)}>
      <div className="container">
        <Heading as="h1" className="hero__title">
          {siteConfig.title}
        </Heading>
        <p className="hero__subtitle">{siteConfig.tagline}</p>
        <div className={styles.buttons}>
          <Link
            className="button button--secondary button--lg"
            to="/docs/intro">
            Docusaurus Tutorial - 5min
          </Link>
        </div>
      </div>
    </header>
  );
}

export default function Home() {
  const {siteConfig} = useDocusaurusContext();
  return (
    <Layout
      title={`Hello from ${siteConfig.title}`}
      description="Description will go into a meta tag in <head />">
      <HomepageHeader />
      <main>
        <HomepageFeatures />
      </main>
    </Layout>
  );
}

Preview Your Site¶

Start the development server:

npm start

Visit http://localhost:3000 in your browser.

Docusaurus running locally main page

And here is our documentation page:

Documentation page of our docusaurus site

Build Your Site¶

Generate the static site:

npm run build

Docusaurus build

This creates a build directory with your static website.

Commit and Push to GitHub¶

Initialize git repository and commit your changes:

git init
git add .
git commit -m "Initial commit"

Create a new repository on GitHub.

Create GitHub repository for Docusaurus Documentation Site

In this screenshot repository is set to public, but for your projects, you might want to set it to private.

Since the repository is empty, GitHub will offer you a few commands. We need the line git remote add origin Copy this line and run it in your terminal

and push your code: