Markdown Style Guide

Our handbook is generated by Hugo a Static Site Generator (SSG) commonly used by web developers. Markdown is a lightweight markup language that helps structure documents, making them easily distinguishable from plain text. This guide outlines our Markdown conventions to ensure consistency across our documentation.

Let’s dive into our Markdown guidelines

Headings

Paragraphs, Line Breaks, and Horizontal Lines

ParagraphsLine BreaksHorizontal Lines
Paragraphs are separated by blank lines.Use line breaks sparingly, preferably within 100 characters per line.Horizontal lines consist of four dashes, surrounded by blank lines.

Emphasis: Bold and Italic

RuleDescription
Text FormattingUse double asterisks (**) for bold and underscores (_) for italic. For both, wrap the text in triple symbols.
UnderliningAvoid underlining text in Markdown; if underlining is necessary, use the <ins> HTML tag sparingly.

Code Blocks

Always use the ``` block to create one!

Links

We provide two ways to create links in the handbook, designed to accommodate both new contributors and power users:

Simple Approach (Recommended for New Authors)

Just write regular markdown links! The handbook automatically adds appropriate icons:

What happens automatically:

  • Internal links (starting with ./ or /) get a chevron-right icon →
  • External links (starting with http) get an arrow-up-right icon ↗

Advanced Approach (Shortcode)

For more control over styling, sizes, and behavior, use the eds-link shortcode:

Shortcode parameters:

  • label - The link text
  • url - The destination URL
  • size - small or large (default: small)
  • intent - underline or other visual treatments
  • icon - Icon to display (e.g., chevron-right, arrow-up-right)
  • icon-small - Set to "true" for smaller icons
  • external - Set to "true" for external links

Email Links

Use mailto: links for email addresses:

Emojis

If you want to use emojis in your files, the best way is to follow the guidelines and assets provided by IBM

Images

Here’s how you can introduce images. To add images, the easiest way is to put the image files in the same directory as the Markdown file. For example, add an image file collaboratory.png alongside the collaboratory-page.md file.

Diagrams

We support Mermaid and PlantUML for diagrams.

graph LR
    A[Start] --> B{Is it working?}
    B -- Yes --> C[Continue]
    B -- No --> D[Fix It]
    D --> B
    C --> E[Finish]

Here’s the code that produced the diagram above:

Videos

Embed videos using HTML5 <video> or <iframe> tags. Follow the provided instructions for YouTube videos.

Notes and Alerts

Utilize the implemented eds-alert shortcode for different types of alerts and callouts.

Tables

You can use standard markdown tables.

Standard Markdown Table

Accordions

Use accordions to organize collapsible content sections:

Comments

Edit this page on GitLab ↗