How to deploy Docusaurus v2 on GitLab Pages

Erwan Leboucher — Wed, 23 Dec 2020 08:44:33 +0000

At viafintech, we use docusaurus for our internal documentation. We also use GitLab to host our code and to test it.

GitLab pages is a feature (like Github pages) that allow us to publish a static website from a GitLab repository. You can host plenty of different static site generator like Gatsby, Hugo, Jekyll...

Docusaurus is a documentation site generator created and maintained by Facebook Open Source. Using Markdown, it allowed us to write documentation faster and also to generate clean docs for our RAML files that describe our endpoints.

To generate a docusaurus project, use the project generator:

npx @docusaurus/init@latest init [name] [template]

for my example I will use the classic template, but you can find more details here

npx @docusaurus/init@latest init test-gitlab classic

Now, you should have the project properly generated in the test-gitlab/ folder.

How to setup the gitlab ci

Once you messed up with the docs and you are ready to deploy it.
Create a .gitlab-ci.yml file that will allow us to create an artifact containing the static resources to allow GitLab pages to render your website.

The content of 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:
    - master

And add this script to the package.json to allow docusaurus to build the file into the public/ folder:

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

How to access it

Now you are set to deploy your website, push your newly added stuff and your documentation site should be available. Go on GitLab > Settings > Pages and you will be able to see the link of your page, For me: https://eleboucher.gitlab.io/test-docs/

Note:
Make sure you set up correct the baseURL in docusaurus.config.js in case your link is not the root path.

If you have any questions, feel free to leave a comment!

Find me on:

Happy coding!

We are hiring! => https://www.viafintech.com/op_software-engineer/

Forem: Erwan Leboucher

How to deploy Docusaurus v2 on GitLab Pages

How to setup the gitlab ci

How to access it