Skip to content

Create handbook development SSoT, sync tools with public handbook

Michael Friedrich requested to merge tools-dev-documentation into main

Problem to solve

The public and internal handbook are in a different documentation state for the local dev setup. Contributors have a hard time figuring out how to run Hugo locally, and make larger changes without waiting for CI/CD pipelines.

CI/CD and linters are not documented.

General Docsy Theme development and dependency update workflows for maintainers are not documented.

TL;DR - contributing and maintaining the handbook is not efficient.

Changes

  1. Create /docs/development documentation as SSoT for all handbooks (their development does not differ much). All changes are tested and verified.
    1. How to run Hugo locally - Docker, and source installation
    2. Dependency updates
    3. Theme development
    4. Redirects
    5. CI/CD
    6. Review apps
    7. Linting
    8. Reviewer Roulette
  2. CI/CD
    1. Bump Hugo image to 0.123.7, markdownlint2 to 0.12.1 (same as other handbooks)
  3. Tools
    1. Add Makefile
    2. Add Vale config
    3. Update default config version to Hugo 0.123.7

related to https://gitlab.com/gitlab-com/content-sites/internal-handbook/-/issues/80

fixes #4 (closed)

Edited by Michael Friedrich

Merge request reports