Docusaurus Component

This component will produce a static HTML export of your Markdown files. The export can be either published to GitLab pages or released as web server container.

See a list of available configuration options.

Usage

• Create a docusaurus.config.ts and sidebars.ts in folder .
• Create a multiple Markdown files in folder docs
• Optionally install custom Docusaurus npm packages during the build with extra-packages
• Create GitLab pipeline file .gitlab-ci.yml:
• Configure (GitLab Pages Access Control)

include:
- component: $CI_SERVER_FQDN/xrow-public/ci-tools/common@stable
  inputs:
    proxy: true
- component: $CI_SERVER_FQDN/xrow-public/ci-tools/workflow@stable
- component: $CI_SERVER_FQDN/xrow-public/ci-tools/semantic-release@stable
- component: $CI_SERVER_FQDN/xrow-public/ci-tools/lint-markdown@stable
- component: $CI_SERVER_FQDN/xrow-public/ci-tools/docusaurus@stable

Custom Theme Package

Set extra-packages when your Docusaurus site uses a theme or plugin shipped as an npm package. Packages are installed before the Docusaurus build, so they can provide assets such as logos, stylesheets, and theme overrides referenced from docusaurus.config.ts.

Set registry on a package when one extra package must be installed from a dedicated npm registry instead of the global npm default or package-proxy.

include:
- component: $CI_SERVER_FQDN/xrow-public/ci-tools/docusaurus@stable
  inputs:
    extra-packages:
      - package: "@example/docusaurus-theme"
        version: "1.2.3"
        registry: https://nexus.example.com/repository/npm/

Package Proxy

Set the common component variable CI_NPM_PACKAGE_PROXY when npm packages must be installed through a registry proxy such as Nexus. The Docusaurus package-proxy input overrides the global value for one build. The component configures npm with the proxy registry before it creates and builds the Docusaurus project.

include:
- component: $CI_SERVER_FQDN/xrow-public/ci-tools/docusaurus@stable
  inputs:
    package-proxy: https://nexus.example.com/repository/npm-proxy/

Versioned Documentation

Set preserved-versions to build Docusaurus docs versions from Git tags. The component fetches tags, filters semantic version tags, creates Docusaurus versions from the selected tag contents, then restores the current branch docs as the latest documentation.

include:
- component: $CI_SERVER_FQDN/xrow-public/ci-tools/docusaurus@stable
  inputs:
    preserved-versions:
      - max-major: 2
        max-minor: 5

max-major keeps the newest major release lines. If it is unset, all major lines are preserved. max-minor keeps the newest minor release lines per selected major. If it is unset, all minor lines are preserved. The default [] disables version generation.

Built-in Components

Also see common built-in components.

Changelog

• <Changelog url="https://gitlab.com/api/v4/projects/group%2Fproject/releases?per_page=10">Changelog</Changelog> MDX component to render GitLab releases from the CORS-enabled releases API
• <Changelog url="https://gitlab.com/group/project/-/releases.atom">Changelog</Changelog> MDX component to render a GitLab releases Atom feed
• Atom feeds are still supported for same-origin or CORS-enabled feed URLs
• The Changelog component is packaged as @xrow/docusaurus-changelog, published to npmjs.com on semver tags when NPM_TOKEN is configured, and registered automatically during the Docusaurus build

GitLab configuration helpers

• @xrow/docusaurus-gitlab exports a gitlab helper object with gitLabPagesUrl, gitLabTitle, gitLabTagline, and gitlabEditUrl for Docusaurus configuration files that run in GitLab CI
• gitlab.gitLabPagesUrl() returns the Docusaurus url and baseUrl values for GitLab Pages
• gitlab.gitlabEditUrl() builds edit links for the current GitLab project and default branch

Inputs

Name	Description	Default	Type
---	---	---	---
dependencies	The dependencies that this job depends on.	[]	array
export-container-enabled	Export to registry container	false	boolean
extra-packages	Additional npm packages to install before the Docusaurus build. Each item has package, version, and optional registry.	[]	array
image	Image of Docusaurus to use	${CI_TOOLS_REPO}/docusaurus:${CI_TOOLS_COMPONENT_VERSION}	string
name	Name of the documentation	documentation	string
needs	The jobs that this job depends on.	[]	array
package-proxy	npm package registry proxy for Docusaurus dependencies. Leave empty to use npm defaults.		string
path	Path to markdown files	docs	string
preserved-versions	Docusaurus docs versions to preserve. Use [] to disable, or set max-major/max-minor.	[]	array
rules	Rules for the build job	[{"if":"$CI_PIPELINE_SOURCE == \"schedule\"","when":"never"},{"when":"on_success"}]	array
rules-release	Export to GitLab pages	[{"if":"$CI_PIPELINE_SOURCE == \"schedule\"","when":"never"},{"if":"$CI_COMMIT_TAG =~ $CI_PATTERN_SEMVER","when":"on_success"},{"when":"never"}]	array
stage	The pipeline stage that the jobs belongs to.	build	string
tags	The runners that this job depends on.	[]	array