Hawaiʻi's Technology Community

Write You're Own eBook in Markdown with Ruby and Github Pages

Many of us have either had the urge to write a book or spew some sort of long-winded excrement of words.  Maybe it's a story that's been bouncing around in your head, a piece of history you would like to document, or a coalescence of documentation/blog posts on a subject you are passionate about. Regardless of the reason they all require the same thing.  The ability to convert written text into a document or eBook format.  

Since I am a ruby developer I've gotten quite comfortable writing markdown for documentation or general formatted text content. So the ability to compose the book in markdown that supports Github style code snippets is a big plus for me. After some brief searching I found ruby gem called wordsmith that fit the bill pretty nicely with decent set of features.

  • Compose content in markdown with syntax highlighting for code snippets.
  • Simple directory structure that automatically generates the table of contents.
  • Generates eBooks in several popular formats
    • HTML with styles that are easy to customize
    • epub
    • mobi (kindle)
    • pdf

Note: The following example requires basic understanding of git/github, html & css, how to use ruby/rubygems,  as well as the command line.

Before installing maker sure to install the pandoc dependency listed in the README.  Don't forget to install the LaTeX library listed in the pandoc install instructions if you would like to generate a pdf version.  Also, kindlegen is required if mobi is one of your desired output formats.  

I've tested the gem using ruby 1.9.3-p392. It installs like any other gem:

gem install wordsmith --no-rdoc --no-ri

To create a new ebook project simply follow the usage instructions outlined in the README.  The required structure of the chapters and subsections are shockingly straight forward.  Simply write all your content and generate it to the desired format.  The gem sets up a git repository for the book automatically so it is a good idea to store the progress of your work in incremental and contextually related git commits. 

Initially the stylesheet that is included is pretty simple but would be easy to override by someone who possesses a bit of CSS know-how.  A custom header/footer can also be added to the eBook by editing the respectively named html files in the layout folder.

The wordsmith gem also includes a publish command. With this you can publish the html version of your eBook using github pages.

  1. Write and generate your ebook in the html format
  2. Commit to the master branch
  3. Create a repository on github named for your ebook but don't push anything to it. Also elect not to create a README file.
  4. Update the .git/config file for the ebook git repository so the origin remote is referencing your new repository on github.
  5. Run the command: wordsmith publish
  6. If the publish command fails for some reason push it up manually with the command: git push origin gh-pages:gh-pages

You can see an example I created based off the one wordsmith generates for every new project at

This is definitely a programmer's approach to writing an eBook and probably not for everyone, but I found it to be an entertaining exercise that I might use in future.  I have not done too much research on the products/tools that already exist in the eBook-creating world but would be curious what other options people have found and what they think of them.


Views: 2389


You need to be a member of TechHui to add comments!

Join TechHui

Comment by Kyle Oba on April 21, 2013 at 9:10pm

Did I mention that our website is running on GitHub Pages / Jekyll now?  With a few mods here and there...

Comment by Chris Sass on March 26, 2013 at 12:47pm

Thanks Mike & Kyle!

Producing content is always the hardest part :)

Comment by Mike King on March 26, 2013 at 9:16am

This is really cool Chris, I've actually thought about this before but never took the time to look in to publishing to other formats.

Posts like these make me want to drop self-hosted WordPress installs and use things like Octopress and Github setups like the above for all of my personal work.

Now I just need to create more content :D

Comment by Kyle Oba on March 25, 2013 at 11:16pm

Very interesting... yet another reason to use GitHub pages...  Thanks!


web design, web development, localization

© 2024   Created by Daniel Leuck.   Powered by

Badges  |  Report an Issue  |  Terms of Service