matkm / docx2gfm

Converts a docx file to github-flavored-markdown

docx2gfm - docx to github-flavored-markdown converter

If you need to convert .docx documents to markdown, then docx2gfm helps you to make the process faster.

"Don't tell me, show me"! Ok ok! docx2gfm turns this docx file into this markdown. Also see the original google Doc.

For another example of docx2gfm in action, take a look at this blog post docx2gfm - Your friendly docx to markdown converter.

While some post-processing of the markdown is still required, docx2gfm already makes the conversion process much faster.

The Long Story

I am maintaining an engineering blog, that uses jekyll to generate static pages.

In our blogging process, the authors write blog post as a Google Doc to collect feedback. Once the post is ready for publishing, they convert the Google Doc to github-flavored-markdown, as that is what jekyll needs as input to render the HTML for the blog.

We used to do this conversion step manually. This was tedious, boring, and in parts error-prone.

With docx2gfm you can do this conversion quickly, and have more time to write new blog posts ... or drink coffee :)

Technically docx2gfm is a thin wrapper around pandoc. In MOTIVATION.md you find more about the technical approach we chose.

Installation

• install ruby
• install pandoc
• install this gem: gem install docx2gfm

Usage

1. download your Google Doc as a .docx file e.g. my_post.docx (File >> Download as >> Microsoft Word (.docx))
2. convert docx to github-flavored-markdown:

docx2gfm -f my_post.docx > my_post.md

To learn more about the available options please refer to the built-in help.

$ docx2gfm -h

Usage: docx2gfm [options]
    -f, --file FILE                  (required) The .docx file to convert to markdown
    -j, --[no-]jekyll                (optional) Prefix the markdown output with a jekyll frontmatter. Default: --jekyll
    -r, --[no-]ref-style-links       (optional) Create reference style links at the end of the markdown. Default: --ref-style-links
    -h, --help                       Display this help screen

Finishing touches for your markdown

The markdown produced by docx2gfm is good but not perfect. You still have to do some manual steps:

• Adapt the YAML Frontmatter (if you used the --jekyll option)
• Add the correct image paths
• Double check code blocks
• Double check quotes
• Double check tables

Alternatives to docx2gfm

• Word to Markdown Converter: online, source
• Writage - Markdown plugin for Microsoft Word

Development

After checking out the repo, run bin/setup to install dependencies. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

docx2gfm is far from perfect. Bug reports and pull requests are welcome on GitHub at github.com/spier/docx2gfm.

License

The gem is available as open source under the terms of the MIT License.