Markdown Helper

Contents

• Installation
• What's a Markdown Helper?
• How It Works
  • Restriction: git Only
  • Commented or Pristine?
• 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.
• 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).