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.
.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
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
"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/
Make sure you set up correct the
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:
We are hiring! => https://www.viafintech.com/op_software-engineer/
Top comments (6)
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
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.
Yeah That's correct.
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.
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
I was literally just struggling with this last night. Finally got it working. This should help with the CI, thanks!