Adding COinS Metadata for Zotero

Peter Baumgartner

2026-09-03

add_coins() appends 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? further down.

Using add_coins()

Prerequisites

Basic Usage

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 <span> 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:

This code: - Uses an R chunk with echo: false and results: asis so it’s invisible to readers - Outputs the COinS <span> 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:

# 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:

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:

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
  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 <span> (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 <span> 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:

The Solution

COinS eliminates guessing. When you add a COinS span to your post, reference manager and many other bibliography software and services can:

  1. Automatically detect the post’s metadata — no manual entry needed
  2. Save the post to your personal library — with correct author, date, title, and keywords
  3. Use correct citation formatting — because software or service knows the post is a blog article, not a book or journal article
  4. Reference it in your writing — The software generates correct citations in your preferred style (Chicago, APA, etc.)

This is especially valuable for academic writers who rely on reference managers for literature management.

The Standard Behind COinS

COinS is based on the OpenURL standard (ANSI/NISO Z39.88-2004), which was originally designed to help libraries link users to full-text content. The “ContextObject” is the standardized metadata package at the heart of OpenURL.

The clever part of COinS is that it embeds an OpenURL ContextObject invisibly in HTML using a <span> element:

<span class="Z3988" title="ctx_ver=Z39.88-2004&rft.title=...&rft.au=..."></span>

The class="Z3988" tells processors like Zotero that this span contains COinS metadata. The actual data is in the title attribute (which is counterintuitive—it’s not displayed as a tooltip; it’s just a container for the encoded metadata).

Why a span?

Using a <span> allows COinS metadata to be placed anywhere in a web page without breaking the HTML structure or being visible to human readers. Other approaches (like storing metadata in <meta> tags in the page’s <head>) are more restrictive—you can only have one set of metadata per page. With COinS, you can embed metadata for multiple items on the same page.

Websites Using COinS

COinS has been adopted by many major platforms and content providers:

How Zotero Uses COinS

When you’re browsing a blog post with COinS in your Zotero-enabled browser:

  1. Zotero’s browser extension scans the page and finds the <span class="Z3988"> element
  2. It decodes the embedded metadata
  3. It displays a save icon (📖) in your browser address bar, indicating that Zotero can capture the page
  4. You click the icon to save the post to your library
  5. Zotero populates the entry with all the metadata from COinS: title, author, date, description, etc.

Without COinS, Zotero might not recognize the page as a citable item, and you’d have to manually enter all the metadata.

Integration with Academic Workflow

COinS is particularly valuable if you:

Further Reading

See Also