Using Markdown to create a boilerplate document for reports and proposals

Following on from our post Cutting and pasting content into Word documents – Is there a better way?, we’ve been looking at how organisations could use Markdown to create reports and proposals more quickly and consistently.

The objective was to:

• Create something simple for non-technical people to use.
• Have a collection of re-usable chunks of content that could be embedded into the document (no more cutting and pasting). If a chunk needed to be changed, then the documents where it is embedded would reflect that change automatically.
• Be able to generate the completed report as a .docx (Microsoft Word) file.
• Separate the content from the “look and feel”.
• Enable different people to work on different sections of the document simultaneously.
• Store the content in an open format, so there was potential to use some of the content in other places (such as on a website).

We built a proposal writing boilerplate system, based on Markdown. It currently generates a 26 page Word document (it would be longer if we wrote some more content):

The different sections of the report are stored as individual markdown files, with a master file that embeds all the individual files into a single document. This single Markdown document is then exported as a .docx file.

The image below shows the Markdown files for a proposal to ABC Co., stored on SharePoint. Different team members can check out the individual sections in the proposal to work on them, and then check them back in when they’ve finished.

The individual Markdown files are simple text files (saved as .md). For example, here is a file that stores one of the reusable chunks of information:

The client’s company name, the contact name, and other variable data are stored in a single place. By changing the company name in this location, all occurrences of name throughout the report will change automatically.

Please note, we avoided using any command line scripts in this solution.

As it stands, it lacks certain capabilities you’d get with a Help authoring tool or a content management system:

• There’s no automatic link management. If you change a filename or move a file to a different folder, the report might not work correctly.
• There’s no conditional text. Content doesn’t filter automatically based on different users or outputs.
• There’s only a limited number of styles writers can use.

However, as an easy-to-use and simple solution for creating the type of common reports and proposals generated by organisations, it worked.