Deploy Docusaurus site to GitLab Pages

Prerequisites

Before you dive into publishing on GitLab Pages, it’s a good idea to read more about this service. Or, you may skip and continue with the instructions below.

• You have created the Docusaurus site by following these instructions
• You have your own Docusaurus site you would like to publish on GitLab Pages.

With either of these two options you’re ready to publish the Docusaurus site on GitLab Pages.

Create a GitLab repo

First, you need to create your GitLab repo, if you don’t have one.

To create a GitLab repo:

1. Go to this link to create an empty repo:

   https://gitlab.com/projects/new#blank_project

2. Fill in these fields:

   a. Project name - any name of your project.

   b. Project slug - your repo name.

   c. Select the Public checkbox.

   d. Remove selection from the Initialize repository with a README checkbox.

   e. Select Create project.

   

Your empty repo is created.

Push your Docusaurus project to the remote server

To initialize a local Git repo in your Docusaurus project folder and push it to the newly created repo:

1. In the Command Prompt, clone the newly created repo:

   git clone https://gitlab.com/ivancheban/your-test-site.git
   

   where your-test-site is your repo name.

   

2. In the Command Prompt, go to the your-test-site folder.

   cd your-test-site
   

   

3. Switch to the Git main branch.

   git switch -c main
   

4. Copy the files from your existing Docusaurus project folder to the your-test-site folder without the hidden .git folder.

   

5. In the Command Prompt, add all the copied files:

   git add --all
   

6. Commit the added files.

   git commit -m "add files"
   

7. Push the committed files to the remote server.

   git push -u origin main
   

8. Refresh the GitLab page for your repo to see the uploaded files.

   

Fork project

Another way (much easier) is to fork my project from GitLab.

To fork my project from GitLab:

1. Go to https://gitlab.com/ivancheban/test-site.

2. Select Fork.

   

3. Fill in the fields:

   a. The project namespace - select your GitLab name from the dropdown list.

   b. Project slug - type the repo name.

   c. Select Fork project.

   

4. Clone the forked project.

   git clone https://gitlab.com/ivancheban/my-test-site.git
   

   where my-test-site is the repo name of the forked project.

Create CI configuration

To create a CI (Continuous Integration) configuration file:

1. Open your Docusaurus project in VS Code.

   

2. Click the New file button to add a new file.

   

3. Type the file name and extension: .gitlab-ci.yml. Press Enter.

   Your file is created.

4. Copy this code and paste it inside the .gitlab-ci.yml file.

   image: node:latest
   
   # allow caching for faster deployment
   cache:
     paths:
       - node_modules/
       - public/
       - .cache/
   
   pages:
     stage: deploy
     script:
       - yarn install
       - yarn build:gitlab
     artifacts:
         paths:
           - public
     only:
       - main
   

5. Add this code to the package.json file.

   "build:gitlab": "docusaurus build --out-dir public",
   

   

6. Change the baseUrl value in the docusaurus.config.js file to /my-test-site/ where my-test-site is the name of your repo.

   

7. Commit and push the changes.

Deploy site to GitLab Pages

Now you have the Docusaurus project—locally and on the remote server—with the CI configuration file. It’s time to trigger deployment.

To trigger deployment to GitLab Pages:

1. Change anything in your docs text.

2. Commit and push your changes.

3. Go to Deployments > Pages in GitLab repo.

   

4. Click the site link deployed to GitLab Pages.

   https://ivancheban.gitlab.io/my-test-site

   

Your site is online. The deployment is triggered automatically when you push changes to your repo. You can view the pipeline for each deployment in CI/CD > Pipelines section.