From manifesto to toolkit!

Intro

The previous post covered the principles that I hope to govern the content that I put up on this site. Now that this ground work has been laid out, the next logical step for me was to gather together some of the basic tools that I will need to rely upon in order to effectively produce said content.

Markdown

Overview

The Jekyll documentation website gives a good overview of what Jekyll is and basically how it works to generate websites from simple text files. Naturally, Jekyll can handle HTML content, however one of the benefits of the Jekyll system is its capacity to handle Markdown-formatted text files. Markdown has a good (i.e. accessible to understand) Wikipedia page, as always, and a decent page at Daring Fireball, which is run by one of Markdown’s creators. This tool basically converts specially formatted text files to HTML (or other formats) using a processing program that recognises selected combinations of basic, easy to use, keyboard characters as its syntax.

Kramdown

Markdown seems to have a number of variants, one of which is kramdown. Jekyll seems to be flexible regarding the markdown processor that can be used, in order to host a Jekyll website on Github, kramdown is the only supported Markdown processor according to their help site. Incidentally, for those who haven’t spotted this, kram is mark in reverse ;).

Given that the Ruby-based kramdown is the way forward with Jekyll (also Ruby-based), it is a good idea to have the kramdown quick reference guide handy for easy reference. The kramdown syntax guide provides a more indepth coverage of the capabilities of this markdown variant. I will be looking at these useful resources to avoid being tripped up unecessarily by syntax misuse, that can intruduce hillarious and frustrating bugs into ones processed HTML source pages.

RMarkdown

RMarkdown is a variant of the Markdown language adapted for use with the R programming language, which has comprehensive network that supports its user base. RMarkdown is maintained by RStudio and their project page gives an overview of the multitude of applications and outputs that it facilitates including the creation of Word, HTML and interactive web apps to name a few from the growing list. For example, RStudio have an amazing gallery of links to examples of interactive web apps powered by their Shiny platform. Closer to home, I made a shiny app called Stats Tutorial as part of a course on developing Data Products that I did on Coursera.

I have used RMarkdown, in conjunction with the RStudio IDE, often to write and compile data analyses to write reports that seamlessly integrate text (markdown), R code excerpts (RMarkdown integration) and analysis outputs (tables, graphs and inline text output). This has allowed me to interactively analyse my data and write up my findings as I go, making refinements to my analysis and documenting my progress. Needless to say, RMarkdown is a great tool for reproducible research, which is a concept that I first came to grips with here.

Getting RMarkdown to work with Jekyll is going to be quite important for me, as many of the topic and project pages that I intend to create. However, there is much more to consider when setting up for RMarkdown integration and I want to do a bit more reading while I contemplate which path to tread.

Python integration

I haven’t used Python in the wild, and haven’t touched it since my Codecademy days of yore. This is another widely used language and, like R, has data science integration via the Pandas package, with iPython for similar interactive data analysis. Python also seems to have support for Markdown via its Notebook, which is helpful for reproducible research. In combination, this seems to be a comparable toolkit to RMarkdown and Rstudio, with added functionality available via projects such as webpy for web document creation.

I have included this section on Python because I want to get into this language in the near future, and this fits well in the overall theme and strategy of this series.

Conclusion

In this part of the series, I have started to overview important content development and management tools that I am (or intend) to use in my future professional development. Consequently, I will be making much use of them in the creation of this site.

In subsequent parts, I will be:

• i) covering more of the tools that I use.
• ii) going into more depth about RMarkdown and, specifically, how I want to integrate it into content development
• iii) expanding upon the principles that I laid out in part 1 as I implement my content management strategy.

Thanks for reading this post, I hope that you are edified by what I have shared and find use for it on your journey.