Distill supports a variety of workflows for blog post authoring. For a blog authored by a single individual, the following simple conventions are typically all that's required:
1) Author post R Markdown documents within subdirectories of the
2) Mark posts under development as drafts until they are ready to be published.
For more sophisticated requirements, the following workflows are also supported:
1) Authoring posts within their own standalone Git repositories.
2) Importing posts staged elsewhere on the web (e.g. published to RPubs, located in a Git repository, or published within another Distill blog).
Distill also includes tools for verifying that imported posts are available under an appropriate Creative Commons license and ensuring that posts syndicated from one blog to another give credit within the Google search index to the originating blog. These tools are described below in the [importing posts] section.
There are two distinct ways to manage work in progress on a Distill post:
1) Using the
draft option to prevent the article from being listed in the article index; and
2) Working on the post within a Git branch and merging/publishing it via pull request.
If you want to work on a post for a period of time without having it be added to the listing page, add
draft: true to the post's metadata. For example:
--- title: "The Sharpe Ratio" description: | In this post we present a classic finance use case using the PerformanceAnalytics, quantmod, and dygraphs packages. We'll demonstrate importing stock data, building a portfolio, and then calculating the Sharpe Ratio. draft: true ---
When you are ready to publish the post, either remove the
draft option or set it to
false, then re-Knit the post or build the website using
Once you've done enough work on the post within your branch, you can create a pull request and then ask others for feedback on the post before it is merged.
This workflow has some nice benefits:
1) You can use the commenting and feedback system of your Git host (e.g. GitHub) to discuss the post in a structured fashion with clear linkages back to the source code.
2) You can manage contributions to your blog from others that don't have commit access to the blog (anyone can create a pull request for a public repository).
The mechanics of creating branches and pull requests are beyond the scope of this article. Follow the links above or reference other online resources to learn more.
You may prefer a workflow where posts are worked on separately from your website/blog and then imported when they are ready to be published. This might be the case for a few different reasons:
Below we will cover how to import posts, synchronize to subsequent updates of those posts, as well as address related copyright and search indexing concerns.
You can import a post using the
import_post() function, passing the URL where the post is published to. For example:
You can also import a post from a GitHub repository. For example:
Note that importing a post does not require the original R Markdown document used to author the post---you only need access to the published HTML of a post to import it.
When you import a post, the date for the post will be automatically set to the current day (the idea being that whenever the post was authored, the day you import it is the day it's been published to your blog). You can modify this behavior using the
date parameter. For example:
import_post("https://github.com/jjallaire/distill-article", date = as.Date("2017-07-12"))
The "slug" for a post determines the URL for the post within your blog. By default, slugs are automatically computed using the date and title of the post. For example, the slug for the example just above would have been
You can also override the automatically generated slug entirely using the
slug parameter. For example:
import_post("https://github.com/jjallaire/distill-article", slug = "an-article-about-distill")
If a post that you have imported is subsequently modified and you want to synchronize to the changes, you can use the
update_post() post function. For example:
You can also just use the post slug (rather than including the
_posts directory prefix):
The Distill tools for importing posts make it very easy to aggregate posts published elsewhere on the web into your blog. Note however that you need to ensure that you have appropriate permission to re-publish these posts!
To facilitate this, Distill will scan any imported post for Creative Commons copyright metadata, and in the case that none is found confirm that you still want to import the post. Consequently, you should ask that authors writing posts for your blog always include the
creative_commons field in their post metadata. For example:
--- title: "Distill for R Markdown" description: | Scientific and technical writing, native to the web output: distill::distill_article creative_commons: CC BY ---
Learn more about the
creative_commons field in the documentation on post medatata.
If you know that you have permission to import and republish a post you can suppress this prompt by passing
check_license = FALSE to the
When you specify a
creative_commons license for a blog post you make it easier for others to re-publish your post, giving you a broader audience for your work. In this case you may also want to ensure that the original URL where your post appeared be the one that appears in search engine results.
To facilitate this, Distill automatically specifies a canonical url for posts published within a blog. That way, when a post is imported into another blog, search indexes still point back to the original article.
If you prefer to disable this behavior, you can add
canonical: false to your blog's configuration in
_site.yml. For example:
name: "reproducible-finance-with-r" title: "Reproducible Finance with R" description: | Exploring reproducible finance with the R statistical computing environment. base_url: https://beta.rstudioconnect.com/content/3776/ collections: posts: canonical: false
While canonical URLs are provided automatically for blog posts, they aren't for standalone articles. You can explicitly provide a canonical URL for a standalone article using the
canonical_url metadata field:
--- title: "Distill for R Markdown" description: | Scientific and technical writing, native to the web date: May 4, 2018 author: - name: Nora Jones url: https://example.com/norajones canonical_url: https://rstudio.github.io/distill ---
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.