Enhancement Proposal: Improve Code Block Language Specifiers Across Documentation
Maintainers usually reply within 1 day
Nobody has claimed this yet.
Assessment
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Newbie friendliness
- 58/100
- Issue type
- Documentation
- Clarity
- Mostly clear
- Activity status
- Quiet
- Tech stack
- bash, go, markdown, yaml
- Domain
- documentation
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.
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.mddocs/blog/articles/getting-started-blog-p2.md- Files under
code-samples/ - Other markdown files throughout the
docs/directory.
The Knative docs contributor's guide 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.
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/code-samples/- Contributor's Guide
- Dart Doc Code Block Language Lint (Best Practice Reference)
- Dominant language
- HTML
- Stars
- 5.1k
- Forks
- 1.3k
- PR merge metrics
- No merged PRs in 30d
Getting set up
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from knative/docs
-
Difficulty 1/5 Under an hour Newbie friendliness 85/100
Maintainers usually reply within 1 day
-
Difficulty 1/5 Under an hour Newbie friendliness 35/100
knative/docs#6651 · 1 comment ·
Maintainers usually reply within 1 day
-
kind/documentation
Difficulty 5/5 Over a week Newbie friendliness 20/100
knative/docs#6301 · 7 comments ·
Maintainers usually reply within 1 day
-
kind/bug triage/accepted
Difficulty 4/5 3-5 days Newbie friendliness 35/100
knative/docs#6217 · 6 comments ·
Maintainers usually reply within 1 day
-
lifecycle/frozen triage/accepted
Difficulty 4/5 3-5 days Newbie friendliness 25/100
knative/docs#5703 · 5 comments ·
Maintainers usually reply within 1 day
Similar issues
-
area:docs area:render bug criticality:p3 triage:needs-implementation
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
registrystack/registry-stack#1618 ·
Maintainers usually reply within 1 day
-
curriculum documentation quality
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
githubnext/gh-aw-workshop#3897 ·
Maintainers usually reply within 2 days
-
Difficulty 2/5 1-3 hours Newbie friendliness 76/100
siderolabs/docs#791 ·
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 75/100
nestjs/docs.nestjs.com#3554 ·
Maintainers usually reply within 1 day
-
Difficulty 1/5 Under an hour Newbie friendliness 98/100
huggingface/course#1320 ·
Maintainers usually reply within 1 day