Frag's Writings :: Meta

Meta

Writing a blog post manually in HTML is too much pain. Setting up a "blogging platform" involves lots of black boxes and weird commands incantations in addition to much pain. Writing posts Markdown and then transforming into HTML seems to be the way to go. This is a meta-post (more like notes, really) regarding the workflow I intend to follow for future blog posts, if there are any.

Tools

Currently, Frag-Blags^TM are to be written in Markdown with the following tools:

0. neovim, my preferred text-editor, for converting thoughts into markdown (essentially, text) efficiently.
1. pandoc, the swiss-army knife for document conversion, transforms markdown into HTML that can be published to GH pages
2. GNU make, the venerable generator/builder, for wrapping pandoc invocations and cleaning up afterward
3. tidy, a tool for validating HTML5 locally

Workflow

0. Run install.sh to make sure the necessary tools are installed
1. Edit post.md and create content in markdown
2. Run make when done, this will generate the HTML file from markdown and make view to open the file in default browser via xdg-open
3. img tags need special attention, esp. aligning images :-/
4. Run make deploy and supply title for new post. This will copy the generated HTML file to the correct location and rebuild the post listing
5. Revert post.md, commit other changes and push

The push should have atleast two files the_new_post.html and posts.html (with changes for listing the new post)

Validation

Errors generally creep in different categories:

• Spelling: This is the easy part, neovim has a spell-checker built in and markdown is quite easy to spellcheck
• Syntax: tidy integrates quite well with neovim, see this page for details
• Links: A simple convention like using relative links for local (within the blog) resources and fully-qualified links for external resources can help mitigate this problem

Ugly Bits and Improvements

There are a few steps requiring manual editing and mucking with HTML, such as:

• Image handling needs to be improved
• Done 2017-02-19 via make deploy editing posts.html, perhaps the entire file can be generated from markdown as well
• Done 2017-02-19 via make deploy add script or make targets for automate post creation and copying to correct dir for publishing

Meta-ception

This is really a meta-post, intended as a test for ensuring that the md-to-html step produces satisfactory output with features such as inline monospace text, links and the like.