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
- Unordered list item
- 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:
| 100px | 25% | Remainder Column |
|---|---|---|
| Cell 1 | Cell 2 | Cell 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]
| 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}
| 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:
markdownconsole.log("hi"); // [!code --]
console.log("hello"); // [!code ++]
console.log("goodbye");
renders as:
tsconsole.log("hi");
console.log("hello");
console.log("goodbye");
Can also highlight rows using [!code error], [!code warning].
tsconsole.log("error");
console.log("warning");
You can also focus the reader’s attention on specific lines using [!code focus]:
tsconsole.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().
markdownThis 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.
markdownThis 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):
markdownThis 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."
:::
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
srconly, then that’s the image that will be used in both modes, - If you specify
srcSetonly, then you can provide different images for light and dark modes, and - If both
srcandsrcSetare present, thensrcwill 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."
:::
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:
- If you don’t specify a
widthorheight, then the image will be displayed at its original size. - 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.
- If you specify a
widthas 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. - 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”). - 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 awidththat 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"
:::
Static Assets
Place images in the images/ subfolder at the docs root:
Reference them in Markdown using relative paths:
markdown
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.
tsconsole.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
```
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.
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 answer 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
::
:::
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.
::
:::
This is something interesting about Step 1.
- Bullet 1
- Bullet 2
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.