Skip to content

Pages

The pages job gives you the ability to publish a GitLab Pages documentation site, powered by Material for MkDocs.

Configuration

You can opt for using a supported default configuration or create your own integration.

Default configuration

  • Get started by creating mkdocs.yml and docs/index.md files.
  • GitLab Pages has a tutorial on how to write these files.
  • With those in place, a site gets re-published every time the default branch changes. We only auto-publish the default branch for now.
  • Material for MkDocs has a great docs site and offers lots of plugins that should work on our GitLab pages. You may need to install their prerequisites in a before_script step in the pages job.

Non-default configuration

This option is also supported by GitLab Pages. All you need is to generate a public folder with the resulting static website that you want.

The job definition can be like this:

pages:
  stage: build
  image: ubuntu <==== Any base image that you feel comfortable with
  script:
    - apt get ... <==== Install needed dependencies
    - ./tool-of-choice . --output=public <==== Generate the site in the "public" folder.
    - echo "The documentation will be published at $CI_PAGES_URL"
  artifacts:
    paths:
      - public
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

PHPDocs Generators

There are different tools that can generate a full documentation site based on your project's code comments. Some examples for PHP projects could be:

You could automate those tools and make them generate a folder containing the documentation site and then connect it with the previous code.

Customization

To add additional arguments to the mkdocs command, you can use the _MKDOCS_EXTRA variable. For example: _MKDOCS_EXTRA: '--verbose'.

By default the --strict option is set so that the pages job will fail if any "warning" is displayed about bad links. This can be turned off by setting the variable _MKDOCS_STRICT: 0. You can also set allow_failure: true for the pages job, so that incorrect links will end with an amber warning not red failure.

Note that "info" notices regarding incorrect internal #anchor links are not considered as failures so these will not affect the exit code of the job. The details of incorrect links can be written at the start or end of the mkdocs command output so may not be immediately apparent when viewing the log.

If the project has a logo image file logo.png this should be saved in the project's top-level directory, in accordance with the Drupal standard practice. However, the logo to be displayed in the MkDocs documentation site is taken from the /docs folder. This allows for an alternative logo on the documentation site. If there is no logo stored in the /docs folder then the file from the top-level folder will be used. You do not need to keep a duplicate file in both places.