DEV Community

Erwan Leboucher
Erwan Leboucher

Posted on

How to deploy Docusaurus v2 on GitLab Pages

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]
Enter fullscreen mode Exit fullscreen mode

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

npx @docusaurus/init@latest init test-gitlab classic
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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",
Enter fullscreen mode Exit fullscreen mode

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/

Setting > pages

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/

Top comments (6)

Collapse
 
sumitkharche profile image
Sumit Kharche
Collapse
 
eleboucher profile image
Erwan Leboucher

Thanks !

Cool I didn’t know about azure static web app! Thanks for the info!
We use gitlab pages because we can restrict access to the site with the gitlab account which is pretty handy if you want your docs to stay internal.

Collapse
 
sumitkharche profile image
Sumit Kharche

Yeah That's correct.

Collapse
 
umairhussain profile image
Umair Hussain Siddiqui

Thanks for this article, I'm collecting various gitlab projects on deployment, also have go-through a blog that was stating using GitLab to deploy apps on Cloudways platform. Deployment through Git does resolves the problem of version control and enables better collaboration between the multiple development teams.

Collapse
 
stef33560 profile image
Stef

Quite an "old" (2yo) article but I don't understand the need of caching folder .cache, since this folder is located in node_modules (already cached).

Caching public/ folder may also appear a bit strange since the aim of the build is to generate it.

Last, a forgotten detail, --out-dir public is to link with artifact path :) it's ok when yarn builds in the same folder at the root of the project, otherwise we've got to play with folders (i.e "../public") and that shall be a pain

Collapse
 
seanmclem profile image
Seanmclem

I was literally just struggling with this last night. Finally got it working. This should help with the CI, thanks!