Skip to content

Add a script for front matter updates

Sarah German requested to merge frontmatter-script into main

What does this MR do and why?

Adds a script for modifying docs front matter at build time. We need to migrate page titles (h1s in markdown) to front matter title attributes in order to utilize Hugo features.

Docs: https://gohugo.io/content-management/front-matter/

This script will be temporary: when it's time to launch the Hugo site, we can run it against our real docs to update them in bulk. For now, though, we need to leave the source docs alone in order to not interfere with the Nanoc site.

I expect we will need to add more temporary build-time front matter modifications as the project goes on, so ideally this script is easily extendable.

How to set up and validate locally

Numbered steps to set up and validate the change are strongly suggested.

Test the full content post-processing... process:

  1. Check out this branch.
  2. Run REMOVE_BEFORE_CLONE=true make clone-docs-projects. This should now include a step for updating front matter, with output like this:
Expected output 
$ REMOVE_BEFORE_CLONE=true make clone-docs-projects

INFO: Fetching docs content sources...
2023/12/12 14:40:13 [Info] ../gitlab already exists, removing it
2023/12/12 14:40:13 [Info] Fetching gitlab on branch master at commit heads/master
2023/12/12 14:40:48 [Info] Last commit: b8c25dbe3 Merge branch 'phikai-reporter-reviewer-perms-docs' into 'master'
2023/12/12 14:40:48 [Info] ../omnibus-gitlab already exists, removing it
2023/12/12 14:40:48 [Info] Fetching omnibus on branch master at commit heads/master
2023/12/12 14:40:49 [Info] Last commit: df252a9 Merge branch 'update-chef-gem' into 'master'
2023/12/12 14:40:49 [Info] ../gitlab-runner already exists, removing it
2023/12/12 14:40:49 [Info] Fetching runner on branch main at commit heads/main
2023/12/12 14:40:51 [Info] Last commit: 4a7c4b6 Merge branch 'mbradburn-fix-powershell-native-command-error' into 'main'
2023/12/12 14:40:51 [Info] ../charts-gitlab already exists, removing it
2023/12/12 14:40:51 [Info] Fetching charts on branch master at commit heads/master
2023/12/12 14:40:52 [Info] Last commit: 3b2e431 Merge branch 'fix-toolbox-extraEnvFrom' into 'master'
2023/12/12 14:40:52 [Info] ../gitlab-operator already exists, removing it
2023/12/12 14:40:52 [Info] Fetching operator on branch master at commit heads/master
2023/12/12 14:40:53 [Info] Last commit: 9718ec0 Merge branch 'ci-refactor-pipelines-for-vcluster' into 'master'

INFO: Running content update scripts...
Renaming index files in ../gitlab...
Updating front matter in ../gitlab...
Renaming index files in ../omnibus-gitlab...
Updating front matter in ../omnibus-gitlab...
[WARN] No valid YAML front matter found in ../omnibus-gitlab/doc/development/allure-test-report.md.
Renaming index files in ../gitlab-runner...
Updating front matter in ../gitlab-runner...
[WARN] No valid YAML front matter found in ../gitlab-runner/docs/internal/engineering/executor-interface/_index.md.
Renaming index files in ../charts-gitlab...
Updating front matter in ../charts-gitlab...
Renaming index files in ../gitlab-operator...
Updating front matter in ../gitlab-operator...
[WARN] No valid YAML front matter found in ../gitlab-operator/doc/adr/0012-makefile-modifications.md.
[WARN] No valid YAML front matter found in ../gitlab-operator/doc/adr/0001-record-architecture-decisions.md.
[WARN] No valid YAML front matter found in ../gitlab-operator/doc/adr/0014-supported-openshift-versions.md.
[WARN] No valid YAML front matter found in ../gitlab-operator/doc/adr/0003-use-operator-sdk.md.
[WARN] No valid YAML front matter found in ../gitlab-operator/doc/adr/0016-replace-makefile-with-taskfile.md.
[WARN] No valid YAML front matter found in ../gitlab-operator/doc/adr/0006-gitlab-application-versions-supported.md.
[WARN] No valid YAML front matter found in ../gitlab-operator/doc/adr/0005-versioning-of-the-operator.md.
[WARN] No valid YAML front matter found in ../gitlab-operator/doc/adr/0002-use-rh-codebase.md.
[WARN] No valid YAML front matter found in ../gitlab-operator/doc/adr/0004-integration-of-the-gitlab-chart.md.
[WARN] No valid YAML front matter found in ../gitlab-operator/doc/adr/0011-operator-release-process.md.
[WARN] No valid YAML front matter found in ../gitlab-operator/doc/adr/0015-ci-pipelines-in-dev.md.
[WARN] No valid YAML front matter found in ../gitlab-operator/doc/adr/0018-obsolete-gitlab-cr-v1beta1.md.
[WARN] No valid YAML front matter found in ../gitlab-operator/doc/adr/0017-structured-spec-for-gitlab-cr.md.
[WARN] No valid YAML front matter found in ../gitlab-operator/doc/adr/0009-version-tagging.md.
[WARN] No valid YAML front matter found in ../gitlab-operator/doc/adr/0010-ci-environments.md.
[WARN] No valid YAML front matter found in ../gitlab-operator/doc/adr/0007-dependency-on-other-external-components.md.
[WARN] No valid YAML front matter found in ../gitlab-operator/doc/adr/0013-stable-branch-policy.md.
[WARN] No valid YAML front matter found in ../gitlab-operator/doc/adr/0008-operator-scoped-to-namespace.md.
INFO: Content updates complete!

We expect some docs to raise warnings about missing front matter. There are a bunch of markdown files in projects' docs directories that are not normal docs pages (gotta keep things interesting). We'll do something to omit these in #24 (closed). For now I'd like to log them in case anything new and unexpected appears there.

Test the script on its own against a single project:

  1. Reset the gitlab checkout to undo the previous script runs: git -C ../gitlab clean -d -f && git -C ../gitlab reset --hard HEAD
  2. From your project directory, try the new script by itself on the gitlab docs:
find ../gitlab/doc -type f -name "*.md" | xargs go run ./scripts/migration/frontmatter.go
  1. Go take a look at the git diff in gitlab: git -C ../gitlab diff

The diff should be limited to our intended change: remove text in an h1 and move that same text up to front matter.

Merge request acceptance checklist

This checklist encourages us to confirm any changes have been analyzed to reduce risks in quality, performance, reliability, security, and maintainability.

Edited by Sarah German

Merge request reports