Language, software, photography and food

Simple Includes Using Markdown

I’ve been sending out a fair few messages to potential sponsors, applicants, volunteers and coaches for Rails Girls South Florida. To make this job easier, I edit all my documents using Markdown syntax.

I find myself repeating a lot of the same information, so in order to DRY up my Markdown files, I create them from several different components by using template folders. I do it this way because Markdown has no native way of including sub-documents into a main document.

  1. Each template folder contains symlinks to each section Markdown file.
  2. Each symlink is named so that it appears in the right order inside the final document.

Here’s what the folder structure looks like for my Rails Girls documents:

  applicant -> ../docs/ -> ../docs/ -> ../docs/
  coach -> ../docs/ -> ../docs/ -> ../docs/
  sponsor -> ../docs/ -> ../docs/ -> ../docs/ -> ../docs/

It’s very easy to link the right content inside the template folder. For example, when I created the coach template folder, I typed in the following commands:

mkdir coach                                         # Make a template folder and
cd coach/                                           # make it your current working directory
ln -s ../docs/                  # Symlink the intro/header
ln -s ../docs/  # Symlink the content section(s)
ln -s ../docs/                # Symlink the footer/signature
cat *.md                                            # To see how it looks on-screen
cat *.md > coaching.markdown                        # Make a complete markdown document
cat *.md | markdown > coaching.html                 # Generate HTML

I use to view Markdown files, so having a complete file is convenient for me.