Move development/contributing docs to docsy theme repo (embed via...

Move development/contributing docs to docsy theme repo (embed via /docs/development), sync tools with other handbooks (hugolint, Hugo v0.123.7, CI/CD components)

.gitlab-ci.yml

@@ -35,7 +35,7 @@ stages:
   - export AWS_SESSION_TOKEN="${STS[2]}"
 
 include:
-  - template: Security/Secret-Detection.gitlab-ci.yml
+  - component: gitlab.com/components/secret-detection/secret-detection@~latest
   - component: gitlab.com/gitlab-org/components/danger-review/danger-review@~latest
 
 default:
@@ -106,6 +106,7 @@ pages-review:
     name: review/$CI_COMMIT_REF_SLUG
     # There is no predefined CI variable that is formatted quite right
     # neither $CI_PAGES_URL nor $CI_JOB_URL have /-/ directly after the hostname
+    # TODO @dnsmichi improve and make review apps work https://gitlab.com/groups/gitlab-com/content-sites/-/epics/11 
     url: https://gitlab-com.gitlab.io/-/content-sites/handbook/-/jobs/$CI_JOB_ID/artifacts/public/
     on_stop: stop-pages-review
   variables:
@@ -129,12 +130,17 @@ stop-pages-review:
 
 pages:
   extends: [.hugo]
+  environment:
+    # tracking DORA deployment frequency
+    name: production
+    deployment_tier: production
   rules:
     # Only run the deploy on the default branch. If you want to deploy from Merge Request branches,
     # you can use Review Apps: https://docs.gitlab.com/ee/ci/review_apps
     - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
     - if: '$CI_PIPELINE_SOURCE == "schedule" && $SCHEDULED_DEPLOY == "true"'
 
+# TODO @dnsmichi: What does this job do?
 deploy s3:
     stage: deploy
     needs:
@@ -213,7 +219,7 @@ hugolint:
     - if: $CI_PIPELINE_SOURCE == 'merge_request_event'
       allow_failure: true
   image:
-    name: registry.gitlab.com/fforster/hugolint:main
+    name: registry.gitlab.com/gitlab-com/content-sites/handbook-tools/hugolint:latest
   script:
     - hugolint linkcheck --format=json $(find content -type f -name '*.md' | grep -v ' ') >linkcheck.json
     - hugolint missinglinks --num 30 $(find content -name '*.md' | grep -v ' ') >missinglinks.txt 2>/dev/null

.gitlab/CODEOWNERS

@@ -623,7 +623,7 @@
 /go.mod @gitlab-com/content-sites @gitlab-com/content-sites/handbook-backend
 /go.sum @gitlab-com/content-sites @gitlab-com/content-sites/handbook-backend
 /layouts/ @gitlab-com/content-sites @gitlab-com/content-sites/handbook-backend @gitlab-com/egroup
-/LICENCE @gitlab-com/content-sites @gitlab-com/content-sites/handbook-backend @gitlab-com/egroup
+/LICENSE @gitlab-com/content-sites @gitlab-com/content-sites/handbook-backend @gitlab-com/egroup
 /package-lock.json @gitlab-com/content-sites @gitlab-com/content-sites/handbook-backend
 /package.json @gitlab-com/content-sites @gitlab-com/content-sites/handbook-backend
 /README.md @gitlab-com/content-sites @gitlab-com/content-sites/handbook-backend @gitlab-com/egroup

LICENCE → LICENSE

-Copyright (c) 2011-2022 GitLab B.V.
+Copyright (c) 2011-present GitLab B.V.
 
 With regard to the GitLab Software:
 
@@ -20,7 +20,7 @@ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 THE SOFTWARE.
 
-For all third party components incorporated into the GitLab Software, those 
-components are licensed under the original license provided by the owner of the 
+For all third party components incorporated into the GitLab Software, those
+components are licensed under the original license provided by the owner of the
 applicable component.
 

README.md

@@ -5,180 +5,8 @@
 Welcome to the GitLab Handbook.  This repository contains all of the content
 for the Handbook on <https://handbook.gitlab.com/>.
 
-The handbook site uses [Hugo](https://gohugo.io/) for static page generation
-from Markdown.
+## Development and contribution guidelines
 
-The handbook uses a base theme called [Docsy](https://www.docsy.dev/). A custom theme override is located in the [Docsy GitLab Theme](https://gitlab.com/gitlab-com/content-sites/docsy-gitlab) project and automatically included in the handbook setup.
-
-## Requirements
-
-The recommended and documented way for building the handbook locally is using Docker or a compatible container runtime.
-
-- Command line: git, wget (for syncing data)
-- Docker or compatible runtime (for running the Hugo environment in a container)
-    - On [macOS](https://handbook.gitlab.com/handbook/tools-and-tips/mac/#docker-desktop): Docker Desktop, Rancher Desktop, etc.
-    - On [Linux](https://handbook.gitlab.com/handbook/tools-and-tips/linux/#production-engineering): Docker engine, Podman, etc.
-
-## Getting started
-
-1. [Clone this repository](#clone-this-repository)
-1. [Set up the repository](#set-up-the-repository)
-1. [Running Hugo](#running-hugo)
-1. [Parameters for Hugo](#parameters-for-hugo)
-1. [Build static files](#build-static-files)
-1. [Linting content](#linting-content)
-
-### Clone this repository
-
-Cloning the repository allows you to manually edit the handbook locally. If you prefer to use the Web IDE, please continue reading the [editing the handbook](https://handbook.gitlab.com/handbook/editing-handbook/) documentation.
-
-We recommend using git to clone the repository and then editing the handbook with a text editor such
-as [Visual Studio Code](https://code.visualstudio.com/), [Typora](https://typora.io/),
-[Nova](https://nova.app/) or [Sublime](https://www.sublimetext.com/) to name a few.
-
-Clone the repo with HTTPS or SSH:
-
-```shell
-# HTTPS
-git clone https://gitlab.com/gitlab-com/content-sites/handbook.git
-
-# SSH
-git clone git@gitlab.com:gitlab-com/content-sites/handbook.git
-```
-
-### Set up the repository
-
-After cloning the repository, sync the required data files from the
-data file location (currently the `www-gitlab-com` repository).  Without this
-step, the handbook cannot be run locally.
-
-Open a terminal, navigate into the cloned handbook repository path, and run the `sync-data.sh` script.
-
-```shell
-cd handbook
-
-./scripts/sync-data.sh
-```
-
-### Running Hugo
-
-Hugo needs to be run to generate the static files from the handbook markdown content.
-
-You can use the Hugo container to start a locally running instance of the handbook, and verify how your changes look.
-
-The following command starts the Hugo server, using the [`hugomods/hugo` container image](https://hugomods.com/docs/docker/#image-tags).
-The `exts` container image tag is important, as it provides the required SASS/CSS conversion tools.
-
-```sh
-docker run --rm -v $(pwd):$(pwd) -w $(pwd) --network host hugomods/hugo:exts hugo server
-```
-
-This will start the Hugo server listening on `http://localhost:1313`. If that doesn't work, try `http://127.0.0.1:1313`. It may take a couple of minutes to load the first time.
-
-You can also start a new container, and run the commands with Hugo manually.
-
-```sh
-docker run --rm -it -v $(pwd):$(pwd) -w $(pwd) --network host hugomods/hugo:exts sh
-
-hugo server
-
-ctrl+d # to quit
-```
-
-### Parameters for Hugo
-
-The handbook is huge, and by default, the `hugo server` command loads everything to memory.
-
-The following options for the `hugo` command can be helpful for debugging or otherwise running locally:
-
-- `--environment=production`: generate a production build (asset minification, checksums, etc)
-  - **Note:** `hugo v0.x.x+extended` version must be installed, use `hugo version` to check
-  - **Note:** `npm i` must be run as a prerequisite to install `postcss` and `autoprefixer` dependencies
-- `--renderToDisk`: slower but requires less memory to run. Useful if you have <16GB allocated to docker machine
-- `--verbose`: enables verbose logging output
-- `--templateMetrics` and `--templateMetricsHints`: prints metrics related to how frequently templates are invoked and how much time is being spent evaluating them
-- `--printMemoryUsage`: periodically prints memory usage while the site is building
-
-### Build static files
-
-To render the entire site to disk (and inspect the output in `${PWD}/public`),
-purge the generated files first, and then run Hugo.
-
-```sh
-make clean
-
-docker run --rm -v $(pwd):$(pwd) -w $(pwd) hugomods/hugo:exts hugo
-```
-
-### Linting content
-
-We use [`markdownlint-cli2`](https://github.com/DavidAnson/markdownlint-cli2) and [Vale](https://vale.sh) to enforce
-rules in handbook content.
-
-#### Markdownlint
-
-We use `markdownlint-cli2` in our pipelines with a slightly customized set of rules. Before pushing any changes, you
-should run `markdownlint-cli2` and fix any suggested changes to avoid pipeline failures.
-
-To run `markdownlint-cli2` using Docker, run:
-
-```sh
-docker run --rm -v $(pwd):$(pwd) -w $(pwd) davidanson/markdownlint-cli2 content/**/*.md
-```
-
-#### Vale
-
-We use Vale to warn when some rules from the
-[Handbook Markdown Guide](https://gitlab.com/gitlab-com/content-sites/docsy-gitlab/-/blob/main/content/docs/markdown-guide.md?ref_type=heads#markdown-style-guide-for-the-handbook).
-are broken. Vale is not run in pipelines.
-
-To run Vale using Docker, run:
-
-```sh
-docker run --rm -v $(pwd):$(pwd) -w $(pwd) jdkato/vale content
-```
-
-## Support
-
-For help and support with the development environment, please reach out in the public [#handbook](https://gitlab.slack.com/archives/C81PT2ALD) Slack channel.
-
-If you encounter a problem or bug, please open an issue or MR.
-
-## Contribution guidelines
-
-For contribution guidelines see the [dedicated handbook page](https://handbook.gitlab.com/docs/).
-
-## Architecture
-
-The Markdown files get parsed by Hugo, and converted into static HTML files, including all assets (JS, CSS, images, etc.). The static files are uploaded to GitLab Pages.
-
-### Required development versions
-
-The handbook development environment requires the **extended** version of [Hugo](https://gohugo.io/). The extended version is required for the [Docsy GitLab theme](https://gitlab.com/gitlab-com/content-sites/docsy-gitlab) as we use SASS for generating the CSS stylesheets for the site.  This will also require the installation of Node/NPM.
-
-Additionally, more software is required to develop the handbook:
-
-1. Install Hugo following [their documentation](https://gohugo.io/getting-started/installing).
-1. Install NodeJS through a package manager or [asdf](https://asdf-vm.com/guide/getting-started.html), and run `npm install`.
-1. Install Git, curl, wget for sync scripts.
-1. Install the GitLab CLI for linting jobs.
-1. Install Golang for theme dependency development.
-
-### Theme dependency
-
-The [Docsy GitLab theme](https://gitlab.com/gitlab-com/content-sites/docsy-gitlab) is integrated into the handbook repository through a Go module in [go.mod](https://gitlab.com/gitlab-com/content-sites/docsy-gitlab/-/blob/main/go.mod?ref_type=heads).
-
-### Templates and Partials
-
-Review the Hugo development documentation to learn more.
-
-- https://gohugo.io/templates/introduction/
-- https://gohugo.io/functions/partials/
-
-### CI/CD pipeline
-
-The CI/CD pipeline uses GitLab Pages for Review Apps to preview the changes in the same environment.
-
-#### Reviewer Roulette
-
-The project uses [Reviewer Roulette](https://docs.gitlab.com/ee/development/code_review.html#reviewer-roulette) feature of [`danger-review` CI/CD component](https://gitlab.com/gitlab-org/components/danger-review/-/tree/main).
+For details on how to run the handbook locally, modify the backend configuration,
+add CI/CD and linting jobs, etc., check the handbook development documentation at
+<https://handbook.gitlab.com/docs/>

config/_default/config.yaml

@@ -58,7 +58,11 @@ params:
       - name: "Repository"
         url: "https://gitlab.com/gitlab-com/content-sites/handbook"
         icon: "fa-solid fa-code-branch"
-        desc: "Contribute on GitLab"
+        desc: "GitLab project"
+      - name: "Editing"
+        url: "/docs/development"
+        icon: "fa-solid fa-edit"
+        desc: "Contribute to the handbook"
     developer: []
 
 staticDir:
@@ -121,7 +125,7 @@ module:
   proxy: https://proxy.golang.org
   hugoVersion:
     extended: true
-    min: 0.111
+    min: 0.123
   imports:
   - path: gitlab.com/gitlab-com/content-sites/docsy-gitlab
     disable: false

data/toc.yaml

@@ -85,7 +85,7 @@
   - name: Practical Handbook Edits
     url: /handbook/editing-handbook/practical-handbook-edits
   - name: Edit This Website Locally
-    url: https://gitlab.com/gitlab-com/content-sites/handbook/-/tree/main
+    url: /docs/development
   - name: Handbook Style Guide
     url: /handbook/style-guide
   - name: Content Websites

go.mod

@@ -2,11 +2,9 @@ module gitlab.com/gitlab-com/content-sites/handbook
 
 go 1.19
 
-// 2024-02-23 @dnsmichi require 0.8.0 because of URL anchor regression in 0.9.0
-// Remove when fixed in https://gitlab.com/gitlab-com/content-sites/handbook/-/issues/194
 require github.com/google/docsy v0.9.1
 
 require (
 	github.com/google/docsy/dependencies v0.7.2 // indirect
-	gitlab.com/gitlab-com/content-sites/docsy-gitlab v0.3.14 // indirect
+	gitlab.com/gitlab-com/content-sites/docsy-gitlab v0.3.17 // indirect
 )

go.sum

+github.com/FortAwesome/Font-Awesome v0.0.0-20230327165841-0698449d50f2/go.mod h1:IUgezN/MFpCDIlFezw3L8j83oeiIuYoj28Miwr/KUYo=
 github.com/FortAwesome/Font-Awesome v0.0.0-20240108205627-a1232e345536 h1:LFS9LpoSZYhxQ6clU0NIVbaGR08BlxAs4b+9W+7IGVQ=
 github.com/FortAwesome/Font-Awesome v0.0.0-20240108205627-a1232e345536/go.mod h1:IUgezN/MFpCDIlFezw3L8j83oeiIuYoj28Miwr/KUYo=
 github.com/google/docsy v0.9.1 h1:+jqges1YCd+yHeuZ1BUvD8V8mEGVtPxULg5j/vaJ984=
@@ -7,3 +8,9 @@ github.com/google/docsy/dependencies v0.7.2/go.mod h1:gihhs5gmgeO+wuoay4FwOzob+j
 github.com/twbs/bootstrap v5.2.3+incompatible/go.mod h1:fZTSrkpSf0/HkL0IIJzvVspTt1r9zuf7XlZau8kpcY0=
 gitlab.com/gitlab-com/content-sites/docsy-gitlab v0.3.14 h1:iynu4nSkGM3+l4zl6ohQ0RoYNzFswq2JNouKR0pGoqI=
 gitlab.com/gitlab-com/content-sites/docsy-gitlab v0.3.14/go.mod h1:HlTbTwpFkWbQSCjCUanbNXRx3MmQD0MOkBVc0L0TeS0=
+gitlab.com/gitlab-com/content-sites/docsy-gitlab v0.3.15 h1:kars3M/P6EsRU4A0MWnDqAh1U0Vw0IQCablSgwwxIus=
+gitlab.com/gitlab-com/content-sites/docsy-gitlab v0.3.15/go.mod h1:HlTbTwpFkWbQSCjCUanbNXRx3MmQD0MOkBVc0L0TeS0=
+gitlab.com/gitlab-com/content-sites/docsy-gitlab v0.3.16 h1:MTM1lcidj742fU4iyOpWp2sjWo4akQQSumzwO3klzyQ=
+gitlab.com/gitlab-com/content-sites/docsy-gitlab v0.3.16/go.mod h1:HlTbTwpFkWbQSCjCUanbNXRx3MmQD0MOkBVc0L0TeS0=
+gitlab.com/gitlab-com/content-sites/docsy-gitlab v0.3.17 h1:XKC8o+bPcCJd2SnIj6eqj/y1rvtoqYBGyEKA6P+BhzI=
+gitlab.com/gitlab-com/content-sites/docsy-gitlab v0.3.17/go.mod h1:HlTbTwpFkWbQSCjCUanbNXRx3MmQD0MOkBVc0L0TeS0=

scripts/parse-codequality-report.sh

@@ -2,6 +2,7 @@
 REPORT=markdownlint-cli2-codequality.json
 ERRORS=()
 MSG=""
+REPO_URL="https://gitlab.com/gitlab-com/content-sites/handbook"
 
 generate_message() {
     MSG+="## ⚠️ Pipeline Failure - Linting Errors\n\n"
@@ -20,7 +21,7 @@ generate_table() {
       URL="https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#$ERROR"
       FILE=$(yq ".[$i].location.path" $REPORT -o yaml)
       LINE=$(yq ".[$i].location.lines.begin" $REPORT -o yaml)
-      LOC="https://gitlab.com/gitlab-com/content-sites/handbook/-/blob/$CI_COMMIT_SHA/$FILE#L$LINE"
+      LOC="$REPO_URL/-/blob/$CI_COMMIT_SHA/$FILE#L$LINE"
       ERRORS+=( $ERROR )
       if [[ $ERROR == "Missing CODEOWNER entry" ]]; then
         MSG+="| $ERROR | [$FILE]($LOC) | [$LINE]($LOC) | $DESCRIPTION |  |\n"