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
    - node_modules/
    - public/
    - .cache/

  stage: deploy
    - yarn install
    - yarn build:gitlab
        - public
    - 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:

Setting > pages

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! =>

Top comments (6)

sumitkharche profile image
Sumit Kharche
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.

sumitkharche profile image
Sumit Kharche

Yeah That's correct.

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.

stef33560 profile image

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

seanmclem profile image

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