Markdown Styling

Configure how Atmos displays markdown content in the terminal.

Configuration

Configure markdown styling in your atmos.yaml configuration file:

atmos.yaml

settings:
  # Terminal settings for displaying content
  terminal:
    max_width: 120  # Maximum width for terminal output
    pager: true     # Use pager for long output
    timestamps: false
    colors: true
    unicode: true
    
    # Markdown element styling
    markdown:
      document:
        color: "${colors.text}"
      heading:
        color: "${colors.primary}"
        bold: true
      code_block:
        color: "${colors.secondary}"
        margin: 1
      link:
        color: "${colors.primary}"
        underline: true
      strong:
        color: "${colors.secondary}"
        bold: true
      emph:
        color: "${colors.muted}"
        italic: true
      

Style Properties

Each markdown element supports the following properties:

Common Properties

Property	Type	Description
color	string	Text color in hex format (e.g., "#FFFFFF")
background_color	string	Background color in hex format
bold	boolean	Whether to make the text bold
italic	boolean	Whether to make the text italic
underline	boolean	Whether to underline the text
margin	number	Space around the element
indent	number	Indentation level

Element-Specific Properties

Document

Base styling for all text content.

Supports all common properties.

Headings (H1-H6)

Individual styling for each heading level (1-6).

# Heading 1
## Heading 2
### Heading 3
etc...

Supports:

• H1 supports additional background_color property
• All heading levels support margin for vertical spacing

Code Blocks

Styling for multi-line code blocks (aka code fences).

```
this is a codeblock
```

Supports:

• margin for visual separation
• Color applies to the entire block

Block Quotes

Styling for quoted text. Supports all common properties.

> 
> This is quoted text
>

Supports:

• indent property controls quote indentation

Links

Styling for hyperlinks.

[This is a link](https://example.com/)

Supports:

• underline property specifically for links
• Color applies to both link text and underline

Default Styles

If no custom styles are configured, Atmos uses a built-in default theme related to the default atmos brand colors:

# Built-in default theme
settings:
  markdown:
    document:
      color: "#FFFFFF"  # White text
    heading:
      color: "#00A3E0"  # Blue headings
      bold: true
    h1:
      color: "#FFFFFF"  # White text
      background_color: "#9B51E0"  # Purple background
      bold: true
      margin: 2
    code_block:
      color: "#00A3E0"  # Blue code
      margin: 1
    link:
      color: "#00A3E0"  # Blue links
      underline: true

Terminal Compatibility

Atmos uses termenv and glamour to automatically detect and adapt to your terminal's capabilities:

• Full Color Support (24-bit)

  • Renders exact hex colors as specified in your config
  • Detected via $COLORTERM=truecolor or $TERM containing 24bit/truecolor
  • Examples: iTerm2, Terminal.app, Windows Terminal

• 256 Color Support

  • Automatically maps hex colors to nearest ANSI 256 colors
  • Detected via $TERM containing 256color
  • Examples: xterm-256color terminals

• Basic Color Support (8/16 colors)

  • Automatically maps to basic ANSI colors
  • Used when $TERM indicates basic terminal
  • Examples: xterm, vt100, basic SSH sessions

• No Color Support

  • Falls back to plain text with basic formatting
  • Used when $TERM=dumb or no color support detected
  • Examples: Basic terminals, some CI environments

The color degradation is handled automatically by termenv's color profile detection. You don't need to configure anything - your styles will work everywhere, automatically adjusting to each terminal's capabilities.

Examples

Error Messages

Custom styling can help distinguish different types of messages:

settings:
  markdown:
    # General heading styles
    heading:
      color: "#00A3E0"  # Blue for standard headings
      bold: true
      
    # Code blocks for command examples
    code_block:
      color: "#00FFFF"  # Cyan for code examples
      margin: 1
      
    # Emphasized text for warnings/errors
    emph:
      color: "#FF6B6B"  # Red for emphasis in error messages
      italic: true
      
    # Strong text for important messages
    strong:
      color: "#FF6B6B"  # Red for important parts
      bold: true

Help Text

Atmos uses the Glamour library for markdown rendering and styling. The styling is handled automatically based on your terminal's capabilities and color profile.

Key features of the markdown rendering:

• Auto-styling: Adapts to your terminal's color scheme
• Word wrapping: Automatically adjusts to terminal width
• Emoji support: Renders emoji characters when available
• Rich formatting: Supports headings, code blocks, links, and other markdown elements

The styling is managed internally by Glamour and does not require manual configuration in your atmos settings.

Best Practices

1. Color Contrast: Ensure sufficient contrast between text and background colors for readability.
2. Consistent Styling: Use a consistent color scheme across different elements.
3. Terminal Support: Test your styling in different terminals to ensure compatibility.
4. Accessibility: Consider color-blind users when choosing your color scheme.

Troubleshooting

1. Verify Terminal Supports True Color:

   • Check $COLORTERM:

     echo $COLORTERM

     Expected Output: truecolor or 24bit

   • Check $TERM:

     echo $TERM

     Recommended Values: xterm-256color, xterm-direct, xterm-truecolor

2. Ensure Your Terminal Emulator Supports True Color:

   • Use a terminal emulator known for true color support (e.g., Terminal.app, iTerm2, Windows Terminal, etc).

3. Configure Environment Variables Correctly:

   • Set $TERM to a value that supports true color:

     export TERM=xterm-256color
     Add this to your shell's configuration file (~/.bashrc, ~/.zshrc, etc.) to make it permanent.

4. Validate atmos.yaml Configuration:

   • Ensure colors are in hex format, boolean values are true/false (not quoted strings), and numbers are integers.
   • Use a YAML linter to validate the syntax.
   • Try removing custom styles to see if default styles work.

See Also

• CLI Configuration
• Command Reference