In this article, I explain how to publish a Docusaurus site to GitLab Pages using a CI configuration file. This is an alternative way to deploy the Docusaurus site on your company GitLab or your private GitLab account.
The goal is to deploy or publish your Docusaurus site to GitLab Pages. I use this example Docusaurus site from this article.
Table of Contents
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:
Go to this link to create an empty repo: https://gitlab.com/projects/new#blank_project
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.gitwhere 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 main4. 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 main8. 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:
- main5. 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.
Komentarze