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.
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
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.
docx2gfm you can do this conversion quickly, and have more time to write new blog posts ... or drink coffee :)
- install ruby
- install pandoc
- install this gem:
gem install docx2gfm
- download your Google Doc as a
my_post.docx(File >> Download as >> Microsoft Word (.docx))
- 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
- Add the correct image paths
- Double check code blocks
- Double check quotes
- Double check tables
Alternatives to docx2gfm
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.
docx2gfm is far from perfect.
Bug reports and pull requests are welcome on GitHub at github.com/spier/docx2gfm.
The gem is available as open source under the terms of the MIT License.