A Step-by-Step Guide to Create, Customize, and Deploy
Introduction ๐ก
As a developer or technical writer, creating a well-organized and easy-to-navigate documentation site is essential to help users quickly find information and understand how to use your product or service. Markdown is a lightweight markup language that is widely used for writing technical documentation because it is easy to write and read, and can be converted into various formats. Docusaurus is a popular open-source static site generator that can help you create beautiful and responsive documentation sites with ease.
In this step-by-step guide, we'll walk you through how to build a Markdown documentation site with Docusaurus.
Step 1: Install Docusaurus
Before we start building our documentation site, we need to install Docusaurus. Docusaurus is a Node.js-based tool, so we need to make sure that Node.js and npm (Node Package Manager) are installed on our computer. To install Docusaurus, we'll use npm.
Open a terminal or command prompt and run the following command:
npm install --global docusaurus-init
This command installs the Docusaurus command-line interface (CLI) globally on our computer. Once the installation is complete, we can use the docusaurus-init
command to create a new Docusaurus project.
Step 2: Create a new Docusaurus project
To create a new Docusaurus project, run the following command:
docusaurus-init my-docs
Replace my-docs
with the name of your project. This command creates a new directory with the specified name and sets up a basic Docusaurus project structure inside it. The project structure includes the following files and directories:
docs/
: This directory is where we'll put our Markdown documentation files.website/
: This directory contains the Docusaurus configuration files, such asdocusaurus.config.js
andpackage.json
.node_modules/
: This directory contains the dependencies that our project requires.static/
: This directory is where we'll put any static assets, such as images or CSS files.
Step 3: Customize the Docusaurus configuration
Now that we have our project structure set up, we can customize the Docusaurus configuration to suit our needs. The configuration files are located in the website/
directory.
Configuring the site title and tagline
Open the docusaurus.config.js
file in a text editor and change the title
and tagline
fields to the title and tagline of your documentation site. For example:
module.exports = {
title: 'My Documentation Site',
tagline: 'This is the tagline for my documentation site',
// ...
};
Configuring the site URL and base URL
By default, Docusaurus assumes that the documentation site will be hosted at the root of a domain (e.g. https://example.com
). If you're hosting your documentation site on a subpath (e.g. https://example.com/docs/
), you need to configure the site URL and base URL.
Open the docusaurus.config.js
file and add the following fields to the url
and baseUrl
objects:
module.exports = {
url: 'https://example.com',
baseUrl: '/docs/',
// ...
};
Replace https://example.com
with the URL of your documentation site, and /docs/
with the base URL of your documentation site.
Configuring the navigation bar
The navigation bar is the bar at the top of the documentation site that contains links to the different pages of the site. To configure the navigation bar, open the docusaurus.config.js
file and add the following fields to the nav
array:
module.exports = {
// ...
themeConfig: {
navbar: {
title: 'My Documentation Site',
logo: {
alt: 'My Site Logo',
src: 'img/logo.svg',
},
items: [
{
to: 'docs/introduction',
activeBasePath: 'docs',
label: 'Docs',
position: 'left',
},
{ to: 'blog', label: 'Blog', position: 'left' },
{
href: 'https://github.com/myusername/myproject',
label: 'GitHub',
position: 'right',
},
],
},
footer: {
// ...
},
},
// ...
};
This example adds three items to the navigation bar:
A link to the
docs/introduction.md
file, with the label "Docs".A link to the
blog/
directory, with the label "Blog".A link to a GitHub repository, with the label "GitHub".
The to
field specifies the URL or path of the page or directory that the link points to. The activeBasePath
field specifies the base path for the link to be considered active. The label
field specifies the text to display in the link. The position
field specifies the position of the link in the navigation bar, either "left" or "right".
Configuring the sidebar
The sidebar is the menu on the left-hand side of the documentation site that contains links to the different sections and pages of the site. To configure the sidebar, we need to create a sidebars.js
file in the website/
directory. The sidebars.js
file is where we define the structure and content of the sidebar.
Create a new file named sidebars.js
in the website/
directory and add the following code:
module.exports = {
docs: {
Introduction: ['introduction'],
Features: ['feature-1', 'feature-2'],
// ...
},
};
This example defines a docs
section with three pages: "Introduction", "Feature 1", and "Feature 2". The page titles correspond to the Markdown file names (e.g. introduction.md
).
Adding content to the documentation site
Now that we have the Docusaurus configuration set up, we can start adding content to our documentation site. Create a new file named introduction.md
in the docs/
directory and add the following Markdown content:
---
id: introduction
title: Introduction
---
# Welcome to my documentation site
This is the introduction page for my documentation site.
This Markdown content defines the title and ID of the page, and the content of the page itself.
To add more pages to the documentation site, create new Markdown files in the docs/
directory and update the sidebars.js
file to include the new pages.
Step 4: Customize the styling of the documentation site
Docusaurus comes with a default theme that provides a clean and professional look for the documentation site. However, we can customize the styling of the site to match our branding or personal preferences.
Changing the color scheme
To change the color scheme of the site, open the docusaurus.config.js
file and add the following field to the themeConfig
object:
module.exports = {
// ...
themeConfig: {
// ...
colorMode: {
defaultMode: 'light',
disableSwitch: false,
respectPrefersColorScheme: false,
switchConfig: {
darkIcon: '<i class="fa fa-moon"></i>',
lightIcon: '<i class="fa fa-sun"></i>',
},
},
},
// ...
};
This example sets the default color mode to "light" and enables the color mode switch in the navigation bar. The disableSwitch
field specifies whether to disable the color mode switch. The respectPrefersColorScheme
field specifies whether to use the system's color scheme as the default mode. The darkIcon
and lightIcon
fields specify the icons to use for the dark and light modes, respectively.
You can also customize the colors of the site by editing the src/css/custom.css
file. For example, to change the background color of the site, add the following CSS rule:
body {
background-color: #f9f9f9;
}
Customizing the logo
To customize the logo of the site, replace the website/static/img/logo.svg
file with your own logo file. You can also edit the size and position of the logo by adding the following field to the themeConfig
object:
module.exports = {
// ...
themeConfig: {
navbar: {
// ...
logo: {
alt: 'My Site Logo',
src: 'img/logo.svg',
// ...
width: 100,
height: 50,
},
},
// ...
},
// ...
};
This example sets the width and height of the logo to 100 and 50 pixels, respectively. You can also use the className
field to add custom CSS classes to the logo element.
Customizing the font
To customize the font of the site, add the following field to the themeConfig
object:
module.exports = {
// ...
themeConfig: {
// ...
font: {
family: 'Arial',
size: 16,
weight: 'normal',
},
},
// ...
};
This example sets the font family to "Arial", the font size to 16 pixels, and the font weight to "normal". You can also use the googleFonts
field to specify Google Fonts to load, and the codeFonts
field to specify the font for code blocks.
Step 5: Deploy the documentation site
Once you have customized the documentation site to your liking, it's time to deploy it so that others can access it. There are several options for deploying a Docusaurus site, including hosting it on a web server, using a static site hosting service, or deploying it to a cloud service like AWS or Azure.
Hosting on a web server
To host the documentation site on a web server, copy the built files from the build/
directory to your web server's document root directory. You can use a tool like rsync
to copy the files over:
rsync -av build/ myserver:/var/www/html/
Replace myserver
with the hostname or IP address of your web server, and /var/www/html/
with the document root directory.
Static Site hosting service : Netlify, GitHub Pages, or Vercel.
These services provide a simple way to host your Docusaurus site and deploy changes quickly.
Deploying to GitHub Pages
To deploy your Docusaurus site to GitHub Pages, follow these steps:
Push your changes to the
main
branch:git add . git commit -m "Update documentation" git push origin main
Install the
gh-pages
package:yarn add -D gh-pages
Update the
docusaurus.config.js
file to include thebaseUrl
andtrailingSlash
fields:module.exports = { // ... url: 'https://username.github.io', baseUrl: '/my-docs/', trailingSlash: true, // ... };
Replace
username
with your GitHub username andmy-docs
with the name of your repository.Add a new script to the
package.json
file:"scripts": { // ... "deploy": "docusaurus deploy", // ... }
Run the deploy script:
yarn deploy
Wait for the deployment to complete. Once it's finished, your documentation site will be available at
https://username.github.io/my-docs/
.
Deploying to Netlify
To deploy your Docusaurus site to Netlify, follow these steps:
Sign up for a Netlify account if you don't already have one.
Create a new site in Netlify and connect it to your GitHub repository.
Configure the build settings in Netlify:
Build command:
yarn build
Publish directory:
build/
Save the settings and trigger a new deploy.
Wait for the deployment to complete. Once it's finished, your documentation site will be available at a Netlify URL like
https://my-docs.netlify.app/
.
Deploying to Vercel
To deploy your Docusaurus site to Vercel, follow these steps:
Sign up for a Vercel account if you don't already have one.
Connect your Docusaurus project to Vercel using the Vercel CLI:
yarn global add vercel vercel login cd my-docs vercel init
Follow the prompts to configure your deployment settings.
Deploy the project:
vercel deploy
Wait for the deployment to complete. Once it's finished, your documentation site will be available at a Vercel URL like
https://my-docs.vercel.app/
.
Conclusion ๐
Congratulations, you've successfully built and deployed a documentation site with Docusaurus! With this powerful tool, you can create professional-looking documentation sites with ease, and keep your users up-to-date with your latest releases and updates.