extended-markdown-filter
Extended Markdown filters for the HTML::Pipeline.
Installation
Add this line to your application's Gemfile:
gem 'extended-markdown-filter'
And then execute:
$ bundle
Or install it yourself as:
$ gem install extended-markdown-filter
Usage
The simplest way to do this is
require 'extended-markdown-filter'
Then just use the HTML pipeline normally. With Jekyll, this is meant to be used with another plugin in conjunction, https://github.com/gjtorikian/jekyll-html-pipeline.
A minimum config file might look like:
gems:
- extended-markdown-filter
- jekyll-html-pipeline
markdown: HTMLPipeline
html_pipeline:
filters:
- "ExtendedMarkdownFilter"
context:
emf_use_blocks: true
Within Jekyll
Because of the Liquid template engine, if you use this filter with Jekyll, you might find that your curly brace tags--such as {{#tip}}
--disappear.
You'll need to pass the context emf_use_blocks
through your filter. This sets up a totally safe monkey-patch to convert the {{ }}
blocks into [[ ]]
, so that Liquid ignores them. Then, this renderer will convert the Markdown appropriately.
What does this add?
You may be wondering what features this filter adds to Markdown. Great question! Here's what we've got:
Command-line highlighting
A new pre block, command-line
, adds some divs to allow for better highlighting for terminal code.
Example
``` command-line
$ git remote add origin https://github.com/<em>user</em>/<em>repo</em>.git
# Set a new remote
> origin https://github.com/user/repo.git
```
$
represents content a user enters<em>
highlights content for the user#
represents comments>
represents output as a result of a command
Helper
The helper
notation wraps content in an accordion fold.
Example
``` helper
I'm not really important enough to show.
```
Admonition blocks
You can create separate, priority-colored callouts with {{#tip}}
, {{#note}}
, {{#warning}}
, and {{#error}}
tags.
Example
{{#tip}}
Here's a hot tip: **line one**
Here's a hot tip: line two
{{/tip}}
{{#note}}
You should probably know this! line one
You should probably know this! line two
{{/note}}
{{#warning}}
Yo, check this out: line one
Yo, check this out: line two
{{/warning}}
{{#danger}}
Sheeeeit, this is a problem: ~~line one~~
Sheeeeit, this is a problem: line two
{{/danger}}
Intro
The intro
block demarcates a special section that provides a summary of the content to follow.
Example
{{#intro}}
[Gists](https://gist.github.com) are a great way to share your work. You can share single files, parts of files, or full applications.
{{/intro}}
Octicon
The {{ octicon }}
helper lets you easily render any Octicon in the content, including an aria label.
Example
{{ octicon-gear The Settings gear }}
Operating system blocks
Sometimes, certain content needs to be rendered for only a certain operating system. Use {{#mac}}
of Mac OS specific content, {{#windows}}
for Windows, {{#linux}}
for Linux, and {{#all}}
as a catch-all for everything else.
Example
{{#mac}}
1. Command-click on the option.
{{/mac}}
{{#windows}}
1. Right click on the **Start** menu.
{{/windows}}
{{#linux}}
1. Open the terminal.
{{/linux}}
{{#all}}
1. Double-click on the icon.
{{/all}}