Syntax Guide¶

As a content publisher for our MkDocs-based Knowledge Base, it's important to leverage all available formatting options to create engaging and informative content. This guide now includes advanced Material for MkDocs formatting options to further enhance your articles.

1. Metadata and Frontmatter¶

Every article should begin with frontmatter. This is enclosed in triple dashes and contains important metadata:

---
title: Your Article Title
date: 2024-06-29
description: A brief description of your article (under 160 characters)
tags:
  - tag1
  - tag2
---

2. Headings and Table of Contents¶

Use headings to structure your content. The table of contents will be automatically generated:

# Main Heading
## Subheading
### Smaller Subheading

3. Code Blocks and Syntax Highlighting¶

For code snippets, use triple backticks with the language specified:

def hello_world():
    print("Hello, World!")

In addition to the existing syntax, you can now add line numbers and highlight specific lines:

1
2

def hello_world():
    print("Hello, World!") # (1)

1. This line will be highlighted

4. Admonitions¶

Recommended HTML Admonition Format¶

Admonitions are highlighted blocks used to emphasize important information. Due to reliability issues with Markdown-style admonitions, we strongly recommend using HTML-style admonitions as the default approach:

<div class="admonition type">
  <p class="admonition-title">Title</p>
  <p>Content of the admonition.</p>
</div>

Replace type with one of the supported types (note, info, warning, etc.).

Example:

<div class="admonition warning">
  <p class="admonition-title">Security Notice</p>
  <p>Never share your credentials with unauthorized personnel.</p>
</div>

This renders as:

HTML Admonition Types¶

All of these admonition types are available using the HTML format by changing the class name:

• note - Blue information blocks
• abstract - Summary blocks
• info - Information blocks
• tip - Helpful tip blocks
• success - Success message blocks
• question - FAQ blocks
• warning - Caution/warning blocks
• failure - Failure message blocks
• danger - Critical alert blocks
• bug - Known issue blocks
• example - Example blocks
• quote - Quote blocks

Alternative Markdown-style Admonitions (Less Reliable)¶

While HTML admonitions are preferred for reliability, you can also use Markdown-style admonitions. However, these are extremely sensitive to formatting and may not render correctly in all environments:

!!! type "Optional Title"
    Content of the admonition (indented with 4 spaces)

For Markdown-style admonitions to render correctly, you MUST follow these rules:

1. Start with three exclamation marks (!!!) followed by the type and optional title
2. Add a blank line after the admonition declaration line
3. Indent all content with exactly 4 spaces (not tabs)
4. Maintain consistent indentation throughout the admonition
5. Do not add extra blank lines between the declaration and content

Correct and Incorrect Examples¶

✅ Correct Formatting:¶

!!! warning "Security Notice"
    Never share your credentials with unauthorized personnel.

This renders as:

❌ Incorrect Formatting (no blank line after declaration):¶

!!! warning "Security Notice"
Never share your credentials with unauthorized personnel.

❌ Incorrect Formatting (content on same line):¶

!!! warning "Security Notice" Never share your credentials with unauthorized personnel.

❌ Incorrect Formatting (wrong indentation):¶

!!! warning "Security Notice"
  Never share your credentials with unauthorized personnel.

Troubleshooting Admonition Rendering Issues¶

If your admonitions aren't rendering properly, follow these solutions in order:

1. Use HTML admonition format (recommended): Switch to the HTML admonition format as shown above, which is more reliable across different rendering environments.

   <div class="admonition warning">
     <p class="admonition-title">Security Notice</p>
     <p>Never share your credentials with unauthorized personnel.</p>
   </div>
   

2. Use HTML comments to force line breaks (for Markdown-style admonitions):

   !!! warning "Security Notice" <!-- force line break -->
       Never share your credentials with unauthorized personnel.
   

3. Check for invisible characters: Sometimes copying and pasting can introduce invisible characters that break the syntax. Try retyping the admonition from scratch.

4. Ensure consistent line endings: Mixed line endings (CRLF vs LF) can sometimes cause rendering issues. Use a text editor to normalize line endings.

5. Verify MkDocs configuration: Make sure the pymdownx.admonition extension is properly enabled in your mkdocs.yml file.

Inline blocks¶

Admonitions can also be rendered as inline blocks (e.g., for sidebars). You can place them to the left using the inline modifier, or to the right using the inline end modifier.

Left-aligned inline block¶

Here's the code for a left-aligned inline block:

!!! info inline "Lorem ipsum"

    Lorem ipsum dolor sit amet, consectetur
    adipiscing elit. Nulla et euismod nulla.
    Curabitur feugiat, tortor non consequat
    finibus, justo purus auctor massa, nec
    semper lorem quam in massa.

This is some text that will appear next to the inline block.

This renders as:

This is some text that will appear next to the inline block. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa. Sed sollicitudin ante sed turpis pulvinar, et venenatis arcu semper. Fusce non lorem at mi mattis gravida. Praesent sit amet nunc nec libero fermentum ullamcorper. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa. Sed sollicitudin ante sed turpis pulvinar, et venenatis arcu semper. Fusce non lorem at mi mattis gravida. Praesent sit amet nunc nec libero fermentum ullamcorper.

Right-aligned inline block¶

Here's the code for a right-aligned inline block:

!!! info inline end "Lorem ipsum"

    Lorem ipsum dolor sit amet, consectetur
    adipiscing elit. Nulla et euismod nulla.
    Curabitur feugiat, tortor non consequat
    finibus, justo purus auctor massa, nec
    semper lorem quam in massa.

This is some text that will appear next to the inline end block.

This renders as:

This is some text that will appear next to the inline end block.

Important: Admonitions that use the inline modifiers must be declared prior to the content block you want to place them beside. If there's insufficient space to render the admonition next to the block, the admonition will stretch to the full width of the viewport, e.g., on mobile viewports.

Supported Types Examples¶

MkDocs supports several types of admonitions, each with its own style and icon. Here are examples using the recommended HTML format:

<div class="admonition note">
  <p class="admonition-title">Note</p>
  <p>This is a simple note admonition.</p>
</div>

<div class="admonition abstract">
  <p class="admonition-title">Abstract</p>
  <p>This is an abstract or summary.</p>
</div>

<div class="admonition info">
  <p class="admonition-title">Information</p>
  <p>Here's some important information.</p>
</div>

<div class="admonition tip">
  <p class="admonition-title">Pro Tip</p>
  <p>Here's a helpful tip for our users.</p>
</div>

<div class="admonition success">
  <p class="admonition-title">Success</p>
  <p>Great job! You've done it correctly.</p>
</div>

<div class="admonition question">
  <p class="admonition-title">FAQ</p>
  <p>Frequently asked question here.</p>
</div>

<div class="admonition warning">
  <p class="admonition-title">Caution</p>
  <p>Be careful when using this feature.</p>
</div>

<div class="admonition failure">
  <p class="admonition-title">Failure</p>
  <p>This action resulted in a failure.</p>
</div>

<div class="admonition danger">
  <p class="admonition-title">Critical</p>
  <p>This action cannot be undone!</p>
</div>

<div class="admonition bug">
  <p class="admonition-title">Known Issue</p>
  <p>There's a known bug with this feature.</p>
</div>

<div class="admonition example">
  <p class="admonition-title">Example</p>
  <p>Here's an example of how to use this.</p>
</div>

<div class="admonition quote">
  <p class="admonition-title">Famous Quote</p>
  <p>"To be or not to be, that is the question."</p>
</div>

Admonition Formatting Specification¶

When using admonitions in MkDocs, adhere to the following specification:

1. Alignment: Admonitions must be aligned with the left margin of the document.
2. Indentation: Do not indent admonitions. Any indentation will prevent them from rendering correctly.
3. Syntax: Start each admonition with three exclamation marks (!!!) followed by the type and optional title.
4. Content: The content of the admonition should be indented by 4 spaces on the lines following the admonition declaration.

5. Task Lists¶

Create interactive checklists:

- [x] Completed task
- [ ] Pending task

Rendered output:

• Completed task
• Pending task

6. Footnotes¶

Add footnotes for additional information:

Here's a sentence with a footnote.[^1]

[^1]: This is the footnote content.

Rendered output:

Here's a sentence with a footnote.¹

7. Diagrams with Mermaid¶

Create diagrams using Mermaid syntax:

```mermaid
graph TD
    A[Start] --> B{Is it working?}
    B -->|Yes| C[Great!]
    B -->|No| D[Keep trying]
    D --> B

graph TD
    A[Start] --> B{Is it working?}
    B -->|Yes| C[Great!]
    B -->|No| D[Keep trying]
    D --> B

8. Mathematical Equations¶

Use LaTeX syntax for equations:

$E = mc^2$

Rendered output:

\(E = mc^2\)

9. Tabbed Content¶

Create tabbed sections:

=== "Tab 1"
    Content for tab 1

=== "Tab 2"
    Content for tab 2

Rendered output:

10. Keyboard Keys¶

Display keyboard shortcuts:

++ctrl+alt+del++

Rendered output:

Ctrl+Alt+Del

11. Text Formatting¶

In addition to highlighting, you can now use other text formatting options:

• Ctrl+Alt+Del (keys)
• This was marked (marked text)
• This was inserted (inserted text)
• This was deleted (deleted text)

12. Emojis¶

Include emojis in your content:

:smile: :rocket: :books:

Rendered output:

:smile: :rocket: :books:

13. Image Lightbox¶

Images will automatically use the lightbox feature. Just insert them as usual:

![Alt text](path/to/image.jpg)

Rendered output:

[Note: The actual image would be displayed here. For this example, imagine a clickable image that opens in a lightbox when clicked.]

14. Tables¶

Create tables using standard Markdown syntax or CSV files (with table-reader plugin):

| Column 1 | Column 2 |
|----------|----------|
| Cell 1   | Cell 2   |

Rendered output:

You can now add a title to your tables:

Table: API Methods

15. Tags¶

Use tags in your frontmatter for better categorization and searchability.

---
tags:
  - documentation
  - tutorial
  - advanced
---

Rendered output:

[Note: Tags are typically displayed at the top or bottom of the page, often as clickable elements. The exact rendering depends on the theme and configuration.]

16. Tooltips¶

You can now add tooltips to your text:

Hover me

17. Buttons¶

Create clickable buttons:

Subscribe to our newsletter

18. Icons and Emojis¶

Include icons from the Material library:

:material-account-circle: – :fontawesome-regular-laugh-wink:

19. Content Tabs¶

Create content tabs for alternative content:

#include <stdio.h>

int main(void) {
  printf("Hello world!\n");
  return 0;
}

print("Hello world!")

20. Data Tables¶

Create sortable data tables:

21. Abbreviations¶

Add explanations to abbreviations:

The HTML specification is maintained by the W3C.

*[HTML]: Hyper Text Markup Language *[W3C]: World Wide Web Consortium

22. Critic¶

Use critic markup for tracking changes:

Text can be {--deleted--} and replacement text {++added++}. This can also be combined into {one~>a single} operation. {Highlighting} is also possible {>>and comments can be added inline<<}.

{==

Formatting can also be applied to blocks by putting the opening and closing tags on separate lines and adding new lines between the tags and the content.

==}

23. Formatting¶

Combine formatting options for rich text styling:

• This is bold text
• This is italicized text
• This is bold and italicized text
• This is inline code
• This is strikethrough text
• This is highlighted text

24. Numbering in Headings and Sections¶

When creating content, use numbering judiciously to enhance readability and reference-ability. Here are the guidelines for using numbers in headings and sections:

Headings Without Numbers¶

If your sections contain numbered steps or lists, avoid using numbers in the headings themselves. For example:

Project Setup¶

1. Initialize the project
2. Install dependencies
3. Configure settings

Continuous Numbering Across Sections¶

When using numbered steps or lists within sections, continue the numbering sequence throughout the entire document. This approach makes it easier for users to reference specific steps. For example:

Project Setup¶

1. Initialize the project
2. Install dependencies
3. Configure settings

Development Process¶

4. Write code
5. Run tests
6. Deploy to staging

Headings With Numbers¶

In documents where sections don't contain numbered steps, you can use numbers in headings for better organization:

1. Introduction¶

2. Getting Started¶

3. Advanced Features¶

Best Practices for Engaging Content Creation¶

As a content publisher, your goal is to create documentation that's both informative and engaging. Here's how to leverage our MkDocs setup to enhance the user experience:

1. Structure for Clarity and Navigation¶

• Use descriptive titles and a logical hierarchy of headings.
• Include a table of contents for longer articles.
• Break up text with short paragraphs and bullet points.

2. Utilize Rich Formatting and Interactive Elements¶

• Emphasize key points with bold, italic, or highlighted text.
• Use admonitions to call out important information:

• Create tabbed content for organizing related information:

• Implement task lists for step-by-step guides:
  • Plan your content
  • Write your draft
  • Review and revise

3. Enhance with Visual and Technical Elements¶

• Include relevant images, diagrams, or screenshots.
• Use Mermaid for flowcharts or sequence diagrams:

graph TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Action 1]
    B -->|No| D[Action 2]

• Add syntax-highlighted code blocks:

def example_function():
    """This is an example function."""
    return "Hello, World!"

• Use LaTeX for mathematical equations: \(E = mc^2\)

4. Optimize for Accessibility and Searchability¶

• Use descriptive alt text for images.
• Create keyboard shortcuts for important actions: Ctrl+S
• Include relevant tags in your frontmatter:

  tags:
    - user guide
    - advanced features
  

• Cross-link related articles within your documentation.

5. Maintain Quality and Encourage Engagement¶

• Follow a consistent style guide and tone across all documentation.
• Provide real-world examples and use cases.
• Keep content up-to-date with the latest product changes.
• Include a clear process for user feedback and contributions.

Remember, the key is to balance information density with readability and visual appeal. By incorporating these practices, you'll create documentation that's not only informative but also engaging and user-friendly. Happy publishing!

KB Article Writing Prompt: Leveraging the Syntax Guide¶

As a content creator for our MkDocs-based Knowledge Base, your goal is to produce highly informative, engaging, and well-structured articles. To achieve this, refer to our comprehensive Syntax Guide and incorporate as many of its features as possible in your writing. Here's how to approach your article creation:

1. Review the Syntax Guide thoroughly before starting your article.

2. For each section of your article, consider which elements from the Syntax Guide could enhance its presentation and clarity.

3. Aim to incorporate at least one example of each major feature described in the Syntax Guide, including but not limited to: - Proper frontmatter with metadata - Structured headings - Code blocks with syntax highlighting - HTML-style admonitions (preferred over Markdown-style admonitions for reliability) - Task lists - Footnotes - Mermaid diagrams - Mathematical equations - Tabbed content - Keyboard key formatting - Text highlighting - Emojis - Images (which will use the lightbox feature) - Tables - Tags

4. Important Note on Admonitions: Always use HTML-style admonitions rather than Markdown-style ones to ensure consistent rendering. For example:

   <div class="admonition note">
     <p class="admonition-title">Note</p>
     <p>Your content here.</p>
   </div>
   

5. Use these features judiciously to enhance your content, not just for the sake of using them. Each element should serve a purpose in improving understanding or engagement.

6. Pay special attention to the "Best Practices for Engaging Content Creation" section at the end of the Syntax Guide. Apply these principles throughout your article.

7. Before finalizing your article, review it against the Syntax Guide to ensure you've made the most of the available formatting options.

8. Remember that while comprehensive formatting is encouraged, the primary goal is to create clear, informative, and user-friendly documentation.

9. Do not include conclusion sections in KB articles. The content should be self-contained and focused on providing information and guidance without unnecessary summarization at the end.

By following this approach, you'll create KB articles that not only contain valuable information but also take full advantage of our MkDocs setup to present that information in the most effective and engaging way possible.