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)
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-riTo 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.
- Write and generate your ebook in the html format
- Commit to the master branch
- Create a repository on github named for your ebook but don’t push anything to it. Also elect not to create a README file.
- Update the .git/config file for the ebook git repository so the origin remote is referencing your new repository on github.
- Run the command:
$ wordsmith publish git@github.com:your_github_username/your_ebook_repository_name.git
- 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 http://lupinedev.github.com/wordsmith-example/
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.
Origninally posted on TechHui