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.
- Each template folder contains symlinks to each section Markdown file.
- 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 00-intro.md -> ../docs/intro.md 01-apply.md -> ../docs/applying.md 99-footer.md -> ../docs/footer.md applying.html applying.markdown coach 00-intro.md -> ../docs/intro.md 01-coach.md -> ../docs/coaching-volunteering.md 99-footer.md -> ../docs/footer.md coaching.html coaching.markdown docs applying.md coaching-volunteering.md footer.md intro.md sponsor.md sponsor 00-intro.md -> ../docs/intro.md 02-sponsor.md -> ../docs/sponsor.md 03-coaching.md -> ../docs/coaching-volunteering.md 99-footer.md -> ../docs/footer.md sponsor.html sponsor.markdown
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
mkdir coach # Make a template folder and cd coach/ # make it your current working directory ln -s ../docs/intro.md 00-intro.md # Symlink the intro/header ln -s ../docs/coaching-volunteering.md 01-coach.md # Symlink the content section(s) ln -s ../docs/footer.md 99-footer.md # 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 Marked.app to view Markdown files, so having a complete file is convenient for me.