Article Metadata

Enhance published articles by providing metadata

Table of Contents


You can enhance Radix articles by providing various types of metadata, including:

  1. Links to the article’s source code repository.

  2. Creative Commons licensing terms.

  3. Open Graph and Twitter Card metadata that is automatically included when the article is shared (e.g. on Twitter or within Slack).

  4. Google Scholar compatible citation metadata for your article as well as other works cited by your article.

Code repository

You can include the repository_url field to indicate where the source code for your article can be found. For example:


---
title: "Radix for R Markdown"
description: | 
  Scientific and technical writing, native to the web
output: radix::radix_article
repository_url: https://github.com/radixpub/radix-r
---

You can optionally also include a compare_updates_url to provide a URL that will show the differences between the article’s current version and the version that was initially published. For example:


---
title: "Radix for R Markdown"
description: | 
  Scientific and technical writing, native to the web
output: radix::radix_article
repository_url: https://github.com/radixpub/radix-r
compare_updates_url: https://github.com/radixpub/radix-r/compare/pubv1...master
---

If you include one or both of these fields, then an Updates and Corrections appendix is automatically generated. For example:

Creative Commons

The Creative Commons copyright licenses and tools forge a balance inside the traditional “all rights reserved” setting that copyright law creates. These tools give everyone from individual creators to large companies and institutions a simple, standardized way to grant copyright permissions to their creative work.

Here are some of the common forms of Creative Commons content license:

License Name Description
CC BY Attribution This license lets others distribute, remix, tweak, and build upon your work, even commercially, as long as they credit you for the original creation. This is the most accommodating of licenses offered.
CC BY-SA Attribution-ShareAlike This license lets others remix, tweak, and build upon your work even for commercial purposes, as long as they credit you and license their new creations under the identical terms. This license is often compared to “copyleft” free and open source software licenses. All new works based on yours will carry the same license, so any derivatives will also allow commercial use.
CC BY-ND Attribution-NoDerivs This license allows for redistribution, commercial and non-commercial, as long as it is passed along unchanged and in whole, with credit to you.
CC BY-NC Attribution-NonCommercial This license lets others remix, tweak, and build upon your work non-commercially, and although their new works must also acknowledge you and be non-commercial, they don’t have to license their derivative works on the same terms.

You can designate articles that you create as Creative Commons licensed by adding the creative_commons field and specifying one of the standard Creative Commons licenses. For example:


---
title: "Radix for R Markdown"
description: | 
  Scientific and technical writing, native to the web
output: radix::radix_article
creative_commons: CC BY
---

If you include this field then a Reuse appendix is automatically generated. For example:

External figures

Note that figures from external sources are explicitly carved out of the license. If you are including a figure from an external source, it’s good practice to delineate this by applying the .external class and adding a caption indicating where it is from. For example:


![Figure from https://example.com](heatmap.png){width=100% .external}    

Using the .external class and providing a “Figure from” link makes it clear that the figure originated elsewhere (and is therefore not covered by any of your article’s copyright or creative commons license grants). For example, here’s how a figure taken from a Stack Overflow post might appear:

Figure from https://stackoverflow.com/questions/12196756/
Figure from https://stackoverflow.com/questions/12196756/

Preview images

You can specify a preview image for your article (for sharing on Slack, Twitter, etc.) in a number of different ways:

  1. You can explicitly provide the full URL of the preview image via the preview field in the article’s metadata. For example:

    
    ---
    title: "JavaScript & D3"
    description: Enhance communication with interactive visualizations 
    preview: https://radixpub.github.io/radix-r/images/javascript-d3-preview.png
    ---

    Note that the preview image is specified with a full absolute URL. This is a requirement of both Open Graph and Twitter (relative image references are not supported). If you are publishing a standalone self-contained HTML version of your article then you’ll need to upload the preview image to another location on the web in order to reference it.

  2. If your article is not self-contained (it’s part of a Radix website or is generated with self_contained: false) then you can include the preview image alongside your document. In this case you still need to specify the root URL where your image will be published to using the base_url field:

    
    ---
    title: "JavaScript & D3"
    description: Enhance communication with interactive visualizations 
    base_url: https://radixpub.github.io/radix-r
    preview: images/javascript-d3-preview.png
    ---

    This technique is generally preferable to including the full URL since it allows Radix to inspect the image file directly and provide additional information about it’s size.

  3. You can also specify that a specific figure within your article should be used as the preview image. To do this, just add the preview = TRUE chunk option to the chunk which creates the figure. For example:

    
    ---
    title: "JavaScript & D3"
    description: Enhance communication with interactive visualizations 
    base_url: https://radixpub.github.io/radix-r
    ---
    
    ```{r, layout="l-body-outset", preview=TRUE}
    library(ggplot2)
    ggplot(diamonds, aes(carat, price)) + geom_smooth() +
      facet_grid(~ cut)
    ```

    As with using the preview metadata field, this method requires that your Radix article is not a single standalone HTML file (self_contained: false) and also requires that you specify a base_url field indicating the domain and path where the article will be published.

Open Graph

The Open Graph protocol is a specification that enables richer sharing of links to articles on the web. Open Graph metadata is automatically generated for Radix articles. For example, here’s what you see in Slack when pasting in a link to the article on using JavaScript and D3 within Radix articles:

Slack uses Open Graph to extract and display the title, description, and a preview image (if specified) for the link.

Twitter Card

Twitter Cards are a way of enhancing the appearance of links to your article on Twitter. When a link to your article is included in a Tweet, Twitter automatically crawls your site to fetch any available Twitter Card metadata.

For example, here’s what happens when you include a link to https://radixpub.github.io/radix-r/interactivity.html within a tweet:

See the section on preview images for additional details on providing an image for your article that will be included on Twitter Cards.

There are two additional fields you can include that provide attribution for your link to the Twitter account of a website and/or creator of the article. This attribution is specified via the twitter:site and twitter:creator fields.

Here’s a complete example that includes the attribution fields as well as a preview image:


---
title: "JavaScript & D3"
description: Enhance communication with interactive visualizations 
base_url: https://rstudio.github.io/radix
preview: images/javascript-d3-preview.png
twitter:
  site: "@rstudio"
  creator: "@fly_upside_down"
---

Be sure to enclose the Twitter account names in quotes (this is required because they start with @).

Google Scholar

Radix articles automatically include metadata compatible with the format indexed by Google Scholar. This makes it easy for indexing engines (Google Scholar or otherwise) to extract not only a citation for your article but also information on other sources which you cited.

For example, here is the Google Scholar metadata automatically included for the home page of the Radix website:


<!--  https://scholar.google.com/intl/en/scholar/inclusion.html#indexing -->
<meta name="citation_title" content="Radix for R Markdown"/>
<meta name="citation_fulltext_html_url" content="https://rstudio.github.io/radix"/>
<meta name="citation_fulltext_world_readable" content=""/>
<meta name="citation_online_date" content="2018/05/04"/>
<meta name="citation_publication_date" content="2018/05/04"/>
<meta name="citation_author" content="JJ Allaire"/>
<meta name="citation_author_institution" content="RStudio"/>
<meta name="citation_author" content="Rich Iannone"/>
<meta name="citation_author_institution" content="RStudio"/>
<meta name="citation_author" content="Yihui Xie"/>
<meta name="citation_author_institution" content="RStudio"/>
<meta name="citation_reference" content="citation_title=Distill;
citation_publication_date=2016;citation_publisher=Distill Working
Group;citation_doi=10.23915/distill;citation_author=Shan Carter;
citation_author=Chirs Olah;citation_author=Arvind Satyanarayan"/>
<meta name="citation_reference" content="citation_title=Literate
programming;citation_publication_date=1984;
citation_publisher=British Computer Society;citation_volume=27;
citation_author=Donald E. Knuth"/>
<meta name="citation_reference" content="citation_title=Dynamic
documents with r and knitr;citation_publication_date=2015;
citation_publisher=Chapman; Hall/CRC;citation_author=Yihui Xie"/>

Note that the citation_reference fields provide information on which works your article cited.

The code above is HTML so don’t worry if you aren’t familiar with the syntax. The important thing to know is that citation data is provided in a way that machines can easily read and index.

If you are publishing a Journal article, there are some additional metadata fields you can provide to enhance the Google Scholar metadata generated by Radix. These include additional fields describing the Journal (title, issn, and publisher) as well fields describing the volume and issue in which your article was published. For example:


---
title: "Radix 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
    affiliation: Spacely Sprockets
    affiliation_url: https://example.com/spacelysprokets
journal: 
  title: "Journal of Data Science Software"
  issn: 2490-1752
  publisher: Data Science Press
volume: 10
issue: 4
doi: "10.23915/distill.00010"
slug: jones2018radix
citation_url: https://radixpub.github.io/radix-r
bibliography: biblio.bib
---

Corrections

If you see mistakes or want to suggest changes, please create an issue on the source repository.

Reuse

Text and figures are licensed under Creative Commons Attribution CC BY 4.0. Source code is available at https://github.com/radixpub/radix-r, unless otherwise noted. The figures that have been reused from other sources don't fall under this license and can be recognized by a note in their caption: "Figure from ...".