Style Guide

As a content publisher for our Docusaurus-based Knowledge Base, it's important to leverage all available formatting options to create engaging and informative content. This guide includes advanced Docusaurus formatting options to 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
description: A brief description of your article (under 160 characters)
slug: custom-url-path
sidebar_position: 1
tags:
  - tag1
  - tag2
---

Important Frontmatter Fields

title: The article title (required)
description: Brief description for SEO and previews (required)
slug: Custom URL path (optional, defaults to filename)
sidebar_position: Controls order in the sidebar navigation (optional)
tags: List of related topics for better searchability (optional)
image: Cover or social image (optional)
hide_table_of_contents: Set to true to hide the TOC (optional)

2. Headings and Table of Contents

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

# Main Heading (H1)
## Subheading (H2)
### Smaller Subheading (H3)
#### Even Smaller (H4)

Docusaurus automatically generates a table of contents based on your headings. You can control the display with these frontmatter options:

---
# Hide the table of contents
hide_table_of_contents: true

# Customize the TOC depth (default is 3)
toc_min_heading_level: 2
toc_max_heading_level: 4
---

3. Code Blocks and Syntax Highlighting

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

​```python
def hello_world():
    print("Hello, World!")
​```

Which renders as:

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

Code Block Options

Docusaurus offers several enhancements for code blocks:

Line Numbers

Add the showLineNumbers option:

​```python showLineNumbers
def hello_world():
    print("Hello, World!")
​```

Line Highlighting

Highlight specific lines:

​```python {2} showLineNumbers
def hello_world():
    print("Hello, World!")  # This line will be highlighted
    return None
​```

Multiple Line Selections

Highlight multiple lines or ranges:

​```python {1,3-4} showLineNumbers
def hello_world():
    print("Hello, World!")
    # This line will be highlighted
    return None  # This line will be highlighted too
​```

Title

Add a title to your code block:

​```python title="hello_world.py"
def hello_world():
    print("Hello, World!")
​```

Live Code Editor

For interactive JavaScript/JSX examples:

​```jsx live
function Button() {
  return (
    <button onClick={() => alert('Hello World!')}>
      Click me!
    </button>
  );
}
​```

4. Admonitions

Admonitions are highlighted blocks used to emphasize important information. Docusaurus uses a specific syntax for admonitions:

:::note
This is a note admonition.
:::

:::tip[Title]
This is a tip with a custom title.
:::

Admonition Types

Docusaurus supports these admonition types:

:::note
Note content
:::

:::tip
Tip content
:::

:::info
Information content
:::

:::caution
Caution content
:::

:::danger
Danger content
:::

Custom Titles

You can add a custom title to any admonition:

:::tip[Your Custom Title]
Content with a custom title
:::

Nested Content

Admonitions can contain other Markdown elements:

:::tip[Complex example]

This admonition contains code:

​```javascript
console.log('Hello world!');
​```

And a bullet list:
- Item 1
- Item 2

:::

5. Task Lists

Create interactive checklists:

- [x] Completed task
- [ ] Pending task
- [ ] Another pending task

Rendered output:

Completed task
Pending task
Another pending task

6. Footnotes

Add footnotes for additional information:

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

[^1]: This is the footnote content.

7. Diagrams with Mermaid

To use Mermaid diagrams in Docusaurus, you'll need to ensure the mermaid plugin is installed and configured in your docusaurus.config.js file. Then you can create diagrams using this syntax:

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

8. Mathematical Equations

Docusaurus supports KaTeX for mathematical equations. Ensure the math plugin is configured, then use:

Inline math: $E = mc^2$

Display math:

\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}

9. Tabbed Content

Docusaurus has built-in support for tabs:

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

<Tabs>
  <TabItem value="apple" label="Apple" default>
    This is an apple 🍎
  </TabItem>
  <TabItem value="orange" label="Orange">
    This is an orange 🍊
  </TabItem>
  <TabItem value="banana" label="Banana">
    This is a banana 🍌
  </TabItem>
</Tabs>

Which renders as tabbed content where users can click between tabs.

Grouping Tabs

You can synchronize tab selections across your document:

<Tabs groupId="operating-systems">
  <TabItem value="win" label="Windows">Windows instructions...</TabItem>
  <TabItem value="mac" label="macOS">macOS instructions...</TabItem>
</Tabs>

<!-- Later in the document -->
<Tabs groupId="operating-systems">
  <TabItem value="win" label="Windows">More Windows instructions...</TabItem>
  <TabItem value="mac" label="macOS">More macOS instructions...</TabItem>
</Tabs>

10. Text Formatting

Docusaurus supports standard Markdown text formatting:

Bold text with **double asterisks**
Italic text with *single asterisks*
~~Strikethrough~~ with ~~double tildes~~
Inline code with backticks
Bold and italic with ***triple asterisks***

11. Links

Internal Links

Link to other documents within your site using relative paths:

[Link to another doc](../folder/document.md)

Docusaurus will automatically convert these to the correct URLs.

External Links

For external resources:

[External link](https://example.com)

Anchor Links

Link to headings within the same document:

[Link to heading](#heading-id)

Docusaurus automatically generates IDs from your headings, converting them to lowercase and replacing spaces with hyphens.

12. Images

Include images with standard Markdown syntax:

![Alt text for the image](/img/docusaurus.png)

For more control, use the Docusaurus image component:

import Image from '@site/src/components/Image';

<Image 
  src="/img/docusaurus.png"
  alt="Alt text for the image"
  width="300px"
/>

13. Tables

Create tables using standard Markdown syntax:

| Header 1 | Header 2 |
|----------|----------|
| Cell 1   | Cell 2   |
| Cell 3   | Cell 4   |

Rendered output:

Header 1	Header 2
Cell 1	Cell 2
Cell 3	Cell 4

Text Alignment

Control column alignment with colons:

| Left-aligned | Center-aligned | Right-aligned |
|:-------------|:--------------:|---------------:|
| Cell 1       | Cell 2         | Cell 3         |

14. Quotes

Create blockquotes with the > character:

> This is a blockquote.
> 
> It can span multiple lines.

Rendered output:

This is a blockquote.

It can span multiple lines.

15. Horizontal Rules

Insert a horizontal line with three or more hyphens, asterisks, or underscores:

---

Rendered output:

16. Embedding Assets

Videos

Embed videos using an iframe or the built-in components:

<iframe 
  width="560" 
  height="315" 
  src="https://www.youtube.com/embed/dQw4w9WgXcQ" 
  title="YouTube video player" 
  frameborder="0" 
  allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" 
  allowfullscreen>
</iframe>

Other Embeds

For other embeds like tweets or CodePen, use iframes or create custom React components.

17. Using React Components

Docusaurus allows using React components directly in Markdown:

import MyComponent from '@site/src/components/MyComponent';

<MyComponent prop1="value1" prop2="value2">
  Children content
</MyComponent>

Built-in Components

Docusaurus provides several built-in components:

import Link from '@docusaurus/Link';
import Highlight from '@site/src/components/Highlight';

<Link to="/docs/introduction">
  Go to Introduction
</Link>

<Highlight color="#25c2a0">Highlighted content</Highlight>

18. Using MDX Features

Docusaurus supports MDX, which lets you use JSX in Markdown files:

export const Highlight = ({children, color}) => (
  <span
    style={{
      backgroundColor: color,
      borderRadius: '2px',
      color: '#fff',
      padding: '0.2rem',
    }}>
    {children}
  </span>
);

<Highlight color="#25c2a0">Docusaurus green</Highlight>

Importing Code Examples

You can import code snippets from files:

import CodeBlock from '@theme/CodeBlock';
import MyComponentSource from '!!raw-loader!./path/to/MyComponent.js';

<CodeBlock className="language-jsx">{MyComponentSource}</CodeBlock>

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 Docusaurus setup to enhance the user experience:

Use descriptive titles and a logical hierarchy of headings.
Add proper frontmatter including description and tags.
Break up text with short paragraphs and bullet points.
Use clear section headings with appropriate heading levels.

2. Utilize Rich Formatting and Interactive Elements

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

Pro Tip

Admonitions visually separate different types of information. Use them sparingly for maximum impact.

Create tabbed content for organizing related information.
Implement task lists for step-by-step guides.

3. Enhance with Visual and Technical Elements

Include relevant images, diagrams, or screenshots.
Use Mermaid for flowcharts or sequence diagrams.
Add syntax-highlighted code blocks.
Use KaTeX for mathematical equations.

4. Optimize for Accessibility and Searchability

Use descriptive alt text for images.
Include relevant tags in your frontmatter.
Cross-link related articles within your documentation.
Structure content with proper headings for better navigation.

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.

Content Creation Guidelines for Knowledge Base

As a content creator for our Docusaurus-based Knowledge Base, your goal is to produce highly informative, engaging, and well-structured articles. To achieve this, refer to this comprehensive Syntax Guide and incorporate its features in your writing:

Begin each article with proper frontmatter including title, description, and tags.
Structure your content with clear headings and a logical flow.
Incorporate appropriate formatting elements based on the content type:
- Use code blocks with syntax highlighting for code examples
- Use admonitions for important notes, warnings, and tips
- Use tables for structured data presentation
- Use diagrams for visualizing processes or relationships
Aim to make your content as accessible and easy to navigate as possible:
- Break long sections into smaller, digestible chunks
- Use descriptive headings and subheadings
- Include a table of contents for longer articles
- Link to related resources when appropriate
Follow these content-specific guidelines:
- For tutorials: Include clear step-by-step instructions with code examples
- For concept guides: Define terms clearly and provide examples
- For reference material: Be comprehensive, accurate, and well-organized
- For troubleshooting guides: Include common issues and their solutions
Before finalizing your article, review it against this Syntax Guide to ensure you've made the most of the available formatting options.

By following this approach, you'll create Knowledge Base articles that not only contain valuable information but also present that information in the most effective and engaging way possible.

1. Metadata and Frontmatter​

Important Frontmatter Fields​

2. Headings and Table of Contents​

3. Code Blocks and Syntax Highlighting​

Code Block Options​

Line Numbers​

Line Highlighting​

Multiple Line Selections​

Title​

Live Code Editor​

4. Admonitions​

Admonition Types​

Custom Titles​

Nested Content​

5. Task Lists​

6. Footnotes​

7. Diagrams with Mermaid​

8. Mathematical Equations​

9. Tabbed Content​

Grouping Tabs​

10. Text Formatting​

11. Links​

Internal Links​

External Links​

Anchor Links​

12. Images​

13. Tables​

Text Alignment​

14. Quotes​

15. Horizontal Rules​

16. Embedding Assets​

Videos​

Other Embeds​

17. Using React Components​

Built-in Components​

18. Using MDX Features​

Importing Code Examples​

Best Practices for Engaging Content Creation​

1. Structure for Clarity and Navigation​

2. Utilize Rich Formatting and Interactive Elements​

3. Enhance with Visual and Technical Elements​

4. Optimize for Accessibility and Searchability​

5. Maintain Quality and Encourage Engagement​

Content Creation Guidelines for Knowledge Base​

1. Metadata and Frontmatter

Important Frontmatter Fields

2. Headings and Table of Contents

3. Code Blocks and Syntax Highlighting

Code Block Options

Line Numbers

Line Highlighting

Multiple Line Selections

Title

Live Code Editor

4. Admonitions

Admonition Types

Custom Titles

Nested Content

5. Task Lists

6. Footnotes

7. Diagrams with Mermaid

8. Mathematical Equations

9. Tabbed Content

Grouping Tabs

10. Text Formatting

11. Links

Internal Links

External Links

Anchor Links

12. Images

13. Tables

Text Alignment

14. Quotes

15. Horizontal Rules

16. Embedding Assets

Videos

Other Embeds

17. Using React Components

Built-in Components

18. Using MDX Features

Importing Code Examples

Best Practices for Engaging Content Creation

1. Structure for Clarity and Navigation

2. Utilize Rich Formatting and Interactive Elements

3. Enhance with Visual and Technical Elements

4. Optimize for Accessibility and Searchability

5. Maintain Quality and Encourage Engagement

Content Creation Guidelines for Knowledge Base