Documentation: Fix and enable linting to require language on Markdown fenced code blocks #17780
Open
Description
Community Note
- Please vote on this issue by adding a 👍 reaction to the original issue to help the community and maintainers prioritize this request
- Please do not leave "+1" or other comments that do not add relevant new information or questions, they generate extra noise for issue followers and do not help prioritize the request
- If you are interested in working on this issue or have submitted a pull request, please leave a comment
Description
Adding the language to a fenced code block has advantages including applying correct syntax highlighting in editors and Terraform documentation. In addition, it helps tooling such as terrafmt, which we use to lint and format Terraform code in our documentation identify relevant code blocks.
This can be checked for using markdownlint using rule MD040.
MD040 is currently disabled in .markdownlint.yml
For contribution documentation, markdownlint can be executed using make docs-lint.
For resource and data source documentation, markdownlint checks are executed by GitHub Actions. Locally, it can be executed using act by running act -W .github/workflows/website.yml -j markdown-lint.
Example Reports
$ act -W .github/workflows/website.yml -j markdown-lint
...
| website/docs/d/availability_zones.html.markdown:62 MD040/fenced-code-language Fenced code blocks should have a language specified [Context: "```"]
| website/docs/d/network_interface.html.markdown:65 MD040/fenced-code-language Fenced code blocks should have a language specified [Context: "```"]
| website/docs/guides/version-3-upgrade.html.md:228 MD040/fenced-code-language Fenced code blocks should have a language specified [Context: "```"]
| website/docs/guides/version-3-upgrade.html.md:256 MD040/fenced-code-language Fenced code blocks should have a language specified [Context: "```"]
| website/docs/guides/version-3-upgrade.html.md:309 MD040/fenced-code-language Fenced code blocks should have a language specified [Context: "```"]
| website/docs/guides/version-3-upgrade.html.md:349 MD040/fenced-code-language Fenced code blocks should have a language specified [Context: "```"]
| website/docs/guides/version-3-upgrade.html.md:502 MD040/fenced-code-language Fenced code blocks should have a language specified [Context: "```"]
| website/docs/guides/version-3-upgrade.html.md:669 MD040/fenced-code-language Fenced code blocks should have a language specified [Context: "```"]
| website/docs/guides/version-3-upgrade.html.md:676 MD040/fenced-code-language Fenced code blocks should have a language specified [Context: "```"]
| website/docs/r/accessanalyzer_analyzer.html.markdown:59 MD040/fenced-code-language Fenced code blocks should have a language specified [Context: "```"]
| website/docs/r/acm_certificate.html.markdown:151 MD040/fenced-code-language Fenced code blocks should have a language specified [Context: "```"]
| website/docs/r/acmpca_certificate_authority.html.markdown:161 MD040/fenced-code-language Fenced code blocks should have a language specified [Context: "```"]
| website/docs/r/ami.html.markdown:119 MD040/fenced-code-language Fenced code blocks should have a language specified [Context: "```"]
| website/docs/r/api_gateway_account.html.markdown:91 MD040/fenced-code-language Fenced code blocks should have a language specified [Context: "```"]
| website/docs/r/api_gateway_api_key.html.markdown:47 MD040/fenced-code-language Fenced code blocks should have a language specified [Context: "```"]
| website/docs/r/api_gateway_base_path_mapping.html.markdown:57 MD040/fenced-code-language Fenced code blocks should have a language specified [Context: "```"]
| website/docs/r/api_gateway_base_path_mapping.html.markdown:63 MD040/fenced-code-language Fenced code blocks should have a language specified [Context: "```"]
| website/docs/r/api_gateway_client_certificate.html.markdown:43 MD040/fenced-code-language Fenced code blocks should have a language specified [Context: "```"]
| website/docs/r/api_gateway_documentation_part.html.markdown:62 MD040/fenced-code-language Fenced code blocks should have a language specified [Context: "```"]
...Definition of Done
MD040removed from disabled list in.markdownlint.yml- Reports via
make docs-lintandact -W .github/workflows/website.yml -j markdown-lintare addressed - CI testing passes with linter enabled