This guide demonstrates the various styling features available in our documentation. Use this as a reference when writing docs.

Tabbed Code Blocks

Use tabbed code blocks to show the same concept in multiple languages. This is especially useful for API examples.

Basic Example

from langsmith import traceable, wrappers
from openai import OpenAI

# Optionally wrap the OpenAI client to trace all model calls.
oai_client = wrappers.wrap_openai(OpenAI())

# Optionally add the 'traceable' decorator to trace the inputs/outputs of this function.
@traceable
def toxicity_classifier(inputs: dict) -> dict:
    instructions = (
        "Please review the user query below and determine if it contains any form of toxic content "
        "such as insults, threats, or highly negative comments. Respond with 'Toxic' if it does, "
        "and 'Not toxic' if it doesn't."
    )
    messages = [
        {"role": "system", "content": instructions},
        {"role": "user", "content": inputs["text"]},
    ]
    result = oai_client.chat.completions.create(
        messages=messages, model="gpt-4o-mini", temperature=0
    )
    return {"class": result.choices[0].message.content}

import { traceable, wrappers } from "langsmith";
import { OpenAI } from "openai";

// Optionally wrap the OpenAI client to trace all model calls.
const oaiClient = wrappers.wrapOpenAI(new OpenAI());

// Optionally add the 'traceable' decorator to trace the inputs/outputs of this function.
const toxicityClassifier = traceable(
  async (inputs: { text: string }): Promise<{ class: string }> => {
    const instructions =
      "Please review the user query below and determine if it contains any form of toxic content " +
      "such as insults, threats, or highly negative comments. Respond with 'Toxic' if it does, " +
      "and 'Not toxic' if it doesn't.";

    const result = await oaiClient.chat.completions.create({
      messages: [
        { role: "system", content: instructions },
        { role: "user", content: inputs.text },
      ],
      model: "gpt-4o-mini",
      temperature: 0,
    });

    return { class: result.choices[0].message.content ?? "" };
  },
  { name: "toxicityClassifier" }
);

Syntax Guide

To create tabbed code blocks, use the following syntax:

=== "Tab Name 1"

    ```python
    # Your Python code here (indented 4 spaces)
    print("Hello, World!")
    ```

=== "Tab Name 2"

    ```javascript
    // Your JavaScript code here (indented 4 spaces)
    console.log("Hello, World!");
    ```

Admonitions (Call-out Boxes)

Admonitions are useful for highlighting important information.

Note

Tip

Warning

Danger

Info

Example

Syntax

!!! note "Custom Title"
    Your content here. Make sure to indent with 4 spaces.

!!! warning
    Warning without a custom title.

Collapsible Sections

Use collapsible sections to hide detailed content that not all readers need.

print("Hidden code!")

Syntax

??? note "Collapsed by default"
    Hidden content here.

???+ tip "Expanded by default"
    Visible content here.

Code Blocks

Basic Code Block

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

Code Block with Line Numbers

The configuration already enables line numbers via anchor_linenums: true.

Code Block with Title

def greet(name: str) -> str:
    return f"Hello, {name}!"

Inline Code

Use backticks for inline code: print("Hello") or const x = 1.

Tables

Math Equations

Inline math: \( E = mc^2 \)

Block math:

Links and References

• External Link
• Internal Link to Overview
• Footnotes¹

Lists

Unordered List

• Item 1
• Item 2
  • Nested item 2.1
  • Nested item 2.2
• Item 3

Ordered List

1. First step
2. Second step
3. Third step

Task List

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

Workflow Steps

Use workflow components to display step-by-step processes with numbered badges and visual indicators.

Basic Workflow (Single Tab)

Tabbed Workflow

Use tabs when you have multiple related workflows to display:

Workflow Syntax Guide

Single workflow (no tabs):

<div class="workflow-single">
<div class="workflow-header">Workflow Title</div>

<div class="workflow">
<ol>
<li><strong>Step Title</strong>

Step description with [links](url) and details.</li>
<li><strong>Another Step</strong>

Description with nested list:

- Item 1
- Item 2</li>
</ol>
</div>
</div>

Tabbed workflows:

=== "Tab 1 Name"

    <div class="workflow">
    <ol class="workflow-steps">
    <li><strong>Step Title</strong>

    Description here.</li>
    </ol>
    </div>

=== "Tab 2 Name"

    <div class="workflow">
    <ol class="workflow-steps">
    <li><strong>Step Title</strong>

    Description here.</li>
    </ol>
    </div>

Combining Elements

Here's an example combining multiple elements:

pip install py-openjudge

import openjudge
print(openjudge.__version__)

Typography Elements

Blockquotes

Use blockquotes for important quotes or highlighted text:

This is a simple blockquote. It's great for highlighting important information or quoting external sources.

With citation:

The best way to predict the future is to invent it.

— Alan Kay

Keyboard Shortcuts

Display keyboard shortcuts using the <kbd> tag:

Press Ctrl + C to copy, and Ctrl + V to paste.

On Mac, use ⌘ + S to save.

Highlighted Text

Use <mark> to highlight important text:

The most critical configuration is the API key setting.

Abbreviations

Define abbreviations that show tooltips on hover:

The HTML specification is maintained by the W3C.

Enhanced Admonitions

Admonitions with Rich Content

Admonitions can contain complex nested content:

from openjudge import LLMGrader

grader = LLMGrader(model="gpt-4")
result = grader.evaluate(response, reference)

Custom Titled Admonitions

from openjudge import TextSimilarityGrader

grader = TextSimilarityGrader(threshold=0.8)

result = grader.evaluate(
    response="The capital of France is Paris.",
    reference="Paris is the capital of France."
)

print(f"Score: {result.score}")  # Score: 0.95
print(f"Pass: {result.passed}")  # Pass: True

Links Styling

Standard Links

• Internal documentation link
• External link to GitHub

Links with Code

Check the LLMGrader class for more details.

Use the evaluate() method to run grading.

Horizontal Rules

Standard divider (three dashes):

Use dividers to separate major sections of your documentation.

Enhanced Tables

Standard Table

Table with Code and Links

Footnotes

Here's a sentence with a footnote¹, and another one².

Next Steps

• Contribute to OpenJudge — Learn how to contribute code and documentation
• Quick Start — Get started with OpenJudge
• Built-in Graders — Explore available graders