Markdown Helper
Contents
- Installation
- What's a Markdown Helper?
- How It Works
- Restriction:
git
Only - Commented or Pristine?
- Restriction:
- File Inclusion
- Re-use Text
- Include Generated Text
- Nest Inclusions
- Merged Text Formats
- Markdown
- Highlighted Code Block
- Plain Code Block
- Comment
- Details
- Pre-Formatted Text
- Usage
- CLI
- API
- Include Descriptions
- Example Include Descriptions
- Page TOC
- Diagnostics
- "Noisy" (Not Pristine)
- Missing Includee File
- Circular Inclusion
- Run
irb
- What Should Be Next?
Installation
gem install markdown_helper
What's a Markdown Helper?
Class MarkdownHelper
supports:
- File inclusion: to include text from other files, as code-block or markdown.
- Page TOC: to create and insert the table of contents for a markdown page.
- Run irb: to execute Ruby snippets in the Ruby interactive shell (
irb
) and include the output in markdown.
How It Works
The markdown helper is a preprocessor that reads a markdown document (template) and writes another markdown document.
The template can contain certain instructions that call for file inclusions.
Restriction: git
Only
The helper works only in a git
project: the working directory or one of ita parents must be a git directory -- one in which command git rev-parse --git-dir
succeeds.
Commented or Pristine?
By default, the output markdown has added comments that show:
- The path to the template file.
- The path to each included file.
You can suppress those comments using the pristine
option.
File Inclusion
This markdown helper enables file inclusion in GitHub markdown.
(Actually, this README file itself is built using file inclusion.)
See all use cases.
Re-use Text
Keep your markdown DRY (Don't Repeat Yourself) by re-using text. See the use case.
Include Generated Text
In particular, you can include text that's built during your "readme build." See the use case.
Nest Inclusions
You can nest inclusions. See the use case.
Merged Text Formats
Markdown
You can include text that is to be treated simply as markdown. See the use case.
Highlighted Code Block
You can include a code block that's to be highlighted. See the use case.
Plain Code Block
You can also include a code block without highlighting. See the use case.
Comment
You can include text that's to become a comment in the markdown. See the use case.
Details
You can include text that's to become details in the markdown. See the use case.
Pre-Formatted Text
You can include text that's pre-formatted. See the use case.
Usage
CLI
include.txt
:
Usage: markdown_helper include [options] template_file_path markdown_file_path
--pristine No comments added
--help Display help
where
* template_file_path is the path to an existing file.
* markdown_file_path is the path to a file to be created.
Typically:
* Both file types are .md.
* The template file contains file inclusion descriptions.
API
include_usage.rb
:
require 'markdown_helper'
template_file_path = 'highlight_ruby_template.md'
markdown_file_path = 'highlighted_ruby.md'
# Pristine.
markdown_helper = MarkdownHelper.new
markdown_helper.pristine = true
markdown_helper.include(template_file_path, markdown_file_path)
# Also pristine.
markdown_helper = MarkdownHelper.new(:pristine => true)
markdown_helper.include(template_file_path, markdown_file_path)
Include Descriptions
Specify each file inclusion at the beginning of a line via an include description, which has the form:
@[
format](
relative_file_path)
where:
-
format (in square brackets) is one of the following:
- Highlighting mode such as
[ruby]
, to include a highlighted code block. This can be any Ace mode mentioned in GitHub Languages. -
[:code_block]
, to include a plain code block. -
[:markdown]
, to include text markdown (to be rendered as markdown). -
[:comment]
, to include text as a markdown comment. -
[:pre]
, to include pre-formatted text. -
[:details]
, to include text as details.
- Highlighting mode such as
- relative_file_path points to the file to be included.
Example Include Descriptions
include.md
:
@[ruby](my_ruby.rb)
@[:code_block](my_language.xyzzy)
@[:markdown](my_markdown.md)
@[:comment](my_comment.txt)
@[:pre](my_preformatted.txt)
Page TOC
You can specify the location for an automatically-generated page TOC (table of cotents). See the use case.
Diagnostics
"Noisy" (Not Pristine)
By default, the markdown helper inserts comments indicating inclusions. See the use case.
Missing Includee File
A missing includee file causes an exception that shows an inclusion backtrace. See the use case.
Circular Inclusion
A circular inclusion causes an exception that shows an inclusion backtrace. See the use case.
Run irb
- Execute Ruby snippets in the Ruby interactive shell (
irb
) and include the output in markdown. See the use case.
What Should Be Next?
I have opened some enhancement Issues in the GitHub markdown_helper project:
- Project TOC: table of contents of all markdown pages in project.
- Partial file inclusion: including only specified lines from a file (instead of the whole file).
- Ruby-entity inclusion: like file inclusion, but including a Ruby class, module, or method.
- Pagination: series of markdown pages connected by prev/next navigation links.
Feel free to comment on any of these, or to add more Issues (enhancement or otherwise).