Examdown lets you evaluatie inline code examples in your Markdown documents. Include some special YAML front matter in your examples and Examdown will make sure its output is included in the code block output.
Examdown is distributed as a Ruby gem, which should be installed on most Macs and Linux systems. Once you have ensured you have a working installation of Ruby and Ruby gems, install the gem as follows from the command line:
% gem install examdown
Now you can use the
examdown input type with the Kramdown Markdown
library from your Ruby scripts:
require 'kramdown' require 'examdown' puts Kramdown::Document.new(ARGV, input: 'examdown').to_html
Examdown takes code blocks in Markdown documents and injects the code's output back into the original script. This allows you to include examples of shell scripts in your document and include the dynamically generated output of those scripts.
Defining runnable code blocks
Define a regular code block in your Markdown file. Then add some special properties using YAML front matter:
Here is some code: --- language: sh --- % echo "foo" Pretty neat, eh?
This example gets converted to (roughly) the following output:
<p>Here is some code:</p> <pre class="language-sh"><code>% echo "foo" foo </code></pre> <p>Pretty neat, eh?</p>
YAML front matter options
The following keys are read from the YAML front matter and used:
languagedefines the language of the code sample and thus how it should be run. Currently, only
shis accepted as value. This value is also added as class name for the wrapper element.
beforecontains an array of lines of code that should be run before the example but not included in the final output.
Example for a list of supported code runners.
Specify custom Kramdown parser
Kramdown::Document.new(content, input: 'examdown').to_html
Have code run to include its output
--- language: sh --- % echo foo
Using before steps
--- language: sh before: - cp /path/to/my-file --- % cat my-file
See the inline API docs for more information.
Note on Patches/Pull Requests
- Fork the project.
- Make your feature addition or bug fix.
- Add tests for it. This is important so I don't break it in a future version unintentionally.
- Commit, do not mess with rakefile, version, or history. (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
- Send me a pull request. Bonus points for topic branches.
Please report any issues, defects or suggestions in the Github issue tracker.
What has changed?
See the HISTORY file for a detailed changelog.