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/.
Before you proceed, complete the following prerequisites:
- (optional) Discover your style
- Generate your website
- (optional) Fine tune the look and feel
- (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:
Select the RStudio Addin labeled “New post.” Image
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
postSubdirectory and set the Format to
R Markdown (.Rmd). Image
Update (or create) parameters in the post metadata including
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.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:
- Author a Jupyter Notebook using your preferred environment, such as your local machine, Google Colab, etc.
- Save a copy of the notebook to your local machine.
- Visit https://gist.github.com/ in your browser.
- In the upper-right corner, click the “+” icon to add a new gist.
- Locate your notebook on your local machine and drag it into the large text box.
- Enter a filename including the
- Change the default option “Create secret gist” to “Create public gist” and select.
7.11 Next steps
Proceed with going live on the internet by pushing your website to GitHub and configuring Netlify for continuous deployment.