Word Diff
Word Diff empowers you to be a Markdown person in a Microsoft Word world by automatically converting any Word document committed to a GitHub repo to Markdown.
How it works
Lets say you have a file called document.docx
and you commit it to your GitHub repo.
Word Diff will automatically make a second commit, along side your commit to add a document.md
file, with the contents of document.docx
converted to markdown. It'll even note that you're the commit author and copy over your commit message.
If you make changes and commit a new version of document.docx
, Word Diff will update the document.md
file, and if you delete document.docx
, document.md
gets deleted as well.
Under the hood, it uses word-to-markdown.
When you'd use this
If you're collaborating on text with someone:
- Using Git's native diff functionality, you can quickly verified what's changed or compare changes over time
- You can collaborate in Markdown/GitHub while the world collaborates via email/Word
Setup
- Create a bot account, and create a new personal access token with
public_repo
scope - Set the token as a
GITHUB_TOKEN
environmental variable. - Add the Word Diff server as a web hook on the repository, receiving push events. You can leave all other settings about formats as they are. Choose a shared secret token as
SECRET_TOKEN
which you then have to set on your server/hosting as well. See how you set it on heroku below. - for local use, you can also store those variables in .env which you then should add to your .gitignore
Running on Heroku
- If you are familiar with heroku, just do what you do. If not, follow the ruby guide for heroku until you are logged in https://devcenter.heroku.com/articles/getting-started-with-ruby
- Clone the worddiff repo to a local folder of your choosing. Create the .env file with the above mentioned
GITHUB_TOKEN
andSECRET_TOKEN
. - With heroku installed, do
heroku create
in the worddiff folder. This also adds a heroku remote to your local git repo. - In order to get LibreOffice installed, you'll want to run
heroku config:add BUILDPACK_URL=https://github.com/ddollar/heroku-buildpack-multi.git
. This will instruct Heroku to read the.buildpacks
file. Ideally do this before you push to heroku the first time. - Then set the two environment variable for Heroku:
heroku config:set GITHUB_TOKEN=yourTokenHere
andheroku config:set SECRET_TOKEN=yoursecretchosentoken
- Finally do
git push heroku master
and the app should be deployed. The heroku repo should have been added before. - When opening the website heroku tells you, there should be nothing there but no error either.
Troubleshooting
- Check logs.
- Check if webhook works at the repository.
Running locally
bundle exec rackup
- Follow the ngrok documentation to forward requests to your computer if you don't want to set up a development server