From 93d8db2d586830a4e08f7b48ae72637c50287ed0 Mon Sep 17 00:00:00 2001 From: raisa-1-sect Date: Fri, 11 Apr 2025 19:39:59 +0000 Subject: [PATCH] Revert "Merge branch 'sarahgerman-docs-linting-img-bump' into 'master'" This reverts commit cb72dfa88105b7901e3ca5a72fbf8e854ce21a88 --- .gitlab/ci/docs.gitlab-ci.yml | 2 +- .tool-versions | 2 +- .vale.ini | 2 -- .../cicd_reference_documentation_guide.md | 2 +- doc/development/distribution/_index.md | 2 +- doc/development/integrations/_index.md | 2 +- doc/development/pages/_index.md | 2 +- .../testing_guide/frontend_testing.md | 2 +- doc/development/webhooks.md | 2 +- doc/development/wikis.md | 2 +- package.json | 2 +- scripts/lint-doc.sh | 24 ++++++++++++++----- yarn.lock | 18 +++++++------- 13 files changed, 37 insertions(+), 27 deletions(-) diff --git a/.gitlab/ci/docs.gitlab-ci.yml b/.gitlab/ci/docs.gitlab-ci.yml index 0748fd3526722d..4f6f0e09fd5605 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 35b2affca06a0f..a26512202f9cca 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 0eb17152be78b2..6111cc3a7499c1 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 09264240e11cb5..5710bb61d367fd 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 64216b84ccfc04..f1f81b8adad6b1 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 dc96c1803f0fa4..285c11558ad78d 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 edf41b1b5290b0..b142b3cf4a5009 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 205b73e27df15a..d4aad188df6ae8 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 0df632a5fad8db..db995bf5a4e855 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 e1e7f48b522a9b..1c86c679291f70 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 fc4525377e353b..acfa4d3b143fc7 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 2173d8759bc7d1..75a64ca761ac71 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 af71f979823187..0bb0eb5b00888a 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" -- GitLab