jekyll-webawesome

This is a plugin for Jekyll that transforms custom Markdown syntax into Web Awesome components. Use a simple, intuitive Markdown-like syntax to create rich interactive components in your Jekyll website. The goal is to keep HTML out of Markdown files and create an easier experience for non-developers to update content.

The tranformations have been extracted into a separate project: markawesome, which can be used with any static site generator or Ruby application that processes Markdown.

The context here is a technical documentation website, and being limited to just basic Markdown features often results in a boring wall of text which the user won't read. The aim is to help create a more visually interesting page to read, by mixing in some components like callouts, tabs, cards and collapsible summary/details.

This plugin focuses on the most commonly used Web Awesome components for Jekyll content. Components are organized by support status:

Not all components will make sense to include here, to be included in the "prose" content of a web page. Some components are more suitable to be used in layouts or used in the page as includes, too complicated for this purpose.

Both syntax styles work identically and can be mixed within the same document.

Layout containers use :::: (quadruple colon) syntax to wrap content in Web Awesome CSS layout utilities. Layouts compose with component syntax — use ::: components inside :::: layouts.

Common attributes across all layouts: gap:SIZE, align:VALUE, justify:VALUE. Alternative ::::wa-* syntax is supported for all layout types.

Add this line to your application's Gemfile:

gem 'jekyll-webawesome'

Add the plugin to your Jekyll site's _config.yml:

plugins:
  - jekyll-webawesome

And add configuration options as needed in _config.yml:

webawesome:
  # Enable debug output to see which files are being processed
  debug: true

  # Control which file types to transform (default: both true)
  transform_pages: true      # Transform pages (like index.md, about.md)
  transform_documents: true  # Transform documents (like blog posts in _posts)
  
  # Enable automatic image-to-dialog transformation (default: false)
  # Can be a simple boolean
  image_dialog: true         # Makes all images clickable and open in dialogs
  
  # Or a hash with options for more control
  image_dialog:
    enabled: true            # Enable the feature
    default_width: 90vh      # Default width for dialogs (e.g., 90vh, 80%, 1200px)

And then execute:

bundle install

You can also configure the plugin programmatically in a _plugins/ file or in your gem's initialization:

require 'jekyll-webawesome'

Jekyll::WebAwesome.configure do |config|
  config.debug_mode = true
  config.transform_pages = false     # Don't transform pages
  config.transform_documents = true  # Only transform documents (posts)
end

See the plugin in action with a complete Jekyll site showcasing all supported components:

cd examples
bundle install
bundle exec jekyll serve

Then visit http://localhost:4000 to see all components rendered with Web Awesome styling.

Note: All components support dual syntax. You can use either the primary syntax (shown in examples below) or the alternative :::wa-component syntax.

Create callouts using the ::: syntax:

:::info
This is an info callout with **bold text** and [links](https://example.com).
:::

:::success
This is a success callout.
:::

:::warning
This is a warning callout.
:::

:::danger
This is a danger callout.
:::

:::neutral
This is a neutral callout.
:::

:::brand
This is a brand callout (official variant name, same as `info`).
:::

You can also add optional size and appearance parameters after the variant:

:::info small
A compact callout.
:::

:::warning large filled-outlined
A large warning with filled-outlined appearance.
:::

:::success accent
An accent callout that draws more attention.
:::

Size options: small, medium (default), large

Appearance options: accent, filled, outlined, plain, filled-outlined (default)

These transform into Web Awesome callout components with appropriate icons and styling.

Create before/after image comparisons using the ||| syntax:

|||
![Grayscale version](before.jpg)
![Color version](after.jpg)
|||

You can specify the initial position of the comparison slider (0-100):

|||25
![Grayscale version](before.jpg)
![Color version](after.jpg)
|||

This transforms into a Web Awesome comparison component that lets users interactively compare two images:

<wa-comparison position="25">
  <img slot="before" src="before.jpg" alt="Grayscale version" />
  <img slot="after" src="after.jpg" alt="Color version" />
</wa-comparison>

The comparison component requires exactly two images within the wrapper:

• The first image becomes the "before" slot
• The second image becomes the "after" slot
• Standard Markdown image syntax is preserved: ![alt text](image.url)
• Optional position parameter (0-100) sets the initial slider position

Note: If the comparison block doesn't contain exactly two images, it will be left unchanged rather than transformed.

Create cards using the === syntax:

===
This is a basic card with just content.
===

The first bold line (**text**) automatically becomes the card header:

===
**Card Title**
This is the card content that appears in the main area.
===

The first image automatically becomes the card media:

===
![Alt text](image.jpg)
**Featured Content**
This card includes both an image and a title.
===

Links at the end of the card content automatically become footer buttons:

===
**Get Started**
Ready to begin your journey?
[Learn More](https://example.com)
===

You can combine all elements for rich content cards:

===filled
![Hero Image](hero.jpg)
**Complete Example**
This card has media, header, content, and footer with a filled appearance.
[Get Started](https://example.com)
===

You can specify different visual styles:

===filled
**Filled Card**
This card uses the filled appearance.
===

===plain
**Plain Card**
This card uses the plain appearance.
===

===filled-outlined
**Filled Outlined Card**
This card uses the filled-outlined appearance.
===

===accent
**Accent Card**
This card uses the accent appearance for emphasis.
===

Cards can be displayed in horizontal layout for side-by-side presentation:

===horizontal
![Feature Image](feature.jpg)
**Horizontal Card**
This card displays with a side-by-side layout where media appears on the left.
===

===filled horizontal
![Product Photo](product.jpg)
**Combined Attributes**
You can combine appearance and orientation in any order.
===

Note: Horizontal cards display media on the left and content on the right. Make sure to set an appropriate max-width for the media slot in your CSS if needed.

Create carousels (image sliders/content rotators) using the ~~~~~~ syntax:

~~~~~~
~~~
![Mountain landscape](mountain.jpg)
Beautiful mountain scenery
~~~
~~~
![Ocean view](ocean.jpg)
Peaceful ocean waves
~~~
~~~
![Forest path](forest.jpg)
Walking through the woods
~~~
~~~~~~

Show multiple slides at once by specifying the number:

~~~~~~3
~~~
Product 1 content
~~~
~~~
Product 2 content
~~~
~~~
Product 3 content
~~~
~~~
Product 4 content
~~~
~~~~~~

Add navigation arrows and pagination dots with keywords:

~~~~~~navigation pagination
~~~
First slide
~~~
~~~
Second slide
~~~
~~~
Third slide
~~~
~~~~~~

Control how many slides advance at a time (first number is slides-per-page, second is slides-per-move):

~~~~~~3 2 navigation
~~~
Slide 1
~~~
~~~
Slide 2
~~~
~~~
Slide 3
~~~
~~~
Slide 4
~~~
~~~
Slide 5
~~~
~~~~~~

This shows 3 slides at a time and moves 2 slides when navigating.

Enable continuous looping with the loop keyword:

~~~~~~loop navigation
~~~
Slide 1
~~~
~~~
Slide 2
~~~
~~~
Slide 3
~~~
~~~~~~

Add padding to show adjacent slides as a hint using the scroll-hint CSS property:

~~~~~~scroll-hint:3rem navigation
~~~
![Photo 1](photo1.jpg)
~~~
~~~
![Photo 2](photo2.jpg)
~~~
~~~
![Photo 3](photo3.jpg)
~~~
~~~~~~

Combine multiple parameters for full control:

~~~~~~3 2 loop navigation pagination scroll-hint:2rem
~~~
![Product 1](prod1.jpg)

# Feature One

Description here
~~~
~~~
![Product 2](prod2.jpg)

# Feature Two

More details
~~~
~~~
![Product 3](prod3.jpg)

# Feature Three

Additional info
~~~
~~~~~~

For carousels with text content, cards, or variable-height slides, you may want to remove the default 16/9 aspect ratio to let content size naturally:

~~~~~~aspect-ratio:auto navigation
~~~
# First Slide

This carousel will size based on content height, not a fixed aspect ratio.

Perfect for text-heavy slides or mixed content.
~~~
~~~
# Second Slide

Another slide with different content height.
~~~
~~~~~~

Use aspect-ratio:auto or aspect-ratio:none to override the default fixed height behavior.

All parameters are optional and can be combined in any order:

~~~~~~vertical pagination autoplay
~~~
Content here
~~~
~~~~~~

Create tags using the @@@ syntax:

@@@
Basic tag
@@@

@@@brand
Version 2.0
@@@

@@@success
Completed
@@@

@@@warning
In Progress
@@@

@@@danger
Critical Issue
@@@

@@@neutral
Documentation
@@@

These transform into Web Awesome tag components with appropriate colors and styling.

Tags support flexible parameters in any order:

Variants:

@@@brand
Brand tag
@@@

@@@success
Success tag
@@@

@@@warning
Warning tag
@@@

@@@danger
Danger tag
@@@

@@@neutral
Neutral tag (default)
@@@

Appearance Styles:

@@@accent
Accent appearance
@@@

@@@filled
Filled appearance
@@@

@@@outlined
Outlined appearance
@@@

@@@filled-outlined
Filled-outlined appearance (default)
@@@

Sizes:

@@@small
Small tag
@@@

@@@medium
Medium tag (default)
@@@

@@@large
Large tag
@@@

Pill Shape:

@@@pill
Rounded tag
@@@

@@@brand pill
Brand tag with rounded edges
@@@

Removable Tags:

@@@with-remove
Removable tag
@@@

@@@success with-remove
Success tag with remove button
@@@

Combining Attributes:

All attributes work together in any order:

@@@brand accent small pill
Small brand tag with accent style and rounded edges
@@@

@@@success filled large with-remove
Large filled success tag with remove button
@@@

@@@pill large brand filled
Same tag - attributes can be in any order
@@@

Inline Tag Syntax:

Tags can also be used inline within paragraphs or headings:

Here's an inline @@@ brand v2.0 @@@ tag in a sentence.

## Feature @@@ success New @@@ Released

Status: @@@ warning Beta @@@ - testing in progress

Combine inline @@@ pill small success Ready @@@ with attributes

Create copy-to-clipboard buttons using the <<< syntax:

<<<
Copy this simple text
<<<

<<<
npm install jekyll-webawesome
<<<

Copy buttons support markdown formatting in the display text while preserving the original markdown in the clipboard value:

<<<
**Copy** this text with *markdown* formatting and `code`
<<<

This transforms into a Web Awesome copy button component:

<wa-copy-button value="**Copy** this text with *markdown* formatting and `code`"></wa-copy-button>

Copy buttons support flexible parameters in any order:

Tooltip Placement:

<<<top
Copy with tooltip on top (default)
<<<

<<<right
Copy with tooltip on right
<<<

<<<bottom
Copy with tooltip on bottom
<<<

<<<left
Copy with tooltip on left
<<<

Custom Labels:

<<<copy-label="Click to copy" success-label="Copied!" error-label="Failed"
Customize feedback messages
<<<

Feedback Duration:

<<<2000
Show success feedback for 2 seconds
<<<

<<<250 right
Quick feedback (250ms) with right tooltip
<<<

Disabled State:

<<<disabled
You can't copy this
<<<

<<<disabled bottom
Disabled with bottom tooltip
<<<

Copy from Another Element:

<<<from="my-element"
Copy from element with id="my-element"
<<<

<<<from="my-input.value"
Copy from input's value property
<<<

<<<from="my-link[href]"
Copy from link's href attribute
<<<

Combined Attributes:

<<<right disabled 1500 copy-label="Click to copy"
Multiple attributes in any order
<<<

<<<bottom 3000 copy-label="Copy" success-label="Done!" error-label="Error"
Full customization example
<<<

Copy buttons work well for:

• Code snippets and commands
• URLs and configuration values
• Installation instructions
• API keys or tokens
• Any text users might want to copy

Note: The value attribute contains the raw text (including any markdown) that gets copied to the clipboard. When using the from attribute, the button copies from the referenced element instead. The copy button displays the standard Web Awesome copy icon and handles the clipboard operation automatically.

Create interactive buttons using the %%% syntax. Buttons support both regular buttons and link buttons (with href):

%%%
Click me
%%%

%%%brand
Submit Form
%%%

%%%success
Save Changes
%%%

%%%danger
Delete Account
%%%

These transform into Web Awesome button components with the specified variants.

Create link buttons using markdown link syntax:

%%%brand
[Download](https://example.com/file.zip)
%%%

%%%success
[Get Started](https://example.com/start)
%%%

%%%
[Learn More](/docs)
%%%

Link buttons use the href attribute and behave like links (support CMD/CTRL+click, right-click, etc.).

Control the button's visual appearance with the appearance attribute:

%%%brand accent
Accent Button
%%%

%%%success filled
Filled Button
%%%

%%%warning outlined
Outlined Button
%%%

%%%danger filled-outlined
Filled-Outlined Button
%%%

%%%neutral plain
Plain Button
%%%

Available appearances: accent (default), filled, outlined, filled-outlined, plain

Buttons come in three sizes:

%%%small
Small Button
%%%

%%%medium
Medium Button
%%%

%%%large
Large Button
%%%

Available sizes: small, medium (default), large

Add the pill attribute for rounded edges:

%%%pill
Rounded Button
%%%

%%%brand pill large
Large Pill Button
%%%

%%%success pill
[Download Now](https://example.com/download)
%%%

Add the caret attribute to show a dropdown indicator:

%%%caret
Options ▼
%%%

%%%brand caret
Actions ▼
%%%

This adds a with-caret attribute to display a dropdown arrow, useful for buttons that trigger dropdowns or menus.

Buttons can have loading or disabled states:

%%%loading
Processing...
%%%

%%%disabled
Can't Click This
%%%

%%%brand loading
Saving Changes...
%%%

%%%danger disabled
[Delete](https://example.com/delete)
%%%

All button attributes can be combined in any order:

%%%brand filled large pill
Big Filled Button
%%%

%%%success outlined small pill caret
Small Options
%%%

%%%danger filled medium disabled
Cannot Delete
%%%

%%%neutral plain large loading
[Processing...](https://example.com/process)
%%%

Attributes work in any order:

• variant: brand, success, neutral, warning, danger
• appearance: accent, filled, outlined, filled-outlined, plain
• size: small, medium, large
• pill: rounded edges
• caret: dropdown indicator
• loading: loading state
• disabled: disabled state

Create interactive dialogs (modals) using the ??? syntax:

???
Open Dialog
>>>
This is the dialog content with **markdown** support.
???

This creates a trigger button and a dialog that opens when clicked:

<wa-button data-dialog='open dialog-abc123'>Open Dialog</wa-button>
<wa-dialog id='dialog-abc123' label='Open Dialog'>
  <p>This is the dialog content with <strong>markdown</strong> support.</p>
  <wa-button slot='footer' variant='primary' data-dialog='close'>Close</wa-button>
</wa-dialog>

The first heading (#) automatically becomes the dialog's label (title):

???
Show Details
>>>
# Important Information
This is the content of the dialog.
???

The button displays "Show Details" and the dialog header shows "Important Information".

You can customize dialog behavior with optional parameters:

Light Dismiss - Dialog closes when clicking the overlay:

???light-dismiss
Open Dialog
>>>
Click outside to close this dialog.
???

Custom Width - Set a specific width using CSS units (px, em, rem, vw, vh, %):

???600px
Open Dialog
>>>
This dialog is 600 pixels wide.
???

???50vw
Open Wide Dialog
>>>
This dialog is 50% of the viewport width.
???

???40em
Open Dialog
>>>
This dialog is 40em wide.
???

Combining Options - You can combine multiple options:

???light-dismiss 700px
Open Dialog
>>>
# Custom Dialog
This dialog has light dismiss enabled and is 700px wide.
???

Note: The dialog uses Web Awesome's declarative data-dialog API, so no custom JavaScript is needed. Each dialog gets a unique ID automatically generated from its content. The header with X close button is always shown for accessibility, and a "Close" button is automatically added to the footer.

Create collapsible content using the ^^^ syntax:

^^^
Click to expand this summary
>>>
This is the detailed content that can be collapsed and expanded.

You can include:
- Lists
- **Bold text**
- [Links](https://example.com)
- Code blocks
^^^

You can also specify appearance styles:

^^^filled
Filled appearance summary
>>>
Content goes here
^^^

^^^plain
Plain appearance summary  
>>>
Content goes here
^^^

^^^filled-outlined
Filled and outlined appearance summary
>>>
Content goes here
^^^

You can also control icon placement (expand/collapse icon location):

^^^start
Summary with icon on the start (left)
>>>
The expand/collapse icon appears on the left side
^^^

^^^end
Summary with icon on the end (right)
>>>
The expand/collapse icon appears on the right side (default)
^^^

You can combine appearance and icon placement:

^^^filled start
Filled appearance with icon on the start
>>>
Content with both styling and icon positioning
^^^

^^^plain end
Plain appearance with icon on the end
>>>
Parameters can be in any order: start filled, filled start, etc.
^^^

Prevent the details from expanding with the disabled flag:

^^^disabled
This summary cannot be expanded
>>>
This content is locked and cannot be viewed
^^^

Make the details open by default with the open flag:

^^^open
This summary is initially expanded
>>>
This content is visible when the page loads
^^^

Group multiple details with the name:group-id parameter to create accordion behavior where only one can be open at a time:

^^^name:faq-group open
First Question
>>>
Answer to the first question (initially open)
^^^

^^^name:faq-group
Second Question
>>>
Answer to the second question
^^^

^^^name:faq-group
Third Question
>>>
Answer to the third question
^^^

When one details element in the group opens, others with the same name automatically close.

All attributes can be combined in any order:

^^^filled start disabled
Disabled with custom styling
>>>
Content here
^^^

^^^filled-outlined open name:section-1
First Section (initially open)
>>>
Content for first section
^^^

^^^filled-outlined name:section-1
Second Section
>>>
Only one section can be open at a time
^^^

Available attributes:

• Appearance: outlined (default), filled, filled-outlined, plain
• Icon placement: start, end (default)
• Boolean flags: disabled, open
• Grouping: name:group-id (for accordion behavior)

Create tabbed content using the ++++++ syntax for tab groups and +++ for tabs.

++++++
+++ First Tab
Content for the first tab goes here.
+++

+++ Second Tab
Content for the second tab.
+++

+++ Third Tab
Content for the third tab.
+++
++++++

You can specify where tabs appear relative to content:

++++++start
+++ Tab 1
Content here
+++
+++ Tab 2
More content
+++
++++++

++++++bottom
+++ Tab 1
Content here
+++
+++ Tab 2
More content
+++
++++++

Supported placements: top (default), bottom, start, end

Set which tab is initially active by specifying the panel name:

++++++tab-3
+++ Tab 1
First panel
+++
+++ Tab 2
Second panel
+++
+++ Tab 3
This tab will be active on load
+++
++++++

Panel names follow the pattern tab-1, tab-2, tab-3, etc., or you can reference specific names if you're using custom IDs.

Control how keyboard navigation works with the activation attribute:

<!-- Auto activation (default) - arrow keys immediately show panels -->
++++++auto
+++ Tab 1
Content
+++
+++ Tab 2
Content
+++
++++++

<!-- Manual activation - arrow keys focus, but Space/Enter needed to show panel -->
++++++manual
+++ Tab 1
Content
+++
+++ Tab 2
Content
+++
++++++

Activation modes:

• auto (default) - Arrow keys immediately show the corresponding tab panel
• manual - Tab receives focus but requires Space or Enter to show panel

Disable scroll arrows for overflowing tabs:

++++++no-scroll-controls
+++ Tab 1
Content
+++
+++ Tab 2
Content
+++
+++ Tab 3
Content
+++
++++++

All attributes can be combined in any order:

++++++bottom manual tab-2 no-scroll-controls
+++ Tab 1
First panel
+++
+++ Tab 2
This tab will be active on load
+++
+++ Tab 3
Third panel
+++
++++++

You can also use the explicit :::wa-tab-group syntax:

:::wa-tab-group end manual advanced
+++ General
General settings
+++
+++ Advanced
Advanced settings - this tab is active initially
+++
:::

Cards support flexible attribute ordering using space-separated parameters:

Appearance:

Orientation:

Note: All attributes can be combined in any order (e.g., ===filled horizontal or ===horizontal filled).

Cards automatically parse content into these slots:

• Media: First image becomes media slot
• Header: First **bold line** becomes header slot
• Content: Remaining content becomes main content
• Footer: Trailing links become footer buttons

Note: All attributes can be combined in any order. For link buttons, use markdown link syntax: [Text](url).

• Automatic ID Generation: Each dialog gets a unique ID based on MD5 hash of its content
• Header with X Button: The header with X close button is always shown for accessibility
• Auto-close Button: A "Close" button is automatically added to the footer
• Declarative API: Uses Web Awesome's data-dialog attributes - no custom JavaScript needed
• Label Extraction: First # heading becomes the dialog label, or button text is used as fallback
• Markdown Support: Full markdown formatting in dialog content

Enable automatic image-to-dialog transformation in your _config.yml:

webawesome:
  # Simple boolean to enable
  image_dialog: true
  
  # Or configure with options
  image_dialog:
    enabled: true
    default_width: 90vh      # Default width for all image dialogs

When enabled, all markdown images automatically become clickable and open in full-size dialogs:

![Architecture Diagram](diagram.png)

Default Width: Set a default width for all image dialogs in the configuration. Images will use this width unless overridden in the title.

Control dialog width by adding a width parameter to the title (overrides default):

![Diagram](diagram.png "50%")        # Dialog width: 50%
![Photo](photo.jpg "800px")         # Dialog width: 800px
![Wide](image.png "90vw")           # Dialog width: 90% viewport

Supported width units: px, em, rem, vw, vh, %, ch

Opt-out by adding "nodialog" to the title:

![Small Icon](icon.svg "nodialog")

Features:

• Light-dismiss and headerless dialogs for clean UX
• Thumbnail displays at original size, dialog shows full-size
• Configurable default width for consistent sizing

• top (default)
• bottom
• start
• end

• Jekyll >= 3.7
• Kramdown >= 2.0
• Web Awesome CSS/JS loaded in your site

Bug reports and pull requests are welcome on GitHub at https://github.com/jannewaren/jekyll-webawesome.

The gem is available as open source under the terms of the MIT License.