Skip to main content

Deploy your Docusaurus site to GitLab Pages

You've created a static website using Docusaurus, and now you're ready to publish it.

In this tutorial, you'll add your Docusaurus files to a new GitLab project, and create a .gitlab-ci.yml file to deploy your site to GitLab Pages.

Before you begin​

You must have:

Move your Docusaurus files to your GitLab project​

Using whatever method you prefer, move all the files in your Docusaurus folder into the blank GitLab project on your computer.

For this tutorial, you do not need to copy the top-level folder of your site, just the contents. For example, if your Docusaurus site is in a folder named my-website, do not copy the my-website folder, only its contents. That way, you avoid an unnecessary additional path in your published website.

A blank GitLab project and new Docusaurus site both contain a README file by default. You might get an error that the file already exists. Choose the one you want to keep.

When you're done, commit your files to the GitLab project:

git add .
git commit -m "Add Docusaurus site"
git push

Update the configuration settings​

  1. Open the docusaurus.config.js file.
  2. Set url and baseUrl to match where your site will be served. For example, if your project URL is gitlab.com/my-group/docusaurus-project:
FieldDescription
urlThe Pages domain the site is deployed to. For example, https://my-group.gitlab.io. For more information, see the domain names section in the GitLab docs.
baseUrlUse /.
info

On self-managed GitLab instances, the Pages domain is set by your administrator and may differ from gitlab.io. Ask your administrator, or check Deploy > Pages in your project.

Commit and push your changes.

Create a CI/CD file​

Create a .gitlab-ci.yml file at the root of your project:

.gitlab-ci.yml
image: node:20

stages:
  - deploy

pages:
  stage: deploy
  script:
    - npm ci
    - npm run build
    - rm -rf public
    - mv build public
  artifacts:
    paths:
      - public
  rules:
    - if: '$CI_COMMIT_BRANCH == "main"'

The file does the following:

  • image: node:20: Uses a Node container to build Docusaurus. Swap the version if your project needs a different one (check the package.json engines field or .nvmrc).
  • pages: A GitLab-specific job name that triggers a Pages deployment.
  • npm ci instead of npm install: Installs exactly what's in package-lock.json.
  • npm run build: By default, Docusaurus builds static files into a build/ folder.
  • mv build public: GitLab Pages expects the output in a folder called public. This command renames the folder.
  • artifacts: paths: - public: Specifies the folder to publish.
  • rules: The pipeline only deploys when you push commits to the main branch. If your default or publishing branch has a different name, change this value.

Commit and deploy​

Now you're ready to trigger your first build.

  1. Commit and push the .gitlab-ci.yml file.

  2. In the left sidebar, select Build > Pipelines.

  3. When the pipeline has finished, visit your site at the Pages URL. For example, if your project URL is gitlab.com/my-group/docusaurus-project, the published URL is https://my-group.gitlab.io/docusaurus-project/.

    Alternatively, in the left sidebar, select Deploy > Pages to get a URL for your site.

Troubleshooting​

If your site does not publish as expected, check the following:

  • Go to Build > Pipelines, confirm that the pipeline passed, and address any errors.
  • If the site loads but is unstyled or shows a blank page with 404s for JS and CSS files, check the url or baseUrl value in the docusaurus.config.js file.
  • If your project is private, only authorized users can access the site:
    1. Go to Settings > General and expand Visibility, project features, permissions.
    2. In the Pages section, select Everyone.
    3. Select Save changes.
  • Deploy your Docusaurus site using other providers.
  • Use a custom domain with your Pages site. If you change to a custom domain, remember to update the url value in your docusaurus.config.js file.