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]

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:

• Twitter
• Github

Happy coding!

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

Comments

[Sumit Kharche]

Great Article!

Since Azure Static Web Apps are in preview but you can also deploy Docusaurus on it.

Deploy a Docusaurus App on Azure Static Web Apps

Sumit Kharche ・ Aug 15 '20 ・ 5 min read

#azure #javascript #showdev #beginners

[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.

[Sumit Kharche]

Yeah That's correct.

[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.

[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

[Seanmclem]

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