Markdown Publishing CLI

Project roadmap

1. 01

   Define the rules

   ~1.5h

   Write README.md: the input folder structure, the front matter fields (title required, date required in YYYY-MM-DD, tags as a list, draft optional, slug optional), how slugs are made (from the title: lowercase, accents removed, dashes, and must be unique), the output structure (/posts/slug/index.html, /tags/tag/index.html and an index page), and the command (publish build SRC OUT, with --drafts). Create a gem skeleton with bundle gem. Done when: README.md defines the rules and output.

2. 02

   Parse and validate front matter

   ~2h

   Split each file into front matter and body, and parse the front matter with YAML.safe_load (allowing only simple types and dates). Validate each field and collect every error with the file name, then print them all together and exit with code 1 before writing anything. Check slugs are unique across all articles. Done when: a folder with several mistakes reports all of them at once.

3. 03

   Render pages

   ~2h

   Convert Markdown to HTML with Kramdown, and render pages with ERB layout templates for articles, the index (newest first) and tag pages, escaping titles and tags. Leave out drafts unless --drafts is given. Write each page to its folder. Done when: building a sample folder produces a working website you can open in a browser.

4. 04

   Make builds deterministic

   ~1.5h

   Make sure the same input always produces the same bytes: sort everything that's listed (articles by date then slug, tags alphabetically), never include the build time in pages, use fixed line endings, and write files only when their content changed. Add a check command that builds twice into temporary folders and compares them. Done when: building twice gives identical files, and the check command passes.

5. 05

   Skip unchanged work and clean up

   ~1.5h

   Keep a manifest of each input's content hash and the pages it produced, rebuilding only articles that changed (and the index and tag pages when any article's title, date or tags changed). Remove output files for deleted articles. Write output to a temporary folder and move it into place so a failed build never leaves a half-updated site. Done when: rebuilding after changing one article only rewrites that article and the affected lists.

6. 06

   Test it

   ~2h

   Write RSpec or Minitest tests: front matter parsing and every validation rule, slug generation (accents, punctuation and duplicates), drafts, deterministic output (building twice), incremental builds, and removed articles. Done when: all tests pass.

Resources

• DocsRuby documentation: YAML.safe_load (Psych)
• DocsKramdown documentation
• DocsRuby documentation: ERB
• ArticleReproducible builds: definitions
• DocsBundler: creating a gem