docx2gfm 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d9a2da3b4b09ea75ecb7523a3a01e0b275237239acea98dbc20c1371afa8a3ea
+  data.tar.gz: 35624ce545980e73a9f931be6f94d5fb7e2c642a8854d2c75d1041cc9d3cb9d4
+SHA512:
+  metadata.gz: '0861e90f7edda3bb08c31f7e5963e3ed7db5866f9bb2e61787aa40a0ee2b48c3ca2d00dab1e44411df635004d2796f1025456979fb7ad46e291d0aec72ad88af'
+  data.tar.gz: e7a5df12dc792018f6c4ff469289e8d5d16cfc4feccfc62a2b507af11163778616ff0c3632f4a9cd398486abb26673abbb78df571c8851d76bd87e7b1d4684e7

data/.gitignore

@@ -0,0 +1,10 @@
+Gemfile.lock
+
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/

data/Gemfile

@@ -0,0 +1,6 @@
+source 'https://rubygems.org'
+
+git_source(:github) {|repo_name| "https://github.com/#{repo_name}" }
+
+# Specify your gem's dependencies in docx2gfm.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2019 Sebastian Spier
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/MOTIVATION.md

@@ -0,0 +1,19 @@
+# Motivation
+
+docx2gfm is a wrapper around [pandoc][pandoc], which does the heavy-lifting of the docx to markdown conversation. So why not use pandoc straight up you may ask?
+
+The best pandoc configuration that I could find so far is this:
+
+```
+pandoc examples/sample.docx --wrap=none --atx-headers --reference-links -f docx -t markdown-bracketed_spans-link_attributes-smart-simple_tables -s
+```
+
+It produces the markdown output as shown in [examples/sample-pure-pandoc.md](./examples/sample-pure-pandoc.md).
+
+While this is pretty good already, this markdown has the following shortcomings:
+
+* lists have superfluous spaces before each list item
+* HTML formatting for underlines is created e.g. `<span class="underline">In mattis lectus</span>` => one could use something similar to `sed -e 's/<[^>]*>//g'` to get rid of the HTML. However this will also remove the HTML placeholders for the images, which are good to keep.
+* less pretty reference-links at the end of the file
+
+[pandoc]: https://pandoc.org/installing.html

data/README.md

@@ -0,0 +1,82 @@
+# docx2gfm - docx to github-flavored-markdown converter
+
+If you need to convert `.docx` documents to markdown, then `docx2gfm` is for you, as it makes the process faster.
+
+"Don't tell me, show. me"! Ok ok! `docx2gfm` turns [this docx file](./examples/sample.docx) into [this markdown](./examples/sample.md). Also see the original [google Doc][gDoc].
+
+Some post-processing of the markdown is still required but `docx2gfm` already makes the conversion process much faster.
+
+## The Long Story
+
+I am maintaining an engineering blog, that uses [jekyll][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][gfm], as that is what [jekyll][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][pandoc]. In [MOTIVATION.md](./MOTIVATION.md) you find more about the technical approach we chose.
+
+## Installation
+
+- install ruby
+- install [pandoc][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))
+1. 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 links
+* Add code blocks
+* Add quotes
+* Add tables
+
+## Alternatives to docx2gfm
+
+* Word to Markdown Converter: [online](https://word-to-markdown.herokuapp.com/), [source](https://github.com/benbalter/word-to-markdown)
+* [Writage](http://www.writage.com) - 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](https://rubygems.org).
+
+## Contributing
+
+`docx2gfm` is far from perfect.
+Bug reports and pull requests are welcome on GitHub at [github.com/spier/docx2gfm](https://github.com/spier/docx2gfm).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+[uth]: https://underthehood.meltwater.com/
+[gfm]: https://guides.github.com/features/mastering-markdown/
+[gDoc]: https://docs.google.com/document/d/16Kww2ic-YgFKskfDxYJu6o_ooSF3IORJh8Ho7XbgngI/edit
+[pandoc]: https://pandoc.org/installing.html
+[jekyll]: https://jekyllrb.com

data/Rakefile

@@ -0,0 +1,2 @@
+require "bundler/gem_tasks"
+task :default => :spec

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "docx2gfm"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/docx2gfm

@@ -0,0 +1,4 @@
+#!/usr/bin/env ruby
+
+require 'docx2gfm'
+puts Docx2gfm::Runner.run()

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/docx2gfm.gemspec

@@ -0,0 +1,36 @@
+
+lib = File.expand_path("../lib", __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require "docx2gfm/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "docx2gfm"
+  spec.version       = Docx2gfm::VERSION
+  spec.authors       = ["Sebastian Spier"]
+  spec.email         = ["github@spier.hu"]
+
+  spec.summary       = "Convert a docx file, to github-flavored-markdown"
+  spec.description   = "Convert a docx file, to github-flavored-markdown. thin wrapper around pandoc."
+  spec.homepage      = "https://github.com/spier/docx2gfm"
+  spec.license       = "MIT"
+
+  # Prevent pushing this gem to RubyGems.org. To allow pushes either set the 'allowed_push_host'
+  # to allow pushing to a single host or delete this section to allow pushing to any host.
+  if spec.respond_to?(:metadata)
+    spec.metadata["allowed_push_host"] = "https://rubygems.org"
+  else
+    raise "RubyGems 2.0 or newer is required to protect against " \
+      "public gem pushes."
+  end
+
+  spec.files         = `git ls-files -z`.split("\x0").reject do |f|
+    f.match(%r{^(test|spec|features)/})
+  end
+  spec.bindir        = "bin"
+  spec.require_paths = ["lib"]
+
+  spec.executables << "docx2gfm"
+
+  spec.add_development_dependency "bundler", "~> 1.16"
+  spec.add_development_dependency "rake", "~> 10.0"
+end

data/examples/sample-pure-pandoc.md

@@ -0,0 +1,103 @@
+---
+title: '<span id="_iq8c5s4280y5" class="anchor"></span>A Google Doc (docx) for testing the markdown conversation with docx2gfm <img src="media/image1.jpg" style="width:1.77604in;height:1.98311in" />'
+---
+
+Nulla ante dui, efficitur ut accumsan id, imperdiet ac urna. Duis nec eros non ex posuere scelerisque. Duis non dui quam. Vivamus pretium pretium lacus sit amet volutpat. In sollicitudin massa euismod, consectetur est in, malesuada sem. Pellentesque ullamcorper ligula blandit lacinia cursus. Nunc sit amet quam dapibus, blandit lacus in, pellentesque lacus. Morbi varius est sapien, vel imperdiet turpis varius vitae. Sed laoreet eu magna vel dictum. Nullam eget iaculis nisl, et congue orci. Curabitur hendrerit fermentum sapien fringilla vehicula. Ut rutrum pretium ligula in accumsan. Donec sed facilisis justo.
+
+## What is this
+
+The document that you are looking at was produced by exporting [<span class="underline">this Google doc</span>] as a .docx file, and then running it through this experimental [<span class="underline">docx2gfm</span>] converter.
+
+Let's link to the [<span class="underline">github repo again</span>][<span class="underline">docx2gfm</span>] but with a different link name.
+
+## Emphasize section
+
+We **may be Bolder**, we *may be Italian* (ouch!), we ~~may be on Strike~~, or <span class="underline">under the line</span>.
+
+Not all of these work in [<span class="underline">github-flavored-markdown</span>], but that is ok. Remember it is a markup language, not a [<span class="underline">text formatting language</span>].
+
+## List section
+
+-   Nam leo ipsum, commodo ut quam in, ultrices dictum nibh. Donec vehicula velit mi, a vehicula ante bibendum id. Duis sit amet pellentesque nibh. Nunc pretium, enim in sodales sollicitudin, sem nisi porta leo, a tempor neque augue a felis.
+
+-   With bullets
+
+-   Mauris nec tempus enim, a porttitor leo. Sed eu varius elit. Cras aliquam felis non ante porta maximus. [<span class="underline">Mauris</span>] quis aliquam diam, ac vestibulum odio. Etiam et commodo tellus.
+
+1.  Numbered lists are great
+
+2.  If one comes after the …
+
+3.  … other
+
+-   Bullet A
+
+    -   Bullet A1
+
+    -   Bullet A2
+
+-   Bullet B
+
+    -   Bullet B1
+
+    -   Bullet B2
+
+-   Bullet C
+
+    -   Bullet C1
+
+        -   Bullet C1a
+
+## An image
+
+## Headline 1<img src="media/image1.jpg" style="width:6.27083in;height:2.3125in" />
+
+[<span class="underline">Lorem ipsum dolor sit amet</span>], consectetur adipiscing elit. Sed cursus laoreet leo, non tempor libero malesuada a. Donec commodo tempor neque, vitae tempor nibh. Vestibulum scelerisque purus ipsum, ac efficitur ipsum feugiat sit amet. Praesent luctus tincidunt ante at cursus. Etiam dignissim aliquet lacus, eu sodales nunc porttitor in. Nunc ut luctus purus. Donec eu vehicula enim. Vivamus eu hendrerit velit. Vivamus pellentesque facilisis ex molestie cursus. Fusce egestas tellus quis tortor cursus imperdiet. Vestibulum ante ipsum primis in faucibus orci luctus et ultrices posuere cubilia Curae; Donec facilisis ipsum nulla, eget dapibus lectus interdum vel. Nam leo ipsum, commodo ut quam in, ultrices dictum nibh. Donec vehicula velit mi, a vehicula ante bibendum id. Duis sit amet pellentesque nibh. Nunc pretium, enim in sodales sollicitudin, sem nisi porta leo, a tempor neque augue a felis.
+
+-   A list
+
+-   With bullets
+
+-   And even more bullets
+
+## Headline 2
+
+Nullam vehicula ac dolor ac ultrices. Integer lacinia urna eu vestibulum tempor. Ut lacus ante, scelerisque consectetur odio blandit, vulputate dapibus nunc. Curabitur mi ex, ullamcorper sit amet diam ac, blandit consectetur tellus. Pellentesque ut eros sit amet enim consequat fermentum at quis orci. In nunc eros, vestibulum mollis posuere non, venenatis a justo. Suspendisse tincidunt, mi vel tincidunt auctor, lacus sem hendrerit ex, eget maximus mi risus eu felis. Mauris nec tempus enim, a porttitor leo. Sed eu varius elit. Cras aliquam felis non ante porta maximus. [<span class="underline">Mauris</span>] quis aliquam diam, ac vestibulum odio. Etiam et commodo tellus.
+
+1.  Numbered lists are great
+
+2.  If one comes after the …
+
+3.  … other
+
+**Ut bibendum turpis ex**, id consequat elit euismod et. Nam lectus arcu, pharetra tincidunt iaculis a, interdum vitae arcu. <span class="underline">Cras ac lectus quis</span> risus laoreet scelerisque. Curabitur metus ex, sagittis sit amet quam vitae, consequat sodales velit. Nulla quis ex urna. Integer et tortor odio. Curabitur euismod feugiat mollis. *Nullam vestibulum tempus feugiat*. Vestibulum porta aliquam mauris non aliquet. Sed aliquam erat ac bibendum lacinia. Nam iaculis ornare lorem, sed consectetur dolor.
+
+[<span class="underline">In mattis lectus</span>] accumsan diam accumsan, in bibendum justo fringilla. Aenean lacinia aliquam ligula vel semper. Phasellus purus ipsum, condimentum in tellus nec, finibus consectetur elit. Nam fringilla, diam id dignissim sodales, magna elit tempor arcu, at pharetra nisi metus eget purus. Donec mollis ac leo in aliquet. Proin congue congue diam, ac euismod est blandit non. Aliquam ac efficitur eros. Mauris mollis commodo fermentum. Donec mattis sit amet risus nec vestibulum. Donec vel sollicitudixn dolor. Aliquam aliquet neque ac augue consequat porta. Praesent tristique lobortis tincidunt. Etiam dapibus consequat fringilla. Etiam ac orci a nunc rutrum finibus eget a turpis. Duis vitae venenatis magna, ut vulputate turpis. Nunc fringilla non tellus at egestas.
+
+## Table Tests
+
+| **TH 1** | **TH 2** | **TH 3** |
+|----------|----------|----------|
+| TD 1     | TD 2     | TD 3     |
+| TD 4     | TD 5     | TD 6     |
+| TD 7     | TD 8     | TD 9     |
+
+## Quote!
+
+Every once in a while you need a great quote. To do so, write your quote and then move the indentation level in the Google Doc to the right, as shown below:
+
+> Blogging is great for your charma.
+>
+> \- Sebastian Spier (2019)
+
+## Headline 3
+
+In closing: Goodbye!
+
+  [<span class="underline">this Google doc</span>]: https://docs.google.com/document/d/1oKGYVORih0GNC1CZHKv0d2IirCtcgMu0O1sifTfH5zo/edit#
+  [<span class="underline">docx2gfm</span>]: https://github.com/meltwater/docx2gfm
+  [<span class="underline">github-flavored-markdown</span>]: https://help.github.com/articles/basic-writing-and-formatting-syntax/
+  [<span class="underline">text formatting language</span>]: https://softwareengineering.stackexchange.com/questions/207727/why-there-is-no-markdown-for-underline
+  [<span class="underline">Mauris</span>]: https://underthehood.meltwater.com
+  [<span class="underline">Lorem ipsum dolor sit amet</span>]: https://loremipsum.io/
+  [<span class="underline">In mattis lectus</span>]: https://spier.hu

data/examples/sample.md

@@ -0,0 +1,112 @@
+---
+layout: post
+title: "YOUR POST TITLE"
+comments: true
+categories: [tag1, tag2, multi word tag]
+author: <a href="link to twitter, personal blog, linkedin, etc">YOUR NAME</a>
+image: "/images/own/post_directory/logo_image_NOT_SVG_FORMAT.png"
+---
+
+---
+title: '<span id="_iq8c5s4280y5" class="anchor"></span>A Google Doc (docx) for testing the markdown conversation with docx2gfm <img src="media/image1.jpg" style="width:1.77604in;height:1.98311in" />'
+---
+
+Nulla ante dui, efficitur ut accumsan id, imperdiet ac urna. Duis nec eros non ex posuere scelerisque. Duis non dui quam. Vivamus pretium pretium lacus sit amet volutpat. In sollicitudin massa euismod, consectetur est in, malesuada sem. Pellentesque ullamcorper ligula blandit lacinia cursus. Nunc sit amet quam dapibus, blandit lacus in, pellentesque lacus. Morbi varius est sapien, vel imperdiet turpis varius vitae. Sed laoreet eu magna vel dictum. Nullam eget iaculis nisl, et congue orci. Curabitur hendrerit fermentum sapien fringilla vehicula. Ut rutrum pretium ligula in accumsan. Donec sed facilisis justo.
+
+## What is this
+
+The document that you are looking at was produced by exporting [this Google doc][this-google-doc] as a .docx file, and then running it through this experimental [docx2gfm][docx2gfm] converter.
+
+Let's link to the [github repo again][docx2gfm] but with a different link name.
+
+## Emphasize section
+
+We **may be Bolder**, we *may be Italian* (ouch!), we ~~may be on Strike~~, or under the line.
+
+Not all of these work in [github-flavored-markdown][github-flavored-markdown], but that is ok. Remember it is a markup language, not a [text formatting language][text-formatting-language].
+
+## List section
+
+- Nam leo ipsum, commodo ut quam in, ultrices dictum nibh. Donec vehicula velit mi, a vehicula ante bibendum id. Duis sit amet pellentesque nibh. Nunc pretium, enim in sodales sollicitudin, sem nisi porta leo, a tempor neque augue a felis.
+
+- With bullets
+
+- Mauris nec tempus enim, a porttitor leo. Sed eu varius elit. Cras aliquam felis non ante porta maximus. [Mauris][mauris] quis aliquam diam, ac vestibulum odio. Etiam et commodo tellus.
+
+1. Numbered lists are great
+
+2. If one comes after the …
+
+3. … other
+
+- Bullet A
+
+    - Bullet A1
+
+    - Bullet A2
+
+- Bullet B
+
+    - Bullet B1
+
+    - Bullet B2
+
+- Bullet C
+
+    - Bullet C1
+
+        - Bullet C1a
+
+## An image
+
+## Headline 1<img src="media/image1.jpg" style="width:6.27083in;height:2.3125in" />
+
+[Lorem ipsum dolor sit amet][lorem-ipsum-dolor-sit-amet], consectetur adipiscing elit. Sed cursus laoreet leo, non tempor libero malesuada a. Donec commodo tempor neque, vitae tempor nibh. Vestibulum scelerisque purus ipsum, ac efficitur ipsum feugiat sit amet. Praesent luctus tincidunt ante at cursus. Etiam dignissim aliquet lacus, eu sodales nunc porttitor in. Nunc ut luctus purus. Donec eu vehicula enim. Vivamus eu hendrerit velit. Vivamus pellentesque facilisis ex molestie cursus. Fusce egestas tellus quis tortor cursus imperdiet. Vestibulum ante ipsum primis in faucibus orci luctus et ultrices posuere cubilia Curae; Donec facilisis ipsum nulla, eget dapibus lectus interdum vel. Nam leo ipsum, commodo ut quam in, ultrices dictum nibh. Donec vehicula velit mi, a vehicula ante bibendum id. Duis sit amet pellentesque nibh. Nunc pretium, enim in sodales sollicitudin, sem nisi porta leo, a tempor neque augue a felis.
+
+- A list
+
+- With bullets
+
+- And even more bullets
+
+## Headline 2
+
+Nullam vehicula ac dolor ac ultrices. Integer lacinia urna eu vestibulum tempor. Ut lacus ante, scelerisque consectetur odio blandit, vulputate dapibus nunc. Curabitur mi ex, ullamcorper sit amet diam ac, blandit consectetur tellus. Pellentesque ut eros sit amet enim consequat fermentum at quis orci. In nunc eros, vestibulum mollis posuere non, venenatis a justo. Suspendisse tincidunt, mi vel tincidunt auctor, lacus sem hendrerit ex, eget maximus mi risus eu felis. Mauris nec tempus enim, a porttitor leo. Sed eu varius elit. Cras aliquam felis non ante porta maximus. [Mauris][mauris] quis aliquam diam, ac vestibulum odio. Etiam et commodo tellus.
+
+1. Numbered lists are great
+
+2. If one comes after the …
+
+3. … other
+
+**Ut bibendum turpis ex**, id consequat elit euismod et. Nam lectus arcu, pharetra tincidunt iaculis a, interdum vitae arcu. Cras ac lectus quis risus laoreet scelerisque. Curabitur metus ex, sagittis sit amet quam vitae, consequat sodales velit. Nulla quis ex urna. Integer et tortor odio. Curabitur euismod feugiat mollis. *Nullam vestibulum tempus feugiat*. Vestibulum porta aliquam mauris non aliquet. Sed aliquam erat ac bibendum lacinia. Nam iaculis ornare lorem, sed consectetur dolor.
+
+[In mattis lectus][in-mattis-lectus] accumsan diam accumsan, in bibendum justo fringilla. Aenean lacinia aliquam ligula vel semper. Phasellus purus ipsum, condimentum in tellus nec, finibus consectetur elit. Nam fringilla, diam id dignissim sodales, magna elit tempor arcu, at pharetra nisi metus eget purus. Donec mollis ac leo in aliquet. Proin congue congue diam, ac euismod est blandit non. Aliquam ac efficitur eros. Mauris mollis commodo fermentum. Donec mattis sit amet risus nec vestibulum. Donec vel sollicitudixn dolor. Aliquam aliquet neque ac augue consequat porta. Praesent tristique lobortis tincidunt. Etiam dapibus consequat fringilla. Etiam ac orci a nunc rutrum finibus eget a turpis. Duis vitae venenatis magna, ut vulputate turpis. Nunc fringilla non tellus at egestas.
+
+## Table Tests
+
+| **TH 1** | **TH 2** | **TH 3** |
+|----------|----------|----------|
+| TD 1     | TD 2     | TD 3     |
+| TD 4     | TD 5     | TD 6     |
+| TD 7     | TD 8     | TD 9     |
+
+## Quote!
+
+Every once in a while you need a great quote. To do so, write your quote and then move the indentation level in the Google Doc to the right, as shown below:
+
+> Blogging is great for your charma.
+>
+> \- Sebastian Spier (2019)
+
+## Headline 3
+
+In closing: Goodbye!
+
+[this-google-doc]: https://docs.google.com/document/d/1oKGYVORih0GNC1CZHKv0d2IirCtcgMu0O1sifTfH5zo/edit#
+[docx2gfm]: https://github.com/meltwater/docx2gfm
+[github-flavored-markdown]: https://help.github.com/articles/basic-writing-and-formatting-syntax/
+[text-formatting-language]: https://softwareengineering.stackexchange.com/questions/207727/why-there-is-no-markdown-for-underline
+[mauris]: https://underthehood.meltwater.com
+[lorem-ipsum-dolor-sit-amet]: https://loremipsum.io/
+[in-mattis-lectus]: https://spier.hu

data/lib/docx2gfm.rb

@@ -0,0 +1,59 @@
+require 'docx2gfm/version'
+require 'docx2gfm/docx_gfm_converter'
+
+require 'pp'
+require 'optparse'
+
+module Docx2gfm
+
+  class Runner
+
+    def self.run
+
+      # set default values for options
+      options = {}
+      options[:jekyll] = true
+      options[:ref_style_links] = true
+
+      # specify available options for the CLI
+      parser = OptionParser.new do |opts|
+        opts.banner = 'Usage: docx2gfm [options]'
+
+        opts.on('-f', '--file FILE', '(required) The .docx file to convert to markdown') do |v|
+          options[:file] = v
+        end
+        opts.on('-j', '--[no-]jekyll', '(optional) Prefix the markdown output with a jekyll frontmatter. Default: --jekyll') do |v|
+          options[:jekyll] = v
+        end
+        opts.on('-r', '--[no-]ref-style-links', '(optional) Create reference style links at the end of the markdown. Default: --ref-style-links') do |v|
+          options[:ref_style_links] = v
+        end
+        opts.on('-h', '--help', 'Display this help screen') do
+          puts opts
+          exit
+        end
+      end
+
+      # most useful way of creating a required parameter with OptionParser
+      # https://stackoverflow.com/questions/1541294/how-do-you-specify-a-required-switch-not-argument-with-ruby-optionparser/1542658#1542658
+      begin
+        parser.parse!
+        mandatory = [:file]
+        missing = mandatory.select{ |param| options[param].nil? }
+        raise OptionParser::MissingArgument, missing.join(', ') unless missing.empty?
+      rescue OptionParser::ParseError => e
+        puts e
+        puts parser
+        exit
+      end
+
+      # pass on options to the Docx2Gfm Converter, and run the conversion
+      doc = DocxGfmConverter.new(options)
+      doc.process_markdown
+      puts doc
+
+    end #run
+
+  end #class
+
+end # module

data/lib/docx2gfm/assets/front-matter.md

@@ -0,0 +1,8 @@
+---
+layout: post
+title: "YOUR POST TITLE"
+comments: true
+categories: [tag1, tag2, multi word tag]
+author: <a href="link to twitter, personal blog, linkedin, etc">YOUR NAME</a>
+image: "/images/own/post_directory/logo_image_NOT_SVG_FORMAT.png"
+---

data/lib/docx2gfm/docx_gfm_converter.rb

@@ -0,0 +1,117 @@
+class DocxGfmConverter
+  attr_accessor :options, :content
+
+  def initialize(options)
+    @options = options
+  end
+
+  # perform all conversation and cleanup steps
+  def process_gfm()
+    docx_2_gfm(@options[:file])
+    cleanup_content_gfm()
+    create_ref_style_links() if @options[:ref_style_links]
+    add_frontmatter() if @options[:jekyll]
+  end
+
+  def process_markdown()
+    docx_2_markdown(@options[:file])
+    cleanup_content_markdown()
+    create_ref_style_links() if @options[:ref_style_links]
+    add_frontmatter() if @options[:jekyll]
+  end
+
+  # output this document (i.e. the markdown content)
+  def to_s
+    @content
+  end
+
+  # convert docx to initial markdown
+  def docx_2_gfm(file)
+    # TODO before reading the file, I could check if the file exists
+    # TODO check out pandoc options that might be useful e.g. --extract-media='/images/own/'
+    @content = `pandoc #{file} -f docx -t gfm --wrap=none`
+  end
+
+  def docx_2_markdown(file)
+    # TODO before reading the file, I could check if the file exists
+    # TODO check out pandoc options that might be useful e.g. --extract-media='/images/own/'
+    @content = `pandoc #{file} --wrap=none --atx-headers -f docx -t markdown-bracketed_spans-link_attributes-smart-simple_tables -s`
+  end
+
+  # this removes all sorts of strange stuff that pandoc generates when
+  # converting a .docx exported from Google Docs into GFM
+  def cleanup_content_gfm()
+    # remove escaping in front of exclamation marks
+    @content = @content.gsub /\\!/, '!'
+
+    # remove underlining of anchors. Anchors are styled by the markdown renderer, so no need to add any explicit formatting here pandoc!
+    # example: [<span class="underline">In mattis lectus</span>](https://spier.hu) => [In mattis lectus](https://spier.hu)
+    @content = @content.gsub /\[<span class="underline">(.*?)<\/span>\]/m,'[\1]'
+
+    # convert underlining of regular text (not anchors) into markdown syntax
+    # example: <span class="underline">Cras ac lectus quis</span> => _Cras ac lectus quis_
+    # Underlining text is not possible??? ok, so I could spit out a warning here, as the author used a formatting feature that our blog does not support
+    @content = @content.gsub /<span class="underline">(.*?)<\/span>/m,'\1'
+
+    # fix unordered lists
+    @content = @content.gsub(/^(\s*)- > /, '\1- ')
+    @content = @content.gsub(/^(\s*)> /, '\1  ')
+
+    # fix ordered lists
+    @content = @content.gsub(/^(\d+\.)  > /, '\1  ')
+
+    # remove `<!-- end list -->`
+    # See http://pandoc.org/MANUAL.html => "Ending a list"
+    @content = @content.gsub(/<!-- end list -->/,'')
+  end
+
+  def cleanup_content_markdown()
+    # remove underlining from links
+    @content = @content.gsub /\[<span class="underline">(.*?)<\/span>\]/m,'[\1]'
+
+    # remove underlining from all other text (and print a warning)
+    @content = @content.gsub(/<span class="underline">(.*?)<\/span>/m) do |match|
+      STDERR.puts "Underline is not supported in markdown. Removing underlining from '#{$1}'."
+      $1
+    end
+
+    # fix lists - remove unneccesary spacing before list items
+    # 1.  Numbered lists are great
+    # -   And even more bullets
+    @content = @content.gsub(/^(\s*)(-|\d+\.)\s+(\S)/, '\1\2 \3')
+
+    # fix spacing in front of reference links
+    @content = @content.gsub(/^ +(\[.+?\]:)/, '\1')
+  end
+
+  def add_frontmatter()
+    asset_file = File.join(File.dirname(__FILE__), '/assets/front-matter.md')
+    front_matter = open(asset_file).readlines().join()
+    @content = front_matter + "\n" + @content
+  end
+
+  def clean_link_placeholder(text)
+    text.downcase.gsub(/\s/,'-')
+  end
+
+  def create_ref_style_links()
+    # matcher = content.scan(/[^!]\[(?<text>.*?)\]\((?<url>.*?)\)/)
+    # TODO using named groups below would be more descriptive. Need to figure out how.
+    link_dictionary = {}
+
+    @content.gsub!(/([^!])\[(.*?)\]\((.*?)\)/) do |match|
+      cleaned_link_placeholder = clean_link_placeholder($2)
+      if not link_dictionary.has_key?($3)
+        link_dictionary[$3] = cleaned_link_placeholder
+      end
+      "#{$1}[#{$2}][#{link_dictionary[$3]}]"
+    end
+
+    # add link references to the end of the content
+    @content += "\n"
+    link_dictionary.each_pair do |url, label|
+        @content += "[#{label}]: #{url}\n"
+    end
+  end
+
+end #class

data/lib/docx2gfm/version.rb

@@ -0,0 +1,3 @@
+module Docx2gfm
+  VERSION = "0.2.0"
+end

metadata

@@ -0,0 +1,91 @@
+--- !ruby/object:Gem::Specification
+name: docx2gfm
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+platform: ruby
+authors:
+- Sebastian Spier
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2019-11-17 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.16'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.16'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+description: Convert a docx file, to github-flavored-markdown. thin wrapper around
+  pandoc.
+email:
+- github@spier.hu
+executables:
+- docx2gfm
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- Gemfile
+- LICENSE.txt
+- MOTIVATION.md
+- README.md
+- Rakefile
+- bin/console
+- bin/docx2gfm
+- bin/setup
+- docx2gfm.gemspec
+- examples/sample-pure-pandoc.md
+- examples/sample.docx
+- examples/sample.md
+- lib/docx2gfm.rb
+- lib/docx2gfm/assets/front-matter.md
+- lib/docx2gfm/docx_gfm_converter.rb
+- lib/docx2gfm/version.rb
+homepage: https://github.com/spier/docx2gfm
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.3
+signing_key: 
+specification_version: 4
+summary: Convert a docx file, to github-flavored-markdown
+test_files: []