Breakdown

Breaks large markdown text files into many smaller ones, based on markdown compatible markup commands.

Installation

Add this line to your application's Gemfile:

gem 'breakdown'

And then execute:

$ bundle

Or install it yourself as:

$ gem install breakdown

Usage

require 'breakdown'
Breakdown::process input_filename, output_dir

E.g. Breakdown::process my_huge_markdown_file.md, contents

Breakdown extends the function of markdown section breaks, providing simple controls for splitting large files.

Any valid markdown horizontal section may be used. The following are all valid breakdown commands:

* * * home
*** page-1 
***** page-2
- - - about
--------------------------------------- my_very_long_page_name

Breakdown will create a new markdown file for each valid horizontal rule it finds. The new file will contain all the text between the horizontal rule and the next rule it finds (or the end of the file). Each file is named using the supplied title, with .md appended to the title. A page called 'home' will be created as 'home.md'.

Any text at the start of a file that doesn't have a named section will be placed in a file 'index.md'.

Page numbering

Pages in a sequence can be automatically numbered using the :autonum directive, e.g.

*** :autonum section
My first section
*** :autonum section
My second section

A markdown file like this will be broken into two smaller files, one called section-1.md and the other section-2.md

Discarding pages

Any page section starting with the :discard directive will be skipped during the breakdown process, e.g.

*** first_page   
This page will created
*** :discard
This page will not

Using blocks

Passing a block to the Breakdown::process method allows an opportunity to modify the title and text of each section prior to writing out to a file.

Breakdown::process input_filename, output_dir do |section|
  section[:title] = section[:title].upcase
  section[:text] = convert_to_swedish_chef(section[:text])
  section
end

Each section is hash containing values for :title and :text keys. It's important to pass the modified section back (as the last statement in the block) so it can be accessed by the rest of the process method.

Typical uses for the block method is to add metadata to the head of a section's text, for example when using Breakdown to generate content for nanoc or Jekyll.

Contributing

Fork it
Create your feature branch (git checkout -b my-new-feature)
Commit your changes (git commit -am 'Add some feature')
Push to the branch (git push origin my-new-feature)
Create new Pull Request