Breaks large markdown text files into many smaller ones
Ruby
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
lib
spec
.gitignore
Gemfile
LICENSE.txt
README.md
Rakefile
breakdown.gemspec

README.md

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

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.

Contributing

  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