- What's a Markdown Helper?
- How It Works
- Commented or Pristine?
- File Inclusion
- Re-use Text
- Include Generated Text
- Nest Inclusions
- Merged Text Formats
- Highlighted Code Block
- Plain Code Block
- Pre-Formatted Text
- Include Descriptions
- Example Include Descriptions
- Page TOC
- "Noisy" (Not Pristine)
- Missing Includee File
- Circular Inclusion
- What Should Be Next?
gem install markdown_helper
What's a Markdown Helper?
- 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.
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
This markdown helper enables file inclusion in GitHub markdown.
(Actually, this README file itself is built using file inclusion.)
See all use cases.
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.
You can nest inclusions. See the use case.
Merged Text Formats
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.
You can include text that's to become a comment in the markdown. See the use case.
You can include text that's to become details in the markdown. See the use case.
You can include text that's pre-formatted. See the use case.
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.
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)
Specify each file inclusion at the beginning of a line via an include description, which has the form:
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
@[ruby](my_ruby.rb) @[:code_block](my_language.xyzzy) @[:markdown](my_markdown.md) @[:comment](my_comment.txt) @[:pre](my_preformatted.txt)
You can specify the location for an automatically-generated page TOC (table of cotents). See the use case.
"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.
A circular inclusion causes an exception that shows an inclusion backtrace. See the use case.
- 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).