This document discusses using static site generators with Markdown to write content that can be reused in multiple places. It describes the customer's need to show content across different sections, the limitations of Markdown for this, and a solution using hidden includes to insert partial Markdown content while avoiding duplicate content. The solution provides flexibility for future products while keeping documentation writing in Markdown.

1. Bending Markdown
to Your Will With Your
Static Site Generator
Leon Barnard, Balsamiq

2. Anyone Else Have This Problem?

4. The Customer's Problem

5. What We Wanted

6. The Problems with Markdown

7. The Dilemma
How do we write content that can
show up in multiple places?

8. The Solution
* Hidden from search and other links

12. Limitations
• Can't include partial content. All or nothing (except front
matter).
• Requires duplicate empty "placeholder" files to insert
content into.
• Standard issues with "single source" models (see, e.g.,
http://idratherbewriting.com/2016/02/11/the-problem-with-
single-source-publishing/)
• Working around some of these though

13. Wins
• Provides a flexible framework for future product versions
• Allows us to continue to write only (mostly) markdown for
the content (no code needed for includes)

14. Thanks!