-
Notifications
You must be signed in to change notification settings - Fork 0
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
code directive #7
Comments
Context: I'm also including my own notes ⬇️ PurposePresent 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 practicesUse 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. |
Code
Implementation
Specification compliance:
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 codeenumerator, number
(string) - Explicitly set the code numberclass
(string)caption
(parsed) - A parsed caption for the code block.linenos
(boolean)- Show line numberslineno-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.
code-block
sourcecode
The text was updated successfully, but these errors were encountered: