Skip to content

Rendering Guide

This knowledge base now supports restrained colour styling for Markdown rendering in MkDocs.

Sensible Rules

Use colour to communicate structure, not to decorate randomly.

Good uses: - required actions - validated results - warnings / risks - project vs research distinctions - quick inline emphasis

Avoid: - long runs of coloured body text - too many competing colours on one page - using red for anything that is not actually risky

Built-in Admonitions

These already work and are the cleanest default.

!!! note
    General note

!!! warning
    Use this for cautions or process risks.

!!! danger
    Use this for real breakage or high-risk operations.

!!! success
    Use this for validated results.

!!! tip
    Use this for practical advice.

Inline Coloured Text

Use HTML spans inside Markdown.

<span class="text-blue">Reference</span>
<span class="text-green">Validated</span>
<span class="text-yellow">Attention needed</span>
<span class="text-red">High risk</span>
<span class="text-purple">Project context</span>
<span class="text-muted">Secondary note</span>

Rendered examples:

  • Reference
  • Validated
  • Attention needed
  • High risk
  • Project context
  • Secondary note

Inline Highlight Chips

Use these for compact emphasis.

<span class="highlight-blue">Reference</span>
<span class="highlight-green">Result</span>
<span class="highlight-yellow">Action needed</span>
<span class="highlight-red">Risk</span>
<span class="highlight-purple">Project</span>

Rendered examples:

  • Reference
  • Result
  • Action needed
  • Risk
  • Project

Coloured Highlight Regions

Use attr_list classes on paragraphs or divs.

Paragraph-style region

Important result block.
{: .panel-result }

Example:

Validated result block.

Rich block region with multiple lines

<div class="panel-research">

### Research note

- Use this for compact contextual blocks.
- Works well for summaries and structured notes.

</div>

Rendered example:

### Research note - Use this for compact contextual blocks. - Works well for summaries and structured notes.

Available Panel Classes

  • .panel-note
  • .panel-reference
  • .panel-result
  • .panel-warning
  • .panel-danger
  • .panel-project
  • .panel-research

Default hierarchy: 1. plain Markdown first 2. admonitions for important blocks 3. panel classes for structured highlight regions 4. inline colour only when short and useful

If a page starts looking like a UI theme demo, you’ve gone too far. Software always wants to become theatre if you let it.