knative / knative/docs

Enhancement Proposal: Improve Code Block Language Specifiers Across Documentation

Open
#6,526 5 comments 0 reactions 0 assignees View on GitHub
triage/accepted
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.