Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Enhancement Proposal: Improve Code Block Language Specifiers Across Documentation #6526

@codeEvolveZenith345

Description

@codeEvolveZenith345

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:

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


Metadata

Metadata

Assignees

No one assigned

    Labels

    triage/acceptedIssues which should be fixed (post-triage)

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions