Chapter 7 Authoring original content

This chapter provides general guidance on authoring original content such as blog posts, tutorials, research articles, and project write-ups using R Markdown.

Note: This chapter builds upon the website generated in chapter 4 and edited in chapters 5 and 6. All subsequent chapters will do the same. The final result can be viewed here - https://r4sites-anatole-custom.netlify.app/.

7.1 Prerequisites

Before you proceed, complete the following prerequisites:

  1. (optional) Discover your style
  2. Generate your website
  3. (optional) Fine tune the look and feel
  4. (optional) Configure pages and features

7.2 How it works

More than anything else on your website, your original content is your opportunity to share your ideas and captivate your viewers. For personal websites, original content often takes the form of blog posts, tutorials, research articles, and project portfolios. In all likelihood, your website visitors will spend most of their time reading your original content.

Your original content can be authored using either R Markdown or plain Markdown documents, and the output will reside on your website’s Posts page.

My recommendation is to use R Markdown for authoring original content. R Markdown is very similar to plain Markdown with one massive exception: R Markdown supports the integration and execution of R, Python, and SQL code within the document. This means your content can include dynamic output such as code printing, interactive tables, interactive graphs, and any other form of output that can be generated from these programming languages (example). You can also embed Jupyter Notebooks stored externally (e.g. GitHub Gist). For these reasons, R Markdown is substantially more flexible than plain Markdown for writing technical content. To learn more about R Markdown, I recommend reading R Markdown: The Definitive Guide.

7.3 Example R Markdown posts

If you have never authored an R Markdown document, spend some time looking through these example posts including their source code and associated output on the website. In the source code, inspect the metadata parameters in between the --- markers at the top of the document, then inspect the post body to gain a basic understanding of how text and code chunks are intertwined.

  • Using R in R Markdown - Post includes a table of contents, code highlighting, and thumbnail image. Content covers interactive HTML tables via the DT package, and interactive plots via the plotly package. (</> Code) (Page)

  • Using Python in R Markdown - Post includes a table of contents, code highlighting, and thumbnail image. Content covers the use of Conda environments, inserting and executing Python code chunks, and displaying plots. (</> Code) (Page)

  • Using SQL in R Markdown - Post includes a table of contents and code highlighting. Content covers inserting and executing pure SQL code chunks and using R to execute SQL queries. (</> Code) (Page)

  • Basic Markdown syntax - Post includes a thumbnail image but no table of contents or code highlighting. Content covers basic Markdown syntax. (</> Code) (Page)

  • Embedded Jupyter Notebook - Post includes a rendering of a Jupyter Notebook stored as a GitHub Gist. </> Code (Page)

7.4 Create a new post

The simplest way to add a new post is via the “New post” RStudio Addin. Follow the steps below to create a new post using this approach:

  1. Select the RStudio Addin labeled “New post.” Image

  2. Configure the new post by specifying the post Title, Author, Date, Subdirectory, and Format. Do not specify Tags and Categories at this point. Be sure to place the new post in the post Subdirectory and set the Format to R Markdown (.Rmd). Image

  3. Update (or create) parameters in the post metadata including title, author, summary, date, output, Tags, and Categories (Image). Continue reading to learn more.

7.5 Add a post summary

Add a summary to your R Markdown post to insert a summarization of the post beneath the post title on the Home page (Image). To add a summary, create a summary parameter in the document metadata. </> Code

7.6 Add a table of contents

Add a table of contents to your R Markdown post to improve navigation and enable an overall better user experience. To add a table of contents, edit the output parameter in the document metadata. </> Code

7.7 Add code highlighting

Add code highlighting to improve the readability of your code snippets. To add code highlighting, edit the output parameter in the document metadata. </> Code

Though I recommend the tango highlighting scheme, other code highlighting options options are available.

7.8 Add tags and categories

Add “tags” and “categories” to your posts to organize your content and to give Google crawlers an idea of what your post is about. According to this website, strive to attach no more than 5-10 categories and 5-10 tags to each post. To add tags and categories to your post, edit the Tags and Categories parameters in the document metadata. </> Code

7.9 Add a post thumbnail

A post thumbnail is an image that appears above the post title on the Home page (Image) and at the beginning of the post itself. To include a thumbnail for a post, create a thumbnail parameter in the document metadata and insert the path to your image located in the static/images folder. </> Code

7.10 Embed a Jupyter Notebook in a R Markdown post

Instead of the conventional workflow of authoring posts from scratch within the RStudio IDE, users of Jupyter Notebooks may find it more attractive to develop notebooks externally (e.g. Google Colab) and simply embed them in R Markdown posts.

Follow these steps to embed an external Jupyter Notebook in a post on your website:

  1. Author a Jupyter Notebook using your preferred environment, such as your local machine, Google Colab, etc.
  2. Save a copy of the notebook to your local machine.
  3. Visit https://gist.github.com/ in your browser.
  4. In the upper-right corner, click the “+” icon to add a new gist.
  5. Locate your notebook on your local machine and drag it into the large text box.
  6. Enter a filename including the .ipynb extension.
  7. Change the default option “Create secret gist” to “Create public gist” and select.
  8. Once the Gist is created, locate the “Embed” button and copy the HTML/Javascript code snippet taking the form <script src="https://gist.github.com/<filename>.js"></script>.
  9. Create a new R Markdown post and paste the HTML/Javascript to embed your Jupyter Notebook. (Example)

7.11 Next steps

Proceed with going live on the internet by pushing your website to GitHub and configuring Netlify for continuous deployment.