Enhancement Proposal: Improve Code Block Language Specifiers Across Documentation
- Dominant language
- HTML
- Stars
- 5.1k
- Forks
- 1.3k
- PR merge metrics
- No merged PRs in 30d
Description
**Background & Validation:**
Several documentation files in the repository—including blog articles, concept guides, and code samples—contain fenced code blocks that do **not** specify their language, or use inconsistent language tags (such as missing specifiers for `go`, `bash`, `yaml`, etc.). This issue appears commonly in:
- [`docs/blog/articles/getting-started-blog-p1.md`](https://github.com/knative/docs/tree/main/docs/blog/articles/getting-started-blog-p1.md)
- [`docs/blog/articles/getting-started-blog-p2.md`](https://github.com/knative/docs/tree/main/docs/blog/articles/getting-started-blog-p2.md)
- Files under [`code-samples/`](https://github.com/knative/docs/tree/main/code-samples/)
- Other markdown files throughout the [`docs/`](https://github.com/knative/docs/tree/main/docs) directory.
The [Knative docs contributor's guide](https://github.com/knative/docs/blob/main/contribute-to-docs/README.md) recommends correct language specifiers for code blocks, but enforcement is inconsistent.
---
### Proposed Enhancement
- Audit all documentation sources (`docs/`, `code-samples/`, and relevant blog articles).
- Update each markdown code block to specify the **appropriate language** (use “go”, “bash”, “yaml”, etc.).
- Use **consistent names** (e.g., always “bash” for shell scripts, “go” for Go code, “yaml” for manifests).
- Reference: [MkDocs Material supported languages](https://squidfunk.github.io/mkdocs-material/reference/code-blocks/#supported-languages).
---
### Benefits
- Enables syntax highlighting and improves readability for contributors and users.
- Supports better onboarding—new contributors can more easily read and copy-paste sample code.
- Aligns with markdown documentation best practices and the Knative docs style guide.
---
### References
- [`docs/`](https://github.com/knative/docs/tree/main/docs)
- [`code-samples/`](https://github.com/knative/docs/tree/main/code-samples)
- [Contributor's Guide](https://github.com/knative/docs/blob/main/contribute-to-docs/README.md)
- [Dart Doc Code Block Language Lint](https://dart.dev/tools/linter-rules/missing_code_block_language_in_doc_comment) (Best Practice Reference)
---
Contributor guide
Research direction
Read the contributor's guide first, then audit the named blog files, the code-samples/ directory, and other Markdown files under docs/. Check each fenced code block against the appropriate language and the recommended consistent names such as go, bash, and yaml. Done means the documentation sources have no missing or inconsistent language specifiers.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- bash, go, markdown, yaml
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 58/100