Extended Markdown Features

In building this white-labelled portal, we’ve recognised that every installation will be different: your own logos, your own layouts, your own way of explaining your functionality. There’s no such thing as a cookie-cutter implementation.

We strive to balance a rich formatting experience — all the tables, images, headings and navigation you’d expect from a professional developer portal, without the need for custom coding — with a simple technical delivery that’s fast to deploy and easy to update with the tools you already have.

We accept:

  • Standard CommonMark syntax for headings, lists, tables, code blocks, etc.
  • Syntax-highlighted code fences from Shiki
  • Custom alert callout containers: :::tip, :::warning, :::danger, :::details
  • Extended table formatting including merged cells and alignment
  • Icons by Font Awesome
  • Tabbed content: :::tabs
  • And a whole lot more!

If you are looking for something that is not supported, please drop us a line!

💡 Tip

Remember that this website is a copy of our white-labelled portal software, so feel free to use developer tools to explore the rendered HTML and CSS.

Basic Text Formatting

All of the basic text formatting options are supported.

markdown
**Bold text**

_Italic text_

~~Strikethrough text~~

`Inline code`

1. Unordered list item
1. Another item

- Unordered list item
- Another item
    - Nested item
    - Another nested item

> This is a blockquote
>
> It can span multiple lines

Bold text

Italic text

Strikethrough text

Inline code

  1. Unordered list item
  2. Another item
  • Unordered list item
  • Another item
    • Nested item
    • Another nested item

This is a blockquote

It can span multiple lines

Headings

Headings are handled with the standard Markdown (#) syntax. With headings up to level six supported.

💡 Tip

While H1 (#) is supported, we recommend using H2 (##) at the highest level on this page. Not only does it look great, it avoids a potential conflict with offline exports (the dreaded PDF!) where the section name is rendered as H1.

All heading are automatically allocated an HTML id anchor, which can be copied to the clipboard by clicking on the hash icon which appears by hovering over the text. To set your own id instead of the auto-generated one, append {#your-id} to the end of the heading line, e.g. ## My Heading {#my-custom-id}.

Heading levels 2, 3 and 4 are automatically added to the “On This Page” navigation menu on the right-hand side with appropriate indenting.

Tables

Basic Tables

Standard Markdown tables are supported:

markdown
| Name  | Age |
| ----- | --- |
| Alice | 30  |
| Bob   | 25  |

Renders as an equal-width column table like this:

Name Age
Alice 30
Bob 25

Column Width

Markdown does not natively support precise column width formatting, but you can use native HTML with CSS width instructions in your Markdown:

markdown
<table>
  <thead>
    <tr>
      <th style="width:100px">100px</th>
      <th style="width:25%">25%</th>
      <th>Remainder Column</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>Cell 1</td>
      <td>Cell 2</td>
      <td>Cell 3</td>
    </tr>
  </tbody>
</table>

Which will render as:

100px25%Remainder Column
Cell 1Cell 2Cell 3

Cell Alignment

You may use the following syntax to control (consistent) cell alignment for a column. Note that this impacts both the header and body cells.

markdown
| Default Align | Left Align | Right Align | Center Align |
| ------------- | :--------- | ----------: | :----------: |
| Default cell  | Left       |       Right |    Center    |

This renders as:

Default Align Left Align Right Align Center Align
Default cell Left Right Center

Merged Cells

The render process will automatically merge empty cells horizontally where a column has no content. To leave an empty (unmerged) cell, simply use the space character. To merge a cell vertically with the cell directly above it, set the cell content equal to ^^.

markdown
| | Grouping ||
| First Header | Second Header | Third Header |
|------------ | :-----------: | -----------|
| Vertical merge | _Horizontal Merge_ ||
| ^^ | **Bold Cell** | Cell |

This example renders as below. Note that the top left cell is preserved (unmerged) because the markdown contains a single space character.

Grouping
First Header Second Header Third Header
Vertical merge
Bold Cell Cell

Lists Within Cells

The syntax of lists and tables appears at odds with each other; Markdown lists require a newline character between bullets, but table cells do not permit such line breaks.

The answer is to split each bullet over a new row and merge them back together during render using a trailing \ character at the end of a table row. This instructs the renderer to merge every cell within the row with the immediately prior row.

💡 Code Auto-Formatters

Some IDE code formatters such as (Prettier in VSCode) may recognise this trailing \ as a new cell, automatically adding a further | marker to close the cell. To avoid this, try wrapping the table in an annotation which disables auto-formatting as you see in the example below.

md
<!-- prettier-ignore-start -->
| Column A   | Column B             | Column C                 |
| ---------- | -------------------- | ------------------------ | 
| First row  | 1. Bullet one        | - Unordered item.        | \ 
|            | 1. Bullet two        | - Second unordered item. |
| Second row | Some paragraph text.<br>Another paragraph. | | 
<!-- prettier-ignore-end -->
Column A Column B Column C
First row 1. Bullet one - Unordered item. \
1. Bullet two - Second unordered item.
Second row Some paragraph text.
Another paragraph.

💡 Paragraphs

The above approach will not neatly handle paragraphs within cells unfortunately. For these, we recommend adding raw <br> HTML as in the above example.

Table Captions

You may add a caption to any table by immediately following it with a string within [] marks. For example:

markdown
| First Column | Second Column |
| ------------ | ------------- |
| Cell One     | Cell Two      |

[This is my table caption]
This is my table caption
First Column Second Column
Cell One Cell Two

Advanced Table Styling

All tables will acquire a default CSS class of markdown-table, which should be used for global table styling. For even more precise styling, you may use the curly bracket syntax.

If you are combining this with a table caption, however, be sure to place it on a new line after the caption.

markdown
| First Column | Second Column |
| ------------ | ------------- |
| Cell One     | Cell Two      |

[table caption]
{#unique_table_id}
table caption
First Column Second Column
Cell One Cell Two

Code Blocks

Code blocks are supported with language definition using Shiki.

ℹ️ Light/Dark Mode

This component automatically adjusts with dark/light mode to keep looking great.

cpp
// Working of implicit type-conversion

#include <iostream>
using namespace std;

int main() {

   int num_int;
   double num_double = 9.99;

   // implicit conversion
   // assigning a double value to an int variable
   num_int = num_double;

   cout << "num_int = " << num_int << endl;
   cout << "num_double = " << num_double << endl;

   return 0;
}

Available languages are:

Language ID
JavaScript javascript or js
TypeScript typescript or ts
Markdown markdown or md
Bash bash
JSON json
JSON with comments jsonc
HTML html
CSS css
Java java
Python python
YAML yaml
SQL sql
C++ cpp
C# csharp
Go go
Rust rust

We also support notation of add/delete rows in code blocks:

markdown
console.log("hi"); // [!code --]
console.log("hello"); // [!code ++]
console.log("goodbye");

renders as:

ts
console.log("hi"); 
console.log("hello"); 
console.log("goodbye");

Can also highlight rows using [!code error], [!code warning].

ts
console.log("error"); 
console.log("warning"); 

You can also focus the reader’s attention on specific lines using [!code focus]:

ts
console.log("Not focused");
console.log("Focused"); 
console.log("Not focused");

Highlight Box

Alerts or callouts are an easy way to emphasise important information to the reader.

markdown
::: warning
This is a warning. By default, the title of the callout is the type of callout.
:::

::: info My Custom Title
To set a custom title, just append it to the callout type.
:::

::: tip
Redocly calls these callouts "admonition tags".
:::

::: danger
This is danger
:::

::: details Click for more details
This is an expandable details element.
:::

:::: tip
::: info
This is a nested info element within a tip element.
:::
::::

These various options render as follows:

⚠️ Warning

This is a warning. By default, the title of the callout is the type of callout.

ℹ️ My Custom Title

To set a custom title, just append it to the callout type.

💡 Tip

Redocly calls these callouts “admonition tags”.

🚨 Danger

This is danger.

📋 Click me to reveal more details

This is an expandable details element.

💡 Tip

ℹ️ Info

This is a nested info element within a tip element.

Font Colour & Background

Emphasising a section of text with a non-default colour is simple with the inline :color: rule. Simply place your Markdown in a :color: inline marker, specifying the text colour and (optionally) a background colour. You may use any CSS colour format you like: strings, hex, rgb() and rgba().

markdown
This is black text. :color:Red:red:. Back to black.

I can combine this with other Markdown syntax such as :color:**bold**:blue: markers.

Passing a third attribute will set the :color:background colour:white:blue:.

This is black text. Red. Back to black.

I can combine this with other Markdown syntax such as bold markers.

Passing a third attribute will set the background colour.

ℹ️ Info

This colouring function is designed to highlight small sections of text only; it is not designed for multi-line or complex situations.

Important: it should not be used to colour icons - use the native icon colour instead.

We automatically add some padding and rounding to background colours to make it look neat. To keep it professional, we encourage pale, pastel colours with an appropriate opacity, such as:

  • Pastel Peach - rgba(255, 218, 185, 0.6)
  • Mint Green - rgba(152, 251, 152, 0.5)
  • Soft Lavender - rgba(230, 230, 250, 0.9)
  • Baby Blue - rgba(173, 216, 230, 0.6)
  • Soft Canary - rgba(255, 253, 10, 0.5)
  • Classic Neon Yellow - rgba(255, 255, 0, 0.85)

Icons

Can use anything from the Font Awesome library.

markdown
This is a copy icon :icon:fa-regular fa-copy: in text.

This is a copy icon in text.

The icons can be any colour too. Simply add a third element to the icon declaration with a valid CSS colour value (name or HEX):

markdown
This is a red copy icon :icon:fa-regular fa-copy:red: in text.

This is a red copy icon in text.

Images

Standard Markdown does support images, but we found it too limited for a modern, technical documentation website, and so we created a custom :::img component which supports a wider range of attributes:

Attribute Type Description
src string Either src or srcSet must be specified. The source URL(s) for the image. See Dark vs Light Mode for more detail.
srcSet string
width string or number Sets the height / width of the image either as a number of pixels, or a string value with units. Defaults to 100%. See Sizing & Alignment.
height string or number
borderRadius string or number Softer, rounded image corners. Can either be a number of pixels or a string with units (e.g., 50%). Defaults to 4px.
align string Describes how you want the image aligned on the page. Options: left, right, center. Defaults to center.
id string CSS id attribute to attach to the outer <figure> element.
class string CSS class attribute to append to the outer <figure>. Note that all images will automatically acquire the markdown-image class.
alt string HTML alt attribute added to the rendered image. Attempts to use caption if not present.
caption string figcaption content. Must be a plain text string only.

Here is a basic example:

md
::: img
alt="Basic example image"
src="example_image.jpg"
width="50%"
align="center"
caption="This is my image caption."
:::
Basic example image
This is my image caption.

Dark vs Light Mode

This portal offers a dark mode toggle in the top navigation bar. Dark mode is very cool, but sometimes images with a “fixed” white background can look slightly unprofessional in dark mode. This is where srcSets saves the day!

  • If you specify src only, then that’s the image that will be used in both modes,
  • If you specify srcSet only, then you can provide different images for light and dark modes, and
  • If both src and srcSet are present, then src will be used.

💡 Tip

We recommend .png image files as they allow transparent backgrounds, which is ideal for logos and other images that need to look good in both light and dark mode.

md
::: img
alt="Example of srcSet changing image based on theme"
srcSet="fixspec.png light, fixspec_dark.png dark"
width="50%"
align="center"
caption="This FixSpec logo changes between light and dark mode."
:::
Example of srcSet changing image based on theme
This FixSpec logo changes between light and dark mode.

Sizing & Alignment

By default, images are displayed centre-aligned and with their original dimensions and aspect ratio. While we considered offering fine-grained CSS style control over images, we quickly realised that path leads to potentially bad layouts, and so we’ve restricted what you can do for safety.

Here’s the logic we use to show the image:

  1. If you don’t specify a width or height, then the image will be displayed at its original size.
  2. If the original image width is larger than the viewport (middle column), then we scale the width and height to make it fit, keeping the original aspect ratio.
  3. If you specify a width as a number of pixels (e.g. 300px), then we use it unless that is wider than the viewport width. We auto-adjust the height to keep the original aspect ratio.
  4. If you specify a percentage width (e.g. 50%), then that percentage is relative to the viewport width and not the original image width (i.e. 50% means “50% of the viewport width”).
  5. If you specify a height, then we use that and ignore the original aspect ratio. Warning: This may result in a stretched or squashed image unless you also specify a width that maintains the original ratio.

💡 Focus On Width

Since users can easily scroll down a page, controlling height is less important than setting width correctly. Explicitly setting height will drop the original aspect ratio and potentially make the image look stretched or squashed.

md
::: img
alt="Demonstration of fixed width"
src="example_image.jpg"
width="50%"
align="right"
caption="Right-aligned and covering 50% of the viewport width"
:::

::: img
alt="Demonstration of borderRadius"
src="example_image.jpg"
width="200"
height="200"
borderRadius="50%"
caption="Creating a circular image using borderRadius"
:::
Demonstration of fixed width
Right-aligned and covering 50% of the viewport width
Demonstration of borderRadius
Creating a circular image using borderRadius

Static Assets

Place images in the images/ subfolder at the docs root:

📁 docs/
└── docs/
└── images/ # Assets directory
├── logo.png # Main brand logo
└── diagram.png # System architecture diagram

Reference them in Markdown using relative paths:

markdown
![Diagram](../images/diagram.png)

Tabbed Content

Sometimes, it is more efficient to present content in a tabbed format. It is great for presenting different programming language examples. Simply use the :::tabs block to wrap your content, and use ::tab[Label] to define each tab.

markdown
:::tabs
::tab[JavaScript]
JS content here
::
::tab[TypeScript]
TS content here
::
:::

You can embed other markdown content in a tab, such as tables:

Name Age
Alice 30
Bob 25

Or perhaps code examples.

ts
console.log("Some example Typescript code");

File/Folder Tree View

In technical documentation, displaying a file/folder tree view is surprisingly common. You can use a ```treeview fenced code block to neatly display a tree view of your project structure using the standard tree characters of ├──, │ and └──.

The tree view will automatically apply a monospace font and preserve whitespace.

markdown
```treeview project-root/
├── src/
│ ├── components/
│ │ ├── Button.tsx       # This is a comment
│ │ └── Card.tsx         // This type of comment also works (but converts to #)
│ └── utils/
│   └── api.ts
├── public/
│ └── favicon.ico
├── package.json
└── README.md
```
📁 project-root/
├── src/
│ ├── components/
│ │ ├── Button.tsx # This is a comment
│ │ └── Card.tsx # This type of comment also works (but converts to #)
│ └── utils/
│ └── api.ts
├── public/
│ └── favicon.ico
├── package.json
└── README.md

Cards

Cards are simple, horizontally-spaced boxes that can contain a title, body and (optionally) a clickable header. They are ideally suited for short, punchy content as opposed to long blocks of text.

ℹ️ Info

We have kept these quite simple for launch, but we hope to enhance them over time. If you are interested in how they might evolve, drop us a line.

The syntax for these cards follows tabs, in that we wrap inner ::card elements inside an outer :::cards container, and use the double- versus triple-colon syntax at the different levels. Just like tabs, the title of the card is enclosed in square brackets. If you would like to make the title clickable, then simply add a second square bracket as shown below.

markdown
::: cards
:: card[This title has a link][https://fixspec.com]
This is **card** content.
::
:: card[Second card title][]
:icon:fa-regular fa-copy:red: This second card content is longer than the first, and so look how both heights adjust.
::
:::

This is card content.

Second card title

This second card content is longer than the first, and so look how both heights adjust.

As you can see, you can place any other markdown inside the body of the card as required, including links, icons, etc. We also equalise the height of the cards in a row to make them look neat.

You can nest as many ::card elements inside the :::cards wrapper as you like. Horizontal space is obviously limited, so the portal displays one, two or three cards per row (depending on the available screen width) and automatically wraps the rest onto further rows.

FAQ Display

If you would like to add a frequently asked questions section with expandable answer display, then use the :::faqs component like this:

md
:::faqs
::faq[My question goes here]
My **answer** goes here
::
::faq[Second question goes here]
Second _answer_ goes here
::
:::
My question goes here

My answer goes here

Second question goes here

Second answer goes here

While questions must be text only, you may use any other Markdown in the answer section provided you correctly nest fence blocks.

Want to add a permalink to allow users to share an FAQ directly? No sweat - just add a unique {#id} attribute after the ::faq block, the same curly-brace syntax used to set a custom heading id.

md
:::faqs
::faq[Hover for a clickable link]{#unique_faq_link}
My answer still appears here
::
:::

ℹ️ Info

Remember that any id you set must comply with HTML requirements: must begin with a letter ([A-Za-z]) and may be followed by any number of letters, digits ([0-9]), hyphens (“-”), underscores (“_”), colons (“:”), and periods (“.”).

Stepper Components

Want to display a list of steps to your users? You need a :::stepper.

Within the outer :::stepper block, you can add as many ::step blocks are you wish, with their order of appearance derived from the order in which they appear.

Heading and sub-heading attributes follow the ::step element, along with an optional third, color attribute. The body of the block may contain all Markdown types, but nesting other block-level containers requires nesting fence blocks.

markdown
:::stepper
::step[STEP 1][Step 1 Heading][grey]
This is something interesting about **Step 1**.

- Bullet 1
- Bullet 2

::
::step[STEP 2][Step 2 Heading][#3b62d6]
I can also embed other Markdown such as :icon:fa-regular fa-cogs:red: icons or :color:highlighted:#fff:blue: text.
::
:::
STEP 1
Step 1 Heading

This is something interesting about Step 1.

  • Bullet 1
  • Bullet 2
STEP 2
Step 2 Heading

I can also embed other Markdown such as icons or highlighted text.

Nesting Fence Blocks

Many of the custom Markdown extensions above use a triple-colon syntax. For example, details about images are placed within a block which starts with :::img and ends with :::. This is sometimes referred to as fencing and is a familiar feature of Markdown.

Furthermore, some types of container expect child blocks (e.g. :::tabs expects child ::tab blocks within them), providing a practical example of nesting fenced blocks within other fenced blocks; note the change from a triple colon to a double one.

Provided you correctly mirror the number of colons at the start and end of the blocks, this approach can be used to deeply nest elements as far as you wish.

markdown
::::tip Image inside a tip
This is an example of embedding an image inside a `:::tip` block.
:::img
src="example_image.jpg"
width="30%"
align="center"
:::
::::

💡 Image inside a tip

This is an example of embedding an image inside a :::tip block.

CSS Classes

For even greater control over Markdown presentation, you are able to attach HTML class and/or id attributes to any block-level code fence or Markdown block, by using curly bracket syntax. These can then be specifically targeted and styled using static style sheets.

markdown
# Heading {#heading_id} // Overrides auto-generated slug

### Heading {.class-one .class-two} // Multiple classes are possible

:::faqs {#faq_id} // ID applied to the outer FAQ <div>
::faq[Some question] {#faq_question_id .faq-class} // ID and class applied to individual FAQ.

⚠️ Images

Note that this functionality does not work with images (using the :::img fence), but you can set these using other attributes. Please see the image section.