Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/bridgetownrb/bridgetown-mdjs
Kramdown-based support for Markdown JavaScript (mdjs) in Bridgetown
https://github.com/bridgetownrb/bridgetown-mdjs
bridgetown bridgetown-plugin kramdown markdown
Last synced: 3 months ago
JSON representation
Kramdown-based support for Markdown JavaScript (mdjs) in Bridgetown
- Host: GitHub
- URL: https://github.com/bridgetownrb/bridgetown-mdjs
- Owner: bridgetownrb
- License: mit
- Created: 2021-03-05T17:25:53.000Z (almost 4 years ago)
- Default Branch: main
- Last Pushed: 2021-05-13T03:49:13.000Z (over 3 years ago)
- Last Synced: 2024-04-24T15:13:40.264Z (9 months ago)
- Topics: bridgetown, bridgetown-plugin, kramdown, markdown
- Language: Ruby
- Homepage:
- Size: 25.4 KB
- Stars: 3
- Watchers: 3
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.txt
Awesome Lists containing this project
README
# bridgetown-mdjs
> [!WARNING]
> This plugin is considered "as-is" and I don't anticpate developing it any further. If you submit an interesting PR, I'm willing to merge it, but otherwise…it's done.
----
A [Bridgetown](https://www.bridgetownrb.com) plugin to add Kramdown-based support for [Markdown JavaScript (mdjs)](https://rocket.modern-web.dev/docs/markdown-javascript/overview/).
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 `` 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:
```shell
$ 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.
```html
<!-- 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](https://github.com/bridgetownrb/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:
~~~markdown
# 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](https://github.com/bridgetownrb/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
1. Fork it (https://github.com/bridgetownrb/bridgetown-mdjs/fork)
2. Clone the fork using `git clone` to your local development machine.
3. Create your feature branch (`git checkout -b my-new-feature`)
4. Commit your changes (`git commit -am 'Add some feature'`)
5. Push to the branch (`git push origin my-new-feature`)
6. Create a new Pull Request