converting word to markdown

Scott and I used Microsoft Word for our Hands On Lab at Oracle Code One. This worked “mostly” fine. The quotes are because we had a one merge conflict when writing the instructions.

At the conference, an attendee (Barry Evans) said he had some improvements to the docs and he’d submit a pull request. Less than useful in Word so I asked him to email me with change tracking. i thought better of that and decided to convert to Markdown.

It wasn’t as bad as I thought:

  1. First, I used the Word to Markdown converter to do a first level pass
  2. Then I manually split it into a page per step (cut/paste) and changed the table of contents to links.
  3. Next, I converted the images to local ones in the repo.
  4. Finally, I did cleanup on code that didn’t format right, lists that were broken and using better code tags.

I used Visual Studio Code as the markdown editor. (I’ve been trying to get more comfortable with VS Code). I learned:

  • Having the markdown file in the left pane and a split view with the preview is nice. They even stay in sync with content/paging.
  • Command up/down goes to the top/bottom of the doc.
  • Home/End goes to the beginning/end of a line.
  • You can test markdown links directly in the preview editor.
  • The preview editor shows images so I could easily spot typos.

I tagged the repo version with the Word doc in case I ever want to go back to what it looked like.

 

Leave a Reply

Your email address will not be published. Required fields are marked *