diff --git a/.gitlab/ci/docs.gitlab-ci.yml b/.gitlab/ci/docs.gitlab-ci.yml index 0748fd3526722ddf0e6cbcf32c9b9b08d6ba701d..4f6f0e09fd5605ab360d6354059b1787e8839662 100644 --- a/.gitlab/ci/docs.gitlab-ci.yml +++ b/.gitlab/ci/docs.gitlab-ci.yml @@ -35,7 +35,7 @@ review-docs-cleanup: .docs-markdown-lint-image: # When updating the image version here, update it in /scripts/lint-doc.sh too. - image: ${REGISTRY_HOST}/${REGISTRY_GROUP}/technical-writing/docs-gitlab-com/lint-markdown:alpine-3.21-vale-3.11.2-markdownlint2-0.17.2-lychee-0.18.1 + image: ${REGISTRY_HOST}/${REGISTRY_GROUP}/technical-writing/docs-gitlab-com/lint-markdown:alpine-3.21-vale-3.9.3-markdownlint2-0.17.1-lychee-0.18.0 docs-lint markdown: extends: diff --git a/.tool-versions b/.tool-versions index 35b2affca06a0f5a0779e050e399378484ab5ecd..a26512202f9cca570f2c81d09ff6fe5adc2e846c 100644 --- a/.tool-versions +++ b/.tool-versions @@ -6,4 +6,4 @@ redis 7.0.14 ruby 3.3.7 3.2.4 rust 1.73.0 yarn 1.22.19 -vale 3.11.2 +vale 3.9.3 diff --git a/.vale.ini b/.vale.ini index 0eb17152be78b217b955ffda657fe083cdb50eb2..6111cc3a7499c174bdc039fe28243dbb421beaa7 100644 --- a/.vale.ini +++ b/.vale.ini @@ -5,8 +5,6 @@ StylesPath = doc/.vale MinAlertLevel = suggestion -IgnoredScopes = code, text.frontmatter.redirect_to - [*.md] BasedOnStyles = gitlab_base, gitlab_docs diff --git a/doc/development/cicd/cicd_reference_documentation_guide.md b/doc/development/cicd/cicd_reference_documentation_guide.md index 09264240e11cb527523fc75bbfc340a8ab564277..5710bb61d367fd1ef377bdcdf3cffde1568405e4 100644 --- a/doc/development/cicd/cicd_reference_documentation_guide.md +++ b/doc/development/cicd/cicd_reference_documentation_guide.md @@ -2,7 +2,7 @@ stage: Verify group: Pipeline Authoring info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. -title: Documenting pipeline configuration keywords +title: Documenting the `.gitlab-ci.yml` keywords --- The [CI/CD YAML syntax reference](../../ci/yaml/_index.md) uses a standard style to make it easier to use and update. diff --git a/doc/development/distribution/_index.md b/doc/development/distribution/_index.md index 64216b84ccfc04a52468a173464916a03086f2dc..f1f81b8adad6b1a56b2a5ff9f83f6c4e6052b6dd 100644 --- a/doc/development/distribution/_index.md +++ b/doc/development/distribution/_index.md @@ -2,7 +2,7 @@ stage: Systems group: Distribution info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. -description: Development guidelines for Distribution +description: GitLab's development guidelines for Distribution title: Contribute to GitLab Distribution --- diff --git a/doc/development/integrations/_index.md b/doc/development/integrations/_index.md index dc96c1803f0fa4cb28587bced675c21b55f44e0b..285c11558ad78d85d2b7d30463780f36e330fe4a 100644 --- a/doc/development/integrations/_index.md +++ b/doc/development/integrations/_index.md @@ -2,7 +2,7 @@ stage: Foundations group: Import and Integrate info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. -description: Development guidelines for Integrations +description: GitLab's development guidelines for Integrations title: Integration development guidelines --- diff --git a/doc/development/pages/_index.md b/doc/development/pages/_index.md index edf41b1b5290b05781093f59e8ea3f5e84cd4935..b142b3cf4a5009edae99313a3b2f5b11a0615dc9 100644 --- a/doc/development/pages/_index.md +++ b/doc/development/pages/_index.md @@ -2,7 +2,7 @@ stage: Plan group: Knowledge info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. -description: Development guidelines for GitLab Pages +description: GitLab's development guidelines for GitLab Pages title: Contribute to GitLab Pages development --- diff --git a/doc/development/testing_guide/frontend_testing.md b/doc/development/testing_guide/frontend_testing.md index 205b73e27df15a3eb62e649335d254b61f36fd15..d4aad188df6ae83413f52a7cf7a622d9a8eb4b3f 100644 --- a/doc/development/testing_guide/frontend_testing.md +++ b/doc/development/testing_guide/frontend_testing.md @@ -42,7 +42,7 @@ See also the issue for [support running Jest tests in browsers](https://gitlab.c ### Debugging Jest tests -Running `yarn jest-debug` runs Jest in debug mode, allowing you to debug/inspect as described in the [Jest documentation](https://jestjs.io/docs/troubleshooting#tests-are-failing-and-you-don-t-know-why). +Running `yarn jest-debug` runs Jest in debug mode, allowing you to debug/inspect as described in the [Jest docs](https://jestjs.io/docs/troubleshooting#tests-are-failing-and-you-don-t-know-why). ### Timeout error diff --git a/doc/development/webhooks.md b/doc/development/webhooks.md index 0df632a5fad8db6b0f9c7b275472b2e2c895116c..db995bf5a4e85579c25b15d4fc52e2a637479023 100644 --- a/doc/development/webhooks.md +++ b/doc/development/webhooks.md @@ -2,7 +2,7 @@ stage: Foundations group: Import and Integrate info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. -description: Development guidelines for webhooks +description: GitLab's development guidelines for webhooks title: Webhooks developer guide --- diff --git a/doc/development/wikis.md b/doc/development/wikis.md index e1e7f48b522a9bfc4fdf522b0de3b5333bf474af..1c86c679291f7058aadbc39432f568725dbaf6e7 100644 --- a/doc/development/wikis.md +++ b/doc/development/wikis.md @@ -2,7 +2,7 @@ stage: Plan group: Knowledge info: Any user with at least the Maintainer role can merge updates to this content. For details, see https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review. -description: Development guidelines for Wikis +description: GitLab's development guidelines for Wikis title: Wikis development guidelines --- diff --git a/package.json b/package.json index fc4525377e353b3424d992690a3220a78e4c91b5..acfa4d3b143fc7f4ba31a802ee7be350126e66cf 100644 --- a/package.json +++ b/package.json @@ -295,7 +295,7 @@ "jest-jasmine2": "^29.7.0", "jest-junit": "^12.3.0", "jest-util": "^29.7.0", - "markdownlint-cli2": "^0.17.2", + "markdownlint-cli2": "^0.17.1", "miragejs": "^0.1.40", "mock-apollo-client": "1.2.0", "nodemon": "^2.0.19", diff --git a/scripts/lint-doc.sh b/scripts/lint-doc.sh index 2173d8759bc7d18a78228637c758f058fe8659a2..75a64ca761ac7196f2cf1a3742bb7029919a7af3 100755 --- a/scripts/lint-doc.sh +++ b/scripts/lint-doc.sh @@ -61,7 +61,7 @@ then # shellcheck disable=2059 printf "${COLOR_RED}ERROR: The number of README.md files has changed!${COLOR_RESET} Use index.md instead of README.md.\n" >&2 printf "If removing a README.md file, update NUMBER_READMES in lint-doc.sh.\n" >&2 - printf "https://docs.gitlab.com/development/documentation/site_architecture/folder_structure/#work-with-directories-and-files\n" + printf "https://docs.gitlab.com/ee/development/documentation/site_architecture/folder_structure.html#work-with-directories-and-files\n" ((ERRORCODE++)) fi @@ -76,7 +76,7 @@ then # shellcheck disable=2059 printf "${COLOR_RED}ERROR: The number of directory names containing dashes has changed!${COLOR_RESET} Use underscores instead of dashes for the directory names.\n" >&2 printf "If removing a directory containing dashes, update NUMBER_DASHES in lint-doc.sh.\n" >&2 - printf "https://docs.gitlab.com/development/documentation/site_architecture/folder_structure/#work-with-directories-and-files\n" + printf "https://docs.gitlab.com/ee/development/documentation/site_architecture/folder_structure.html#work-with-directories-and-files\n" ((ERRORCODE++)) fi @@ -91,7 +91,7 @@ then # shellcheck disable=2059 printf "${COLOR_RED}ERROR: The number of filenames containing dashes has changed!${COLOR_RESET} Use underscores instead of dashes for the filenames.\n" >&2 printf "If removing a file containing dashes, update the filename NUMBER_DASHES in lint-doc.sh.\n" >&2 - printf "https://docs.gitlab.com/development/documentation/site_architecture/folder_structure/#work-with-directories-and-files\n" + printf "https://docs.gitlab.com/ee/development/documentation/site_architecture/folder_structure.html#work-with-directories-and-files\n" ((ERRORCODE++)) fi @@ -104,7 +104,7 @@ if echo "${FIND_UPPERCASE_DIRS}" | grep . &>/dev/null then # shellcheck disable=2059 printf "${COLOR_RED}ERROR: Found one or more directories with an uppercase letter in their name!${COLOR_RESET} Use lowercase instead of uppercase for the directory names.\n" >&2 - printf "https://docs.gitlab.com/development/documentation/site_architecture/folder_structure/#work-with-directories-and-files\n" >&2 + printf "https://docs.gitlab.com/ee/development/documentation/site_architecture/folder_structure.html#work-with-directories-and-files\n" >&2 echo "${FIND_UPPERCASE_DIRS}" ((ERRORCODE++)) fi @@ -133,11 +133,23 @@ if echo "${FIND_UPPERCASE_FILES}" | grep . &>/dev/null then # shellcheck disable=2059 printf "${COLOR_RED}ERROR: Found one or more file names with an uppercase letter in their name!${COLOR_RESET} Use lowercase instead of uppercase for the file names.\n" >&2 - printf "https://docs.gitlab.com/development/documentation/site_architecture/folder_structure/#work-with-directories-and-files\n" >&2 + printf "https://docs.gitlab.com/ee/development/documentation/site_architecture/folder_structure.html#work-with-directories-and-files\n" >&2 echo "${FIND_UPPERCASE_FILES}" ((ERRORCODE++)) fi +FIND_ALL_DOCS_DIRECTORIES=$(find doc -type d) +# shellcheck disable=2059 +printf "${COLOR_GREEN}INFO: Checking for documentation path clashes...${COLOR_RESET}\n" +for directory in $FIND_ALL_DOCS_DIRECTORIES; do + # Markdown files should not have the same path as a directory with an index.md file in it + if [[ -f "${directory}.md" ]] && [[ -f "${directory}/index.md" ]]; then + # shellcheck disable=2059 + printf "${COLOR_YELLOW}WARNING: File ${directory}.md clashes with file ${directory}/index.md!${COLOR_RESET} " + printf "For more information, see https://gitlab.com/gitlab-org/gitlab-docs/-/issues/1792.\n" + fi +done + # Run Vale and Markdownlint only on changed files. Only works on merged results # pipelines, so first checks if a merged results CI variable is present. If not present, # runs test on all files. @@ -183,7 +195,7 @@ function run_locally_or_in_container() { local cmd=$1 local args=$2 local files=$3 - local registry_url="registry.gitlab.com/gitlab-org/technical-writing/docs-gitlab-com/lint-markdown:alpine-3.21-vale-3.11.2-markdownlint2-0.17.2-lychee-0.18.1" + local registry_url="registry.gitlab.com/gitlab-org/technical-writing/docs-gitlab-com/lint-markdown:alpine-3.21-vale-3.9.3-markdownlint2-0.17.1-lychee-0.18.0" if hash "${cmd}" 2>/dev/null then diff --git a/yarn.lock b/yarn.lock index af71f979823187b3e347ddca343ed8af96578214..0bb0eb5b00888a6e4ac637a23f311cf5dd1847ce 100644 --- a/yarn.lock +++ b/yarn.lock @@ -10423,22 +10423,22 @@ markdownlint-cli2-formatter-default@0.0.5: resolved "https://registry.yarnpkg.com/markdownlint-cli2-formatter-default/-/markdownlint-cli2-formatter-default-0.0.5.tgz#b8fde4e127f9a9c0596e6d45eed352dd0aa0ff98" integrity sha512-4XKTwQ5m1+Txo2kuQ3Jgpo/KmnG+X90dWt4acufg6HVGadTUG5hzHF/wssp9b5MBYOMCnZ9RMPaU//uHsszF8Q== -markdownlint-cli2@^0.17.2: - version "0.17.2" - resolved "https://registry.yarnpkg.com/markdownlint-cli2/-/markdownlint-cli2-0.17.2.tgz#8d3dc2637fae42cea01fe3bf218501cbf33a7cd5" - integrity sha512-XH06ZOi8wCrtOSSj3p8y3yJzwgzYOSa7lglNyS3fP05JPRzRGyjauBb5UvlLUSCGysMmULS1moxdRHHudV+g/Q== +markdownlint-cli2@^0.17.1: + version "0.17.1" + resolved "https://registry.yarnpkg.com/markdownlint-cli2/-/markdownlint-cli2-0.17.1.tgz#4455105fe5d75821597779f7a442ce5c5ce0fede" + integrity sha512-n1Im9lhKJJE12/u2N0GWBwPqeb0HGdylN8XpSFg9hbj35+QalY9Vi6mxwUQdG6wlSrrIq9ZDQ0Q85AQG9V2WOg== dependencies: globby "14.0.2" js-yaml "4.1.0" jsonc-parser "3.3.1" - markdownlint "0.37.4" + markdownlint "0.37.3" markdownlint-cli2-formatter-default "0.0.5" micromatch "4.0.8" -markdownlint@0.37.4: - version "0.37.4" - resolved "https://registry.yarnpkg.com/markdownlint/-/markdownlint-0.37.4.tgz#dd58c4a13b798d4702438e5f7fd587a219f753f6" - integrity sha512-u00joA/syf3VhWh6/ybVFkib5Zpj2e5KB/cfCei8fkSRuums6nyisTWGqjTWIOFoFwuXoTBQQiqlB4qFKp8ncQ== +markdownlint@0.37.3: + version "0.37.3" + resolved "https://registry.yarnpkg.com/markdownlint/-/markdownlint-0.37.3.tgz#061ac5462e97fedc7a96aaac5c132885e4161bfd" + integrity sha512-eoQqH0291YCCjd+Pe1PUQ9AmWthlVmS0XWgcionkZ8q34ceZyRI+pYvsWksXJJL8OBkWCPwp1h/pnXxrPFC4oA== dependencies: markdown-it "14.1.0" micromark "4.0.1"