--- title: "Adding COinS Metadata for Zotero" description: "Understand COinS metadata and how add_coins() helps reference managers like Zotero automatically import your blog posts." author: "Peter Baumgartner" date: "`r Sys.Date()`" output: rmarkdown::html_vignette: toc: true toc_depth: 2 vignette: > %\VignetteIndexEntry{Adding COinS Metadata for Zotero} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} --- ```{r, include = FALSE} knitr::opts_chunk$set( collapse = TRUE, comment = "#>" ) ``` `add_coins()` appends [COinS](https://en.wikipedia.org/wiki/COinS) metadata to a finished Quarto blog post so reference managers like Zotero can automatically detect it and import the title, author, date, and other citation details into your library. This article covers everyday usage first. If you want to understand what COinS actually is and why it works the way it does, see [Background: What is COinS?](#background-what-is-coins) further down. ## Using `add_coins()` ### Prerequisites - A completed Quarto blog post in `posts/your-post/index.qmd` - A `_quarto.yml` file in your blog's root directory with at least `site-url:` specified ### Basic Usage ```r library(qpost) # Add COinS to the currently open post in RStudio add_coins() # Or specify a file path explicitly add_coins(file_path = "posts/my-post/index.qmd") ``` ### What Happens When you call `add_coins()`, it: 1. **Reads your post's YAML** — extracts title, author, date, categories, description 2. **Queries `_quarto.yml`** — reads site URL and language settings 3. **Applies auto-resolution** — fills gaps from `_quarto.yml` and `.Rprofile` options 4. **Generates COinS metadata** — creates key-value pairs (title, author, date, language, license, etc.) 5. **Appends a hidden R code chunk** to render the COinS `` at the end of your post 6. **Opens the edited file** — so you can review and commit ### What Gets Generated At the bottom of your `index.qmd`, `add_coins()` appends: ```{r} #| label: coins #| echo: false #| results: asis cat('') ``` This code: - Uses an R chunk with `echo: false` and `results: asis` so it's invisible to readers - Outputs the COinS `` as raw HTML - Is placed **at the end** of your post, so Zotero sees the complete content first ## Configuration By default, `add_coins()` reads everything it needs from your post YAML and `_quarto.yml`. You only need to configure `.Rprofile` for optional fallback values: ```r # Project-level .Rprofile (in your blog's root directory) options( qpost.lang = "en", # Fallback language if not in post or _quarto.yml qpost.license = "CC-BY-4.0" # License code for all posts ) ``` ### Auto-resolution Priority For each field, `add_coins()` looks in this order: 1. **Post YAML** (e.g., `lang:`, `license:` in your post's front matter) 2. **`_quarto.yml`** (e.g., `lang:` in your blog config) 3. **`.Rprofile` options** (e.g., `getOption("qpost.lang")`, `getOption("qpost.license")`) 4. **Omitted** if not found anywhere This design means: - Most of the time, you don't need `.Rprofile` setup — your post YAML and `_quarto.yml` suffice - Set `qpost.license` once in `.Rprofile` to apply it to all posts automatically - Post-level values always override defaults --- ## Editing COinS After Creation The COinS span is just an R code chunk at the end of your post. You can: 1. **Edit it manually** — change metadata values directly in the `title` attribute 2. **Regenerate it** — delete the chunk and run `add_coins()` again 3. **Remove it** — delete the chunk entirely (though this defeats the purpose!) To re-run `add_coins()` on an existing post: 1. Delete the `coins` code chunk at the bottom 2. Run `add_coins(file_path = "posts/your-post/index.qmd")` 3. Review and commit the changes --- ## Backup Mode By default, `add_coins(backup = TRUE)` creates a backup of your post before modifying it: ```r add_coins(file_path = "posts/my-post/index.qmd", backup = TRUE) ``` This creates a file like `posts/my-post/index.qmd.bak` as a safety measure. If something goes wrong, you can restore the original. To disable backups: ```r add_coins(file_path = "posts/my-post/index.qmd", backup = FALSE) ``` --- ## Testing Your COinS Once you've added COinS to a post, you can test it: 1. **Render your blog** with `quarto preview` or `quarto render` 2. **Open the post in your browser** 3. **Install Zotero** browser extension (if you haven't already) from [zotero.org](https://www.zotero.org/download/) 4. **Click the Zotero save icon** in your browser address bar 5. **Verify the metadata** — Zotero should pre-fill the title, author, date, and other fields automatically If the save icon doesn't appear, check that: - The HTML output contains the COinS `` (view page source in your browser) - The metadata in the `title` attribute is properly URL-encoded - Your Zotero browser extension is enabled --- ## Background: What is COinS? **COinS** stands for **ContextObjects in Spans**. It's a simple, standardized way to embed bibliographic metadata directly into HTML pages so that specialized software can read and extract it. Think of it like this: when you visit a website, humans see the text and can understand what a blog post is about. But reference managers like Zotero need machine-readable metadata to know the title, author, publication date, and other citation details without requiring manual data entry. COinS solves this by embedding bibliographic information in an invisible HTML `` element on your page. When Zotero visits your blog post, it detects the COinS metadata and can automatically add the post to your library with all the correct fields filled in. --- ## Why Use COinS? With COinS, you provide metadata from your blog posts to software tools like bibliography managers, enabling automatic retrieval and making it easier to cite your articles correctly. ### The Problem Without COinS, reference manager have to guess your post's metadata by examining the HTML structure. This often fails for blog posts because: - Blog post titles might be in an `

` tag, but so might many other things - The publication date might be hidden in an obscure `