bridgetown-mdjs

A Bridgetown plugin to add Kramdown-based support for Markdown JavaScript (mdjs).

mdjs is a format which allows you to write executable JavaScript from within Markdown files. The mdjs-compatible parser will extract any fenced code block marked as js script and later include the extraction(s) within a <script type="module"> tag at the bottom of the page layout. This means you can import libraries and web components and define various bits of JS inline with your Markdown content.

(Note: While the mdjs support in Rocket includes stories and HTML component previews, in this initial release for Bridgetown we're only supporting the basic JavaScript code extractions.)

Requires Bridgetown 0.21 or higher.

Installation

Run this command to add this plugin to your site's Gemfile:

$ bundle add bridgetown-mdjs -g bridgetown_plugins

Then add either a Liquid tag or Ruby helper to your default layout right below the main content.

<!-- Liquid -->
<main>
   {{ content }}
   {% mdjs_script %}
</main>

<!-- ERB -->
<main>
  <%= yield %>
  <%= mdjs_script %>
</main>

Usage

The plugin will perform the necessary extractions (via the kramdown-parser-gfm-extractions add-on) to any Markdown file in your Bridgetown site.

Here's an example Markdown file where you can see mdjs in action:

# Introducing mdjs

Let's import some components from Skypack!

```js script
import SlIcon from "https://cdn.skypack.dev/@shoelace-style/shoelace/dist/components/icon/icon.js"
import SlIconButton from "https://cdn.skypack.dev/@shoelace-style/shoelace/dist/components/icon-button/icon-button.js"
import { setBasePath } from "https://cdn.skypack.dev/@shoelace-style/shoelace/dist/utilities/base-path.js"

setBasePath("https://cdn.skypack.dev/@shoelace-style/shoelace/dist")
```

## Hello from Shoelace!

<sl-icon-button name="emoji-smile" label="Yo!"></sl-icon-button>

And it's easy to change the DOM…

<aside id="hey-hey"></aside>

```js script
document.querySelector("#hey-hey").innerHTML = "<p>You you!</p>"
```

Optional configuration options

By default, extraction tags (inert, using template) aren't included in the rendered output HTML. You can change those options inside the kramdown namespace in bridgetown.config.yml. See kramdown-parser-gfm-extractions README for further details.

Testing

Run bundle exec rake test to run the test suite
Run rubocop to check for any style offenses.

Releasing

Run bundle exec rake test_and_release to verify rubocop and tests before releasing a new gem.

Contributing

Fork it (https://github.com/bridgetownrb/bridgetown-mdjs/fork)
Clone the fork using git clone to your local development machine.
Create your feature branch (git checkout -b my-new-feature)
Commit your changes (git commit -am 'Add some feature')
Push to the branch (git push origin my-new-feature)
Create a new Pull Request

Releasing (you can delete this section in your own plugin repo)

To release a new version of the plugin, simply bump up the version number in both version.rb and package.json, and then run script/release. This will require you to have a registered account with both the RubyGems.org and NPM registries. You can optionally remove the package.json and frontend folder if you don't need to package frontend assets for Webpack.

If you run into any problems or need further guidance, please check out our Bridgetown community resources where friendly folks are standing by to help you build and release your plugin or theme.

NOTE: make sure you add the bridgetown-plugin topic to your plugin's GitHub repo so the plugin or theme will show up on Bridgetown's official Plugin Directory! (There may be a day or so delay before you see it appear.)