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:

These content-focused components will get dedicated syntax in future releases:

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)

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

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