Breaks large markdown text files into many smaller ones
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


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


Add this line to your application's Gemfile:

gem 'breakdown'

And then execute:

$ bundle

Or install it yourself as:

$ gem install breakdown


require 'breakdown'
Breakdown::process input_filename, output_dir

E.g. Breakdown::process, 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 ''.

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

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 and the other

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])

Each section is hash containing values for :title and :text keys. Modifying the section will change the file content and title generated by the processor.

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.


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