This is an example page of elements and components we can have in the new documentation

Headings, starting with heading 2

There are 6 levels of headings but you should always start with level 2, that is two ## characters. Level 1 is reserved for the title of the full page.

Heading 2 can be done with two ## characters:

## Heading 2

Heading 3

Can be done with three ### characters:

### Heading 3

Heading 4

For level 4, use four #### characters:

#### Heading 4

Heading 5

For level 5, use five ##### characters:

##### Heading 5

Heading 6

For level 6, use six ###### characters:

###### Heading 6

Text effects

You can have italic text by wrapping it inside one one asterisk: italic

*italic*

For bold text, use two asterisks: bold

**bold**

Use three asterisks for bold and italic: bold and italic

***bold and italic***

Use strikethrough for deletions: strikethrough

~~strikethrough~~

Links

Links can be created with square brackets followed by parentheses: Link Text

[Link Text](http://example.com)

For a reference style link: Link Text

[Link Text][1]

[1]: http://example.com

Blockquotes

Blockquotes can be indicated using the > symbol:

This is a blockquote. Add the actual double quote characters “yourself” if you are using this as a quote as in someone said something.

> This is a blockquote. Add the actual double quote characters "yourself" if you are using this as a quote as in someone said something.

Lists

Unordered Lists

Use asterisks to create an unordered list:

• Item 1
• Item 2
  • Sub-item 1
  • Sub-item 2

* Item 1
* Item 2
  * Sub-item 1
  * Sub-item 2

Ordered Lists

Use numbers followed by periods for an ordered list:

1. First item
2. Second item
   1. Subitem 1
   2. Subitem 2

1. First item
2. Second item
   1. Subitem 1
   2. Subitem 2

Images

Images are similar to links but use an exclamation mark before the square brackets:

Code Blocks

Inline code can be indicated with backticks: inline code

`inline code`

For larger code blocks, use three backticks:

function example() {
  return "This is a code block";
}

Syntax highlighting

Always define the language like this:

# this is ruby code
array = ['some', 'code']
puts "Choosing one of them: #{array.sample}"

def foo
  puts 'foo'
end

Plain code blocks

If you do not define the language or define “plain” it is treated differently

def foo
  puts 'this will not be syntax coloured'
end

Horizontal Rules

Horizontal rules can be added with three dashes:

---

Tables

Tables can be created using pipes and dashes:

| Header 1 | Header 2 |
| -------- | -------- |
| Cell 1   | Cell 2   |
| Cell 3   | Cell 4   |

Tables with popovers and icons

Tables work well with inline popovers for contextual information. Use \n in popover content to create line breaks — useful for country-specific lists or multi-line explanations that would otherwise break table syntax.

<!-- Icons: use $$$circle-check and $$$xmark for visual check/cross indicators -->
<!-- Popovers: use &&&trigger >>> content&&& for inline definitions -->
<!-- Line breaks in popovers: use \n for multi-line content inside tables -->

| Feature | Service A | Service B |
|---|---|---|
| Organisation number | $$$circle-check &&&Varies by country >>> NO: Organisation number.\nSE: Organisation number.\nDK: CVR number.\nFI: Business ID (y-tunnus)&&& | $$$circle-check |
| Account number | $$$circle-check &&&Format varies >>> NO: Account number.\nSE: BankGiro.\nDK: FIK&&& | $$$circle-check |
| Reference number | $$$circle-check &&&Details >>> Longer explanation here.\nSecond point.\nThird point.&&& | $$$xmark Not available |

Our own components

You can add our own custom components with special syntax right there in the Markdown file.

Badge

Badges can be created using three ! characters followed by the variant type. Close the badge with another three ! characters.

Available variants: brand, success, neutral, warning, danger

Brand badge

Success badge

Neutral badge

Warning badge

Danger badge

Badge with animations

Badge with appearance styles

Pill badge

Button

Buttons can be created using three % characters followed by the variant type and optional URL. Close the button with another three % characters.

Available variants: brand, success, neutral, warning, danger

Button with link

Button without link

Different button variants

Button with icons

Button with start and end icons

Button with sizes and appearances

Alongside the small/medium/large tokens shown here, the Web Awesome 3.x size scale xs, s, m, l, xl is also accepted for buttons, badges, tags, and callouts. The legacy tokens continue to work, so either scale is fine.

Link button: open in a new tab or download

Link-form buttons (a button wrapping a markdown link) accept _blank to open the link in a new tab and download to download the target instead of navigating to it. A _blank target automatically adds rel="noopener noreferrer" for security. The other targets _self, _parent, and _top are also available. These attributes apply only to link buttons; on a plain button they are ignored.

%%%brand _blank
[Open docs in a new tab](https://example.com)
%%%

%%%neutral download
[Download the diagram](img-big.png)
%%%

Card

Cards can be created using three = characters to open and close the card content.

Card appearance

The appearance token sets the card style: outlined (default), filled, filled-outlined, plain, or accent.

Horizontal card

Add horizontal to place the media beside the body instead of above it. The first image in the card becomes the side media. A multi-block body (a header plus a paragraph) stays contained within the card instead of spilling below it.

Horizontal card

The image sits to the side while the heading and this text flow next to it.

Comparison (Before/After)

Comparison components can be created using three | characters optionally followed by a position value (0-100, default is 50).

Default comparison (50% position)

Comparison with custom position (10%)

Copy Button

Copy buttons can be created using three < characters. The content inside will be copied to the clipboard when clicked.

npm install @web-awesome/components

Copy button tooltip mode

The tooltip token controls when the built-in tooltip appears, separately from tooltip-placement:

• full — Web Awesome’s default: tooltip on hover or focus, plus the brief copy-success feedback
• copy — silent on hover or focus; the tooltip appears only to confirm a copy
• none — no tooltip in any state

You can combine it with a placement, e.g. <<<top tooltip:copy.

Tag

Tags can be created using three @ characters followed by the variant type. Close the tag with another three @ characters.

Available variants: brand, success, neutral, warning, danger

Brand tag

brand

Success tag

success

Neutral tag

neutral

Warning tag

warning

Danger tag

Tag with icons

Tag with sizes and appearance

Removable tag

Icons

Icons can be added inline using three $ characters followed by the icon name. You can use any Font Awesome icon — both free and pro icons are available.

Basic icons

$$$circle-check $$$circle-xmark $$$triangle-exclamation $$$circle-info $$$star $$$gear $$$rocket $$$shield

Icons inline with text

Status: Active — the service is running.

This feature is in beta and may change.

For more details, see the API reference.

Status: $$$circle-check Active — the service is running.

$$$triangle-exclamation This feature is in beta and may change.

$$$circle-info For more details, see the API reference.

Icons in tables

Icons work well in tables as status indicators — see the tables with popovers and icons example above.

| Feature | Status |
|---|---|
| Invoice sending | $$$circle-check Supported |
| Line scanning | $$$xmark Not available |

Icon block form with animation and accessible label

The inline $$$name form is name-only and purely decorative. When you need more (an animation, an accessible label for screen readers, or a different weight or family) use the :::wa-icon block form. The first token is the icon name, followed by optional family, variant, and animation tokens in any order. The block body, if present, becomes the icon’s accessible label.

Available animations: beat, fade, beat-fade, bounce, flip, shake, spin, spin-pulse, spin-reverse

:::wa-icon bell shake
:::

:::wa-icon spinner spin
:::

When an icon carries meaning on its own rather than just decorating, give it a label. The block body becomes the label attribute, which assistive technology announces:

:::wa-icon circle-check solid
Task complete
:::

Icon variant and family

variant (thin, light, regular, solid) and family (classic, sharp, duotone, sharp-duotone, brands) change the icon’s weight and style. The attributes always reach the DOM, but the glyph only changes visibly with a Font Awesome Pro kit.

:::wa-icon star solid
:::

:::wa-icon star regular
:::

Callouts

Callouts can be done with the following syntax, using three : characters followed by the type of callout, and ending with again, three : characters. Like code blocks but with a different character.

info

success

neutral

warning

danger

With custom icon

With an animated icon

Add an animation token (such as shake or beat) directly on the callout line to animate its icon. The default solid variant is preserved, so existing callouts look the same.

:::warning shake
This warning's icon shakes to draw extra attention.
:::

:::danger beat
A danger callout with a beating icon.
:::

With sizes

With appearance styles

Dialogs

Dialogs (modals) can be created using three ? characters followed by optional parameters, then the button text, followed by three > characters to separate the dialog content. Close the dialog with another three ? characters.

Optional parameters:

• light-dismiss - Dialog closes when clicking outside
• Width value (e.g., 500px, 50vw, 40em) - Set custom dialog width

Basic dialog

Dialog with light dismiss

Dialog with custom width

Dialog with all options combined

Popovers

Popovers create floating content that appears on hover, attached to a trigger element. Use three & characters to open and close the popover. The trigger text and popover content are separated by three > characters.

Optional parameters:

• Placement: top (default), bottom, left, right
• link - Renders trigger as underlined inline text instead of a button
• without-arrow - Hides the popover arrow
• distance:N - Custom distance in pixels between trigger and popover

Basic popover with button trigger

Popover with link-style trigger

Use the link parameter to blend the trigger naturally into prose text. This is useful for inline definitions and contextual help.

Peppol

operator networks

Popover placement options

Popover without arrow

Popover with custom distance

Popover with rich content

Combined parameters

invoice validation

Aligned placement and skidding

Beyond the four primary placements, popovers accept the eight aligned variants (top-start, top-end, bottom-start, bottom-end, left-start, left-end, right-start, right-end) that anchor the popover to an edge of the trigger. The skidding:N parameter shifts the popover along the trigger axis (negative values allowed), complementing distance:N, which offsets it away from the trigger.

Inline popovers

Inline popovers can be used directly within a sentence. They always render as link-styled triggers (underlined text). The syntax is <button type='button' id='popover-58a22e77' class='ma-popover-trigger' style='background: none; border: none; padding: 0; color: inherit; text-decoration: underline; text-decoration-style: dotted; cursor: pointer; font: inherit;'>trigger text</button><wa-popover for='popover-58a22e77' placement='top'>popover content</wa-popover> on a single line.

Send invoices via PeppolPeppol is a standardized e-invoicing network used across Europe to your trading partners.

You can add placement parameters before the trigger text: learn about API authenticationAPI keys are used to authenticate your requests to the Maventa API in our documentation.

Combine multiple parameters: check the invoice validationInvoices are validated against Peppol business rules before being sent rules before submitting.

Multiple inline popovers on the same line: use PeppolPan-European e-invoicing network or SFTPSecure file transfer protocol for batch processing for delivery.

Inline code works as trigger text too: use scheme 0106 or 9944Depends on which identifier was used to register the company account in Maventa for Dutch companies.

Tooltips

Tooltips show brief contextual help on hover or focus, attached to a focusable anchor within your prose. Unlike popovers, the anchor is always inline text (dotted underline) and the tip is plain text, so they suit glossary terms and inline definitions. Both keyboard and screen-reader users get the tip.

The inline syntax is <span id="tooltip-016c8629" tabindex="0" class="ma-tooltip-anchor" style="text-decoration: underline dotted; cursor: help;">anchor term</span><wa-tooltip for="tooltip-016c8629" placement="top">tip text</wa-tooltip> on a single line.

Send invoices via PeppolPan-European e-invoicing network used across Europe to your trading partners.

Placement and distance

Add a placement token (top default, bottom, left, right, plus the eight aligned variants like top-start) and distance:N before the anchor:

Hover over API keyAuthenticates your requests to the Maventa API to see a tooltip below.

Use validationInvoices are checked against the target schema before sending with extra distance.

Skidding and line breaks

skidding:N shifts the tip along the trigger axis. Use \n in the tip for line breaks:

Scheme identifier 0106 or 9944NL: KvK number.
Use 0106 for the first, 9944 for VAT depends on registration.

Multiple tooltips and the block form

Multiple tooltips work on one line: SFTPSecure file transfer protocol or APIApplication programming interface for delivery.

A :::wa-tooltip block form is also available:

electronic invoiceA structured invoice exchanged machine-to-machine, not a PDF or a paper document.

Image Dialogs (Auto-transformation)

When image_dialog: true is enabled in _config.yml, all markdown images automatically become clickable and open in full-size dialogs.

Standard images that open in dialogs

Click on these images to view them in full size:

Images with custom dialog width

Control the dialog width by adding a width parameter in the image title:

This image will open in a dialog that takes 50% of the viewport width:

This image will open in a dialog with a fixed width of 800 pixels:

This image will open in a dialog that takes 90% of the viewport width:

Images that don’t open in dialogs

Add "nodialog" to the title to prevent the dialog transformation:

This is useful for small icons, logos, or decorative images that don’t need to be viewed full-size.

Summary / Details

Collapsible summary/details component can be created by using three ^ characters followed by the type of the layout:

• outlined (default)
• plain
• filled
• filled-outlined

The summary and details are separated by three > characters and the whole component is closed by repeating the three starting characters: ^

When to use this element?

• Question + Answer format for additional details?
• Small amount of additional details to keep hidden from the main text - don’t overuse this like we hidden everything in the old documentation with makes it painful to navigate

Summary ‘outlined’, default option

For this default option you can leave out the type “outlined”

Summary ‘plain’

Summary ‘filled’

Summary ‘filled-outlined’

Summary with icon on left

Summary with custom expand/collapse icons

Summary initially open

Accordion groups (only one open at a time)

Accordion

An accordion is a multi-section collapsible container, the grouped sibling of the Summary/Details element above, well suited to FAQs and grouped documentation sections. Where the ^^^name:group trick above chains together separate details elements, this is Web Awesome’s real wa-accordion component.

The container fence is six slashes //////, and each item is a /// block closed with its own ///.

Container tokens (any order):

• appearance: outlined (default), filled, filled-outlined, plain
• mode: multiple (default, several open at once), single, single-collapsible
• icon-placement: start, end
• heading:N: heading level 1–6, or none

Item tokens: leading expanded and/or disabled flags, an optional icon:name, then the rest of the line is the label. Item bodies are full Markdown.

Basic accordion (FAQ)

Single mode with an initially expanded item

Use single so opening one item closes the others, and mark an item expanded to start it open.

Custom icons and rich bodies

Tab groups

Tab groups can be created by using six + characters, followd by the positioning of the tabs:

• top (default)
• start
• end
• bottom

Tabs inside tab groups are created with three + characters. Place multiple tabs inside the tab groups, and close both of them off by using the same amout of + characters they were started with.

When to use the tab group element?

• When you want to show how to do something in different equivalent ways, for example code examples in different languages
• Possibly even for input/output or request/response type of things
• When we have multiple options to choose from and there is a very clear first option, so it does not matter the other options are only hidden behind the tabs, we want to promote the first option, let’s say webhooks vs. polling for example

Tabs aligned ‘top’ (default)

Tabs aligned ‘start’

Tabs aligned ‘end’

Tabs aligned ‘bottom’

Tabs with manual activation (click instead of hover)

Tab with a disabled item

Add a leading disabled token to a tab’s header (right after the +++ ) to render the tab but prevent it from being selected, useful for “coming soon” content.

Tree

A tree renders a hierarchy from a nested Markdown bullet list, using Web Awesome’s wa-tree / wa-tree-item. On our static site it is display-and-navigation only (no selection): visual nesting, an initial expand state, and optional leading icons.

The fence is six pipes ||||||, optionally followed by open to expand the top-level branches. Each bullet is a node; indent to nest children. A leading icon:name on a node adds an icon, and a leading expanded forces that branch open.

File tree with icons

Nested structure with colon-bearing labels

Labels containing colons (such as XML element names) render verbatim.

Dates and timestamps

Two declarative timestamp components render locale-formatted dates with no JavaScript to author. The date value is baked into the page at build time, and the browser formats it via Intl — ideal for post dates, changelog stamps, and “last updated” lines.

The inline syntax is <wa-format-date year="numeric" month="long" day="numeric"></wa-format-date>. A bare date renders an absolute, locale-formatted date (wa-format-date); a leading relative token renders a “3 days ago”-style phrase (wa-relative-time).

Absolute dates

• Default (long):
• style:short:
• style:full:
• With time:
• French locale:

Relative time

• Short format:

Block form

A block alternative is also available (empty body, closed by :::):

Random content

wa-random-content shows one or more of its options at random and hides the rest, optionally rotating them on a timer, all in Web Awesome’s runtime with no JavaScript to author. Handy for a lightly dynamic rotating-tips or featured-content block on an otherwise static page.

The fence is six dots ......, and options are separated by a >>> line.

Tokens (any order):

• mode: unique (default), random, sequence
• items:N: how many options to show at once (default 1)
• animation: none, fade, fade-up, fade-down, fade-left, fade-right
• autoplay and autoplay-interval:N (milliseconds between rotations)

Rotating tips

Show two options at once

Code blocks inside different custom components

Code blocks in Callouts

You can use code blocks inside callouts

class Maventa
  def greet
    puts "Hello from Maventa!"
  end
end

Code blocks in Summary/details

You can use code blocks inside summary/details component too

/// <summary>
/// Set credentials for future API calls
/// </summary>
/// <param name="userApiKey"></param>
/// <param name="companyUuid"></param>
/// <param name="vendorApiKey"></param>
public void SetCredentials(string userApiKey, string companyUuid, string? vendorApiKey = null)
{
    Config.SetConfig(new ConfigValues() { UserApiKey = userApiKey, CompanyUuid = companyUuid, VendorApiKey = vendorApiKey });
}

Code blocks in Tab groups

You can use code blocks inside tab groups too

class Maventa
  def greet
    puts "Hello from Maventa!"
  end
end

Maventa.new.greet

public class Maventa {
    public static void main(String[] args) {
        System.out.println("Hello from Maventa!");
    }
}

using System;

class Maventa {
    static void Main() {
        Console.WriteLine("Hello from Maventa!");
    }
}

class Maventa:
    def greet(self):
        print("Hello from Maventa!")
Maventa().greet()