All Articles

Generating Markdown Post Templates

TL;DR: Use Gulp, go here for example

I decided to rebuild my blog last weekend by enriching a version of the great Gatsby-starter-lumen project with the additions of light and dark mode and a few hidden template pages. One of the useful things that comes out of using a starter is it inevitably allows you to avoid the benefit of not having to build something from scratch and try to over engineering some aspect to the nth percent. Like any normal developer I immediately took the bait and decided creating and naming files was too hard, and a markdown generator for all my new posts would be perfect.

How I got to that conclusion of my own file generator was that the starter template doesn’t cover or create the naming of the post files and the meta data required for each post page by default. Expecting a format of YYYY-DD-MM---title-with-spacers.md with meta data in every file like so:

---
title: Generating Markdown Post Templates
date: 2020-07-27T20:57:45.961Z
template: "post"
draft: false
slug: generating-markdown-post-templates
category: "Blog"
tags:
- "Generators"
- "Javascript"
description: "The Tricky thing about creating your own generators"
socialImage: ""
---

That’s a lot of overhead when creating a new post! Particularly around the dates and making sure its formatted right. I didn’t particularly like it and though the easiest way to lower that barrier to entry was to automate it with Gulp.

In the quickly moving world of JavaScript Gulp might be considered old school now, but it is an incredible tool to help automate workflows and it reduces my file making overhead. At its core a Gulpfile is like a JS version of a Makefile which basically encapsulates shell commands as rules to help run, build, or generate a program. A Gulpfile.js at high level does the same thing with Javascript as the scripting language instead of shell.

Taking a closer look at how a Gulpfile works I created a hello world example here that you can clone down and checkout. Very simply the Gulpfile.js below takes in a template file in /src and pipes it to a new /output directory with nothing changed. You can run npm run run-gulp to see for yourself.

const { src, dest } = require("gulp");

exports.default = function () {
  return src("src/*.js").pipe(dest("output"));
};

Using that same logic now take a look at the master branch and you’ll see what’s changed in the /src directory to template our output file. Using the command from the readme: npm run new-post -- --name PostTitleName it gets passed to the gulp new-post task and we can break down from there. Using Yargs to parse the -- --name PostTitleName input we pass our intended file name to our Gulpfile below.

const gulp = require("gulp");
const yargs = require("yargs");
const { join } = require("path");
const rename = require("gulp-rename");
const template = require("gulp-template");

gulp.task("new-post", () => {
  const { name } = yargs.argv;
  const lowerCaseName = name.toLowerCase();
  const pascalCaseName = name.replace(
    /\w+/g,
    (w) => w[0].toUpperCase() + w.slice(1).toLowerCase()
  );
  const splitCaseName = name.replace(/([a-z])([A-Z])/g, "$1 $2");
  const slugCaseName = name.replace(/([a-z])([A-Z])/g, "$1-$2").toLowerCase();

  const newDate = new Date();
  const date = newDate.toISOString();
  const titleDate = newDate.toLocaleDateString("ug-CN");

  const srcPath = join(__dirname, "src", "new-post.**");
  const destPath = join(__dirname, "output", "/posts");

  return gulp
    .src(srcPath)
    .pipe(
      template({
        name,
        lowerCaseName,
        pascalCaseName,
        slugCaseName,
        splitCaseName,
        date,
      })
    )
    .pipe(
      rename(
        (filePath) =>
          (filePath.basename = filePath.basename.replace(
            "template",
            `${titleDate}-${slugCaseName}`
          ))
      )
    )
    .pipe(gulp.dest(destPath));
});

Working through the tree, we need to deal with two things largely, creating different casing variations for the name and the date format. The title I feel is simple enough using regex replace functions we can generate the different casing permutations that we need for the metadata. Where things start to get a bit odd is the date format. Creating a date is simple enough (new Date() ) but getting it in the correct YYYY-DD-MM format can actually be a bit tricky. If we were to accept the new date generated we’d end up with something like 2020-07-27T20:57:45.961Z which is useful for the exact datetime requirement, but is overkill for the file name. Luckily Javascript has a built in method to deal with that called .toLocaleDateString() which converts our datetime format to a more readable date string. Interestingly enough the possible formats for the local date string aren’t easily discoverable so I’ll list them down below:

   "ar-SA" : "dd/MM/yy",
   "bg-BG" : "dd.M.yyyy",
   "ca-ES" : "dd/MM/yyyy",
   "zh-TW" : "yyyy/M/d",
   "cs-CZ" : "d.M.yyyy",
   "da-DK" : "dd-MM-yyyy",
   "de-DE" : "dd.MM.yyyy",
   "el-GR" : "d/M/yyyy",
   "en-US" : "M/d/yyyy",
   "fi-FI" : "d.M.yyyy",
   "fr-FR" : "dd/MM/yyyy",
   "he-IL" : "dd/MM/yyyy",
   "hu-HU" : "yyyy. MM. dd.",
   "is-IS" : "d.M.yyyy",
   "it-IT" : "dd/MM/yyyy",
   "ja-JP" : "yyyy/MM/dd",
   "ko-KR" : "yyyy-MM-dd",
   "nl-NL" : "d-M-yyyy",
   "nb-NO" : "dd.MM.yyyy",
   "pl-PL" : "yyyy-MM-dd",
   "pt-BR" : "d/M/yyyy",
   "ro-RO" : "dd.MM.yyyy",
   "ru-RU" : "dd.MM.yyyy",
   "hr-HR" : "d.M.yyyy",
   "sk-SK" : "d. M. yyyy",
   "sq-AL" : "yyyy-MM-dd",
   "sv-SE" : "yyyy-MM-dd",
   "th-TH" : "d/M/yyyy",
   "tr-TR" : "dd.MM.yyyy",
   "ur-PK" : "dd/MM/yyyy",
   "id-ID" : "dd/MM/yyyy",
   "uk-UA" : "dd.MM.yyyy",
   "be-BY" : "dd.MM.yyyy",
   "sl-SI" : "d.M.yyyy",
   "et-EE" : "d.MM.yyyy",
   "lv-LV" : "yyyy.MM.dd.",
   "lt-LT" : "yyyy.MM.dd",
   "fa-IR" : "MM/dd/yyyy",
   "vi-VN" : "dd/MM/yyyy",
   "hy-AM" : "dd.MM.yyyy",
   "az-Latn-AZ" : "dd.MM.yyyy",
   "eu-ES" : "yyyy/MM/dd",
   "mk-MK" : "dd.MM.yyyy",
   "af-ZA" : "yyyy/MM/dd",
   "ka-GE" : "dd.MM.yyyy",
   "fo-FO" : "dd-MM-yyyy",
   "hi-IN" : "dd-MM-yyyy",
   "ms-MY" : "dd/MM/yyyy",
   "kk-KZ" : "dd.MM.yyyy",
   "ky-KG" : "dd.MM.yy",
   "sw-KE" : "M/d/yyyy",
   "uz-Latn-UZ" : "dd/MM yyyy",
   "tt-RU" : "dd.MM.yyyy",
   "pa-IN" : "dd-MM-yy",
   "gu-IN" : "dd-MM-yy",
   "ta-IN" : "dd-MM-yyyy",
   "te-IN" : "dd-MM-yy",
   "kn-IN" : "dd-MM-yy",
   "mr-IN" : "dd-MM-yyyy",
   "sa-IN" : "dd-MM-yyyy",
   "mn-MN" : "yy.MM.dd",
   "gl-ES" : "dd/MM/yy",
   "kok-IN" : "dd-MM-yyyy",
   "syr-SY" : "dd/MM/yyyy",
   "dv-MV" : "dd/MM/yy",
   "ar-IQ" : "dd/MM/yyyy",
   "zh-CN" : "yyyy/M/d",
   "de-CH" : "dd.MM.yyyy",
   "en-GB" : "dd/MM/yyyy",
   "es-MX" : "dd/MM/yyyy",
   "fr-BE" : "d/MM/yyyy",
   "it-CH" : "dd.MM.yyyy",
   "nl-BE" : "d/MM/yyyy",
   "nn-NO" : "dd.MM.yyyy",
   "pt-PT" : "dd-MM-yyyy",
   "sr-Latn-CS" : "d.M.yyyy",
   "sv-FI" : "d.M.yyyy",
   "az-Cyrl-AZ" : "dd.MM.yyyy",
   "ms-BN" : "dd/MM/yyyy",
   "uz-Cyrl-UZ" : "dd.MM.yyyy",
   "ar-EG" : "dd/MM/yyyy",
   "zh-HK" : "d/M/yyyy",
   "de-AT" : "dd.MM.yyyy",
   "en-AU" : "d/MM/yyyy",
   "es-ES" : "dd/MM/yyyy",
   "fr-CA" : "yyyy-MM-dd",
   "sr-Cyrl-CS" : "d.M.yyyy",
   "ar-LY" : "dd/MM/yyyy",
   "zh-SG" : "d/M/yyyy",
   "de-LU" : "dd.MM.yyyy",
   "en-CA" : "dd/MM/yyyy",
   "es-GT" : "dd/MM/yyyy",
   "fr-CH" : "dd.MM.yyyy",
   "ar-DZ" : "dd-MM-yyyy",
   "zh-MO" : "d/M/yyyy",
   "de-LI" : "dd.MM.yyyy",
   "en-NZ" : "d/MM/yyyy",
   "es-CR" : "dd/MM/yyyy",
   "fr-LU" : "dd/MM/yyyy",
   "ar-MA" : "dd-MM-yyyy",
   "en-IE" : "dd/MM/yyyy",
   "es-PA" : "MM/dd/yyyy",
   "fr-MC" : "dd/MM/yyyy",
   "ar-TN" : "dd-MM-yyyy",
   "en-ZA" : "yyyy/MM/dd",
   "es-DO" : "dd/MM/yyyy",
   "ar-OM" : "dd/MM/yyyy",
   "en-JM" : "dd/MM/yyyy",
   "es-VE" : "dd/MM/yyyy",
   "ar-YE" : "dd/MM/yyyy",
   "en-029" : "MM/dd/yyyy",
   "es-CO" : "dd/MM/yyyy",
   "ar-SY" : "dd/MM/yyyy",
   "en-BZ" : "dd/MM/yyyy",
   "es-PE" : "dd/MM/yyyy",
   "ar-JO" : "dd/MM/yyyy",
   "en-TT" : "dd/MM/yyyy",
   "es-AR" : "dd/MM/yyyy",
   "ar-LB" : "dd/MM/yyyy",
   "en-ZW" : "M/d/yyyy",
   "es-EC" : "dd/MM/yyyy",
   "ar-KW" : "dd/MM/yyyy",
   "en-PH" : "M/d/yyyy",
   "es-CL" : "dd-MM-yyyy",
   "ar-AE" : "dd/MM/yyyy",
   "es-UY" : "dd/MM/yyyy",
   "ar-BH" : "dd/MM/yyyy",
   "es-PY" : "dd/MM/yyyy",
   "ar-QA" : "dd/MM/yyyy",
   "es-BO" : "dd/MM/yyyy",
   "es-SV" : "dd/MM/yyyy",
   "es-HN" : "dd/MM/yyyy",
   "es-NI" : "dd/MM/yyyy",
   "es-PR" : "dd/MM/yyyy",
   "am-ET" : "d/M/yyyy",
   "tzm-Latn-DZ" : "dd-MM-yyyy",
   "iu-Latn-CA" : "d/MM/yyyy",
   "sma-NO" : "dd.MM.yyyy",
   "mn-Mong-CN" : "yyyy/M/d",
   "gd-GB" : "dd/MM/yyyy",
   "en-MY" : "d/M/yyyy",
   "prs-AF" : "dd/MM/yy",
   "bn-BD" : "dd-MM-yy",
   "wo-SN" : "dd/MM/yyyy",
   "rw-RW" : "M/d/yyyy",
   "qut-GT" : "dd/MM/yyyy",
   "sah-RU" : "MM.dd.yyyy",
   "gsw-FR" : "dd/MM/yyyy",
   "co-FR" : "dd/MM/yyyy",
   "oc-FR" : "dd/MM/yyyy",
   "mi-NZ" : "dd/MM/yyyy",
   "ga-IE" : "dd/MM/yyyy",
   "se-SE" : "yyyy-MM-dd",
   "br-FR" : "dd/MM/yyyy",
   "smn-FI" : "d.M.yyyy",
   "moh-CA" : "M/d/yyyy",
   "arn-CL" : "dd-MM-yyyy",
   "ii-CN" : "yyyy/M/d",
   "dsb-DE" : "d. M. yyyy",
   "ig-NG" : "d/M/yyyy",
   "kl-GL" : "dd-MM-yyyy",
   "lb-LU" : "dd/MM/yyyy",
   "ba-RU" : "dd.MM.yy",
   "nso-ZA" : "yyyy/MM/dd",
   "quz-BO" : "dd/MM/yyyy",
   "yo-NG" : "d/M/yyyy",
   "ha-Latn-NG" : "d/M/yyyy",
   "fil-PH" : "M/d/yyyy",
   "ps-AF" : "dd/MM/yy",
   "fy-NL" : "d-M-yyyy",
   "ne-NP" : "M/d/yyyy",
   "se-NO" : "dd.MM.yyyy",
   "iu-Cans-CA" : "d/M/yyyy",
   "sr-Latn-RS" : "d.M.yyyy",
   "si-LK" : "yyyy-MM-dd",
   "sr-Cyrl-RS" : "d.M.yyyy",
   "lo-LA" : "dd/MM/yyyy",
   "km-KH" : "yyyy-MM-dd",
   "cy-GB" : "dd/MM/yyyy",
   "bo-CN" : "yyyy/M/d",
   "sms-FI" : "d.M.yyyy",
   "as-IN" : "dd-MM-yyyy",
   "ml-IN" : "dd-MM-yy",
   "en-IN" : "dd-MM-yyyy",
   "or-IN" : "dd-MM-yy",
   "bn-IN" : "dd-MM-yy",
   "tk-TM" : "dd.MM.yy",
   "bs-Latn-BA" : "d.M.yyyy",
   "mt-MT" : "dd/MM/yyyy",
   "sr-Cyrl-ME" : "d.M.yyyy",
   "se-FI" : "d.M.yyyy",
   "zu-ZA" : "yyyy/MM/dd",
   "xh-ZA" : "yyyy/MM/dd",
   "tn-ZA" : "yyyy/MM/dd",
   "hsb-DE" : "d. M. yyyy",
   "bs-Cyrl-BA" : "d.M.yyyy",
   "tg-Cyrl-TJ" : "dd.MM.yy",
   "sr-Latn-BA" : "d.M.yyyy",
   "smj-NO" : "dd.MM.yyyy",
   "rm-CH" : "dd/MM/yyyy",
   "smj-SE" : "yyyy-MM-dd",
   "quz-EC" : "dd/MM/yyyy",
   "quz-PE" : "dd/MM/yyyy",
   "hr-BA" : "d.M.yyyy.",
   "sr-Latn-ME" : "d.M.yyyy",
   "sma-SE" : "yyyy-MM-dd",
   "en-SG" : "d/M/yyyy",
   "ug-CN" : "yyyy-M-d",
   "sr-Cyrl-BA" : "d.M.yyyy",
   "es-US" : "M/d/yyyy"

You’ll notice there are a few different options that have the correct YYYY-DD-MM format but the one that worked the most consistently for me was the ug-CN format. Decided not to explore this much further, but at a glance it’s one of the few formats that starts year first and uses - instead of /.

If you’ve made it this far, after running the above npm run new-post -- --name PostTitleName command should output a file in the output directory with everything templated out and the ability to start writing straight away!

If you have any Questions feel free to shoot me an email or open an issue on github here.