Skip to main content

Create Docusaurus application

Create a New Directory​

Docusaurus recommends using the classic template to get started quickly. For more infomation, check Docusaurus documentation.

To create a new Docusaurus application, run the following command:

npx create-docusaurus@latest my-website classic

If you prefer to use TypeScript, use this command instead:

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

Once the installation is complete, navigate to your project directory and start the development server:

cd my-website
npm start

Understanding the Docusaurus Project​

After creating the project, you will see the following file structure::

my-website
├── blog
│   └── 2020-05-30-welcome.md
├── docs
│   ├── doc1.md
│   └── mdx.md
├── src
│   ├── css
│   │   └── custom.css
│   └── pages
│       ├── styles.module.css
│       └── index.js
├── static
│   └── img
├── docusaurus.config.js
├── package.json
├── README.md
├── sidebars.js
└── yarn.lock

Key Folders and Files​

  • /docs/ - Contains the Markdown files for documentation. Files in this folder are displayed under the "Tutorial" tab.
  • /blog/ - Contains the Markdown files for blog posts. Files in this folder are displayed under the "Blog" tab.
  • /docusaurus.config.js - The configuration file for your Docusaurus site.

How to Create a New Documentation Project​

  1. Create a new folder in /docs/, e.g., project1.
  2. To set its sidebar position and title, create a _category_.json file in this folder:
_category_.json
{
  "label": "Project 1",          // This is the title of your folder in the sidebar
  "position": 3,                 // This is the position of this folder in the sidebar
  "link": {
    "type": "generated-index",
    "description": "This is the description about this project/folder in general."
  }
}
  1. Create a new Markdown file in this folder, e.g., testing.md.
  2. At the beginning of the file, define metadata like this:
---
title: Your Page Title
sidebar_position: 1
---

That's it! You've created your first documentation page.

How to Create a New Blog​

The process is similar to creating a documentation page, with one key difference:

  1. File Naming and Order:
  • The order of blog posts is determined by the date prefix in the filename.
    • Example: A blog named 2024-12-29-blog2 will appear in the 2024 section and above 2024-12-28-blog1.
  1. Metadata:
  • At the beginning of the file, define metadata like this:
---
slug: this-blog-url
title: Your Blog Title
authors: [author1]
tags: [tag1, tag2]
---
  1. Author and Tag Management:
  • By default, Docusaurus creates authors.yml and tags.yml for you.
  • Update these files to include the relevant information about authors and tags.

Tips​

  • You can write React components inside .mdx files. For example:.
example.mdx
export const Highlight = ({children, color}) => (
  <span
    style={{
      backgroundColor: color,
      borderRadius: '2px',
      color: '#fff',
      padding: '0.2rem',
    }}>
    {children}
  </span>
);

<Highlight color="#25c2a0">Docusaurus green</Highlight> and <Highlight color="#1877F2">Facebook blue</Highlight> are my favorite colors.

I can write **Markdown** alongside my _JSX_!
  • To customize the styling, view this CSS Styling Guide
  • Remember to config docusaurus.config.ts following the comments

Useful Tutorial​