GitHub-Style Alerts

Alternative styling for asides using GitHub's visual design

GitHub-Style Alerts

In addition to Starlight-style asides, you can use GitHub-styled alerts with the same simple syntax. Just prefix the type with gh- to get GitHub's visual design.

Syntax

:::gh-note
Your content here
:::
Markdown

Available Types

Note (Blue)

Syntax:

:::gh-note
Highlights information that users should take into account, even when skimming content.
:::
Markdown

Tip (Green)

Syntax:

:::gh-tip
Helpful advice for doing things better or more easily.
:::
Markdown

Important (Purple)

Syntax:

:::gh-important
Key information users need to know to achieve their goal.
:::
Markdown

Warning (Yellow/Orange)

Syntax:

:::gh-warning
Urgent info that needs immediate user attention to avoid problems.
:::
Markdown

Caution (Red)

Syntax:

:::gh-caution
Advises about risks or negative outcomes of certain actions.
:::
Markdown

Custom Titles

Just like Starlight asides, you can add custom titles:

Syntax:

:::gh-tip[Pro Developer Tip]
Use meaningful variable names to make your code self-documenting!
:::
Markdown

Full Markdown Support

GitHub alerts support all markdown formatting:

Comparison: Starlight vs GitHub

Starlight Style

GitHub Style

When to Use Each Style

Use Starlight Style When:

  • ✅ You want a clean, modern documentation look
  • ✅ You prefer subtle, elegant design
  • ✅ Building technical documentation

Use GitHub Style When:

  • ✅ Your content is hosted on GitHub
  • ✅ You want familiar GitHub aesthetics
  • ✅ You prefer bold, high-contrast alerts
  • ✅ Migrating content from GitHub README files

Real-World Examples

Installation Warning

Security Notice

Feature Announcement

Prerequisites

Helpful Hint

Combining Styles

You can mix Starlight and GitHub styles in the same document:

Color Reference

GitHub Light Mode

  • Note: Blue (#ddf4ff background, #0969da text)
  • Tip: Green (#dcffe4 background, #116329 text)
  • Important: Purple (#f6e7ff background, #6e1a52 text)
  • Warning: Yellow/Orange (#fff8c5 background, #7d4e00 text)
  • Caution: Red (#ffebe9 background, #d1242f text)

GitHub Dark Mode

All colors automatically adjust for dark mode with proper contrast.

Best Practices

✅ Do

:::gh-note
Clear, concise information that adds value.
:::

:::gh-warning
Specific warning about a real potential issue.
:::
Markdown

❌ Don't

:::gh-note
This is a note. This is some text. Here's more text.
Random information that goes on and on without clear purpose...
:::

:::gh-caution
Minor suggestion that isn't actually dangerous.
:::
Markdown

Tips for Educators

  1. Match your platform - Use GitHub styles if your course materials are on GitHub
  2. Be consistent - Pick one style (Starlight or GitHub) and stick with it
  3. Use appropriately - Don't overuse alerts; they lose impact
  4. Choose the right type - Use important for must-know info, tip for helpful hints

Example: Complete Tutorial Section

Creating Arrays

JavaScript arrays can hold multiple values:

const numbers = [1, 2, 3, 4, 5];
const fruits = ['apple', 'banana', 'orange'];
JAVASCRIPT

Both Starlight and GitHub styles give you powerful ways to highlight information. Choose the style that best fits your content and audience! 🎨