Monday, December 10, 2018

How to create online html documentation from Word document

Suppose that you have your product’s documentation in the Word format and at some point decide to create online version of this documentation. Built-in convert to html works not very well so what other ways are available? Below you will find several possible ways to convert product documentation from Word to online version. These methods are based on Pandoc project which may convert document between many popular formats.

1. Word to EPUB and then to html

This method is based on the fact that EPUB format is internally based on html. As a bonus it splits the Word document into separate html documents per chapter. So if you have single big Word document with many images it will be divided into several html chapters which is better for online version than single big html page.

At first we need to convert Word to EPUB:

pandoc -f docx -t epub –o output.epub input.docx

After that you will have output.epub ebook. Change extension from epub to zip and unzip the file to the local folder. In EPUB subfolder of this folder you will find the following files structure:

image

Here media folder will contain all exported images from the Word file and nav.xhtml will contain clickable table of contents. And text subfolder will contain html files for particular chapters:

image

2. Word to Markdown and then visualize with MkDocs site generator

With this method we at first generate Word document to Markdown format using the same Pandoc tool:

pandoc -f docx -t markdown –o output.md input.docx --extract-media media

Here we explicitly specified folder where Pandoc should extract images from Word document. When we have got Markdown file we may create static site for it using MkDocs tool. With this tool we at first need to create new project folder and put mardown file with images there:

python -m mkdocs new test

It will also put the following mkdocs.yml file to site’s root folder:

site_name: My Docs

and then run:

python -m mkdocs serve

which will launch local web server which will host your online documentation. Also it is possible to choose different UI themes from the list of themes available on MkDocs site.

No comments:

Post a Comment