code directive

[Mpdreamz]

Code

Kind	Link
Reference	https://mystmd.org/guide/directives#directive-code
Documentation	https://mystmd.org/guide/code

A code-block environment with a language as the argument, and options for highlighting, showing line numbers, and an optional filename.

Implementation

• [ ] Parses directives and aliases
• [ ] Emits HTML
• [ ] Unit tests
• [ ] Validation (emits, warnings and errors).

Specification compliance:

• [ ] Arguments is not parsed and treated as language option
• [ ] Body is not parsed and treated as raw string
• [ ] Options:
  • [ ] label, name (string) - Label the code to be cross-referenced or explicitly linked to.
  • [ ] enumerated, numbered (boolean) - Turn on/off the numbering for the specific code
  • [ ] enumerator, number (string) - Explicitly set the code number
  • [ ] class (string)
  • [ ] caption (parsed) - A parsed caption for the code block.
  • [ ] linenos (boolean)- Show line numbers
  • [ ] lineno-start (number) - Start line numbering from a particular value, default is 1. If present, line numbering is activated.
  • [ ] number-lines (number) Alternative for “lineno-start”, turns on line numbering and can be an integer that is the start of the line numbering.
  • [ ] emphasize-lines (string) - Emphasize particular lines (comma-separated numbers), e.g. “3,5”
  • [ ] filename (string) Show the filename in addition to the rendered code. The include directive will use the filename by default, to turn off this default set the filename to false.
• [ ] Aliases:
  • [ ] code-block
  • [ ] sourcecode

[KOTungseth]

Context:

• docsmobile/issues/337
• elastic-docs-v3/issues/9

I'm also including my own notes ⬇️

Purpose

Present code clearly: Code blocks provide a visually distinct area for displaying code snippets, making it easier for users to read and understand programming syntax. This separation from regular text helps highlight important code sections.

Enhance readability: By formatting code with consistent indentation, spacing, and syntax highlighting, code blocks improve readability. This helps users quickly grasp the structure and flow of the code, which is especially important for complex code examples.

Facilitate copying: Code blocks are often designed to allow users to easily copy and paste code into their development environments. This convenience reduces errors caused by manual transcription and speeds up the implementation process.

Demonstrate functionality: Code blocks can illustrate specific functionality or usage examples, helping users understand how to implement a feature, use a library, or interact with an API. They provide practical context for the information being discussed.

Support multi-language examples: Documentation often needs to cover multiple programming languages. Code blocks allow for clear distinctions between different language examples, ensuring users know which code applies to their specific programming environment.

Enable syntax highlighting: Many documentation systems support syntax highlighting for code blocks, which enhances the visibility of keywords, comments, and other elements. This visual differentiation helps users quickly identify relevant parts of the code.

Encourage best practices: Code blocks can be used to showcase best practices, coding standards, or common pitfalls, guiding users in writing better, more efficient code. This is valuable for both novice and experienced developers.

Best practices

Use syntax highlighting: Leverage syntax highlighting to enhance the readability of code blocks. This visual distinction helps users quickly identify keywords, variables, and other elements, making it easier to understand the code.

Provide clear and descriptive context: Before or after the code block, include a brief explanation of what the code does, its purpose, and how it fits into the overall documentation. This context helps users understand why the code is relevant.

Keep code blocks short: Aim to keep code blocks concise and focused on a single concept or function. If a longer example is necessary, consider breaking it into smaller sections or providing a link to a more extensive resource.

Ensure code is executable: If possible, provide code that users can easily copy and paste into their development environments without modification. This reduces errors and enhances the user experience.

Include comments in code: Use comments within the code to explain critical parts or complex logic. This can help users understand the code's intent and facilitate learning.

Provide examples and use cases: Whenever applicable, follow code blocks with real-world examples or scenarios that demonstrate how the code can be used. This practical application helps users see the value of the code in context.

Test code for accuracy: Ensure that the code provided in the documentation is accurate, functional, and up-to-date. Regularly test code examples to verify they work as intended.

Indicate language: Clearly indicate the programming language used in each code block, especially when the documentation covers multiple languages. This helps users quickly identify the relevant syntax.