Skip to content

Pages

The pages job gives you the ability to publish a GitLab Pages documentation site. We have officially standardized on the solution powered by Material for MkDocs.

You can opt for using a supported default configuration (MkDocs is our default), or create your own integration.

Default configuration - MkDocs

Setup:

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

Following the above, we could have:

mkdocs.yml

site_name: 'PROJECT NAME - Documentation'
site_url: 'https://project.pages.drupalcode.org/PROJECT_NAME/'
repo_url: https://git.drupalcode.org/project/PROJECT_NAME
repo_name: drupal/PROJECT_NAME
edit_uri: /-/edit/main/docs/
theme:
  name: material
  logo: logo.png
  favicon: logo.png
nav:
  - Home: 'index.md'
  - Get started:
      - Contribute: 'info/contribute.md'
plugins:
  - search
  - privacy:
      enabled: !ENV [CI, false]

docs/index.md

# PROJECT NAME

This is the entry point to the documentation site.

docs/info/contribute.md

# Contribute

This is how you contribute to the project...

By having those files in the repo, a new documentation site will be automatically generated at https://project.pages.drupalcode.org/PROJECT_NAME.

Unique domain setting

You can go to Deploy > Pages > Domains & settings and select User unique domain or not depending on the format of URL that you want or need for the documentation site:

  • Off: https://project.pages.drupalcode.org/PROJECT_NAME
  • On: https://PROJECT-NAME-123456.pages.drupalcode.org

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.

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.

Examples

You can find some projects using this feature by searching for projects with the mkdocs.yml file: search