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 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.

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.
:::

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 heading (#) 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.
===

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.

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 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. The copy button displays the standard Web Awesome copy icon and handles the clipboard operation automatically.

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.
^^^

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 tab placement:

++++++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.

Cards automatically parse content into these slots:

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

• 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.