Skip to main content

Home

Support This Project

Your support helps keep this project alive!

A Quarto extension to add crowdfunding and sponsorship links to your Quarto documents to support your content creation.

Installation

To install the support-this Quarto extension, follow these steps:

  1. Open your terminal.
  2. Execute the following command:
quarto add coatless-quarto/support-this

This command will download and install the Quarto extension under the _extensions subdirectory of your Quarto project. If you are using version control, ensure that you include this directory in your repository.

Usage

In order to use the support-this extension, you need to configure it in your Quarto document’s YAML front matter.

First, add the support-this filter to the filters list.

filters: [support-this]

Next, provide your funding platform usernames or URLs under the support-this’s extensions section. Here is an example configuration:

---
title: "My Post"
format:
  html: default
  typst: default
extensions:
  support-this:
    heading: "Support This Project"  # Optional custom title
    description: "Your support helps keep this project alive!"  # Optional message
    use_funding_yml: false  # Set to true to use GitHub FUNDING.yml if available
    platforms:
      github: username
      patreon: username
      ko_fi: username
      buy_me_a_coffee: username
      custom: "https://paypal.me/username"
filters: [support-this]
---

where username should be replaced with your actual usernames on the respective platforms.

To configure support-this once for a whole website or blog, or for one folder, see Site-wide Setup.

Supported Platforms

The following platforms are supported under the platforms key. They are the platforms GitHub’s FUNDING.yml supports, with the same keys. See All Platforms for how each one looks.

Platform Key Value Example
GitHub Sponsors github username github: coatless
Patreon patreon username patreon: username
Ko-fi ko_fi username ko_fi: username
Buy Me a Coffee buy_me_a_coffee username buy_me_a_coffee: username
Liberapay liberapay username liberapay: username
Open Collective open_collective collective name open_collective: username
Tidelift tidelift platform/package tidelift: npm/babel
IssueHunt issuehunt username issuehunt: username
LFX Mentorship community_bridge project name community_bridge: cloud-foundry
Polar polar username polar: username
thanks.dev thanks_dev u/gh/username thanks_dev: u/gh/username
Custom URLs custom URL custom: "https://paypal.me/username"

Every key takes a single value or a list, such as custom: [url1, url2]. A custom URL without a scheme, such as example.com/donate, links to https://example.com/donate.

Accounts and URLs are read as Markdown, like the rest of the front matter. support-this keeps --, ... and quotes in them as typed (Markdown would turn them into dashes, ellipses and curly quotes), but other Markdown still applies. If an account contains characters such as _ or * around a word, wrap it in backticks inside the quotes, as in custom: "`https://example.com/_draft_`".

Multiple Accounts

You can specify multiple accounts for any platform:

extensions:
  support-this:
    platforms:
      github: [user1, user2, user3]
      custom: 
        - "https://paypal.me/username"
        - "https://venmo.com/username"

Each account will be displayed as a separate link. Links are listed by platform name, with custom links last, and a platform’s accounts keep the order you list them in.

Configuration Options

The support-this extension supports the following configuration options:

  • heading: Custom title for the support section (default: “Support This Project”). Set heading: false to leave it out; formats other than HTML then show the links without the callout box.
  • description: Custom message to display above the links
  • display: How each link is shown (default: icon-platform-username)
    • icon-platform-username: platform icon, platform name, and username
    • icon-username: platform icon and username
    • text: platform name only
    • badge: a shields.io badge (HTML pages only; RevealJS and other formats use the default)
    Typst and Word output show the same icons as HTML. RevealJS shows a symbol for each platform, and PDF output leaves the icons out, since LaTeX’s default fonts can’t display them.
  • position: Where the support section goes when the document has no ::: {.support-this} div (default: bottom)
    • bottom: at the end of the document (in RevealJS, a final slide)
    • top: at the start of the document
    • custom: only where you add a ::: {.support-this} div (with none, the section is left out and a warning is shown)
  • use_funding_yml: If true, attempts to read GitHub’s FUNDING.yml for funding links (default: false)
  • debug: If true, prints what the extension is doing while rendering (default: false)

Custom Placement

To put the support section somewhere specific, add an empty div with the support-this class where it should go:

::: {.support-this}
:::

The section replaces the div whatever position says, so a single page can override a position set for the whole project. In RevealJS, the section stays on the slide that holds the div; at the top or bottom, it gets a slide of its own.

FUNDING.yml Support

If use_funding_yml is set to true, the extension will attempt to read a FUNDING.yml file to populate funding links automatically. It looks for FUNDING.yml or .github/FUNDING.yml next to the document first, then at the root of your Quarto project, then at the root of the git repository.

Platforms listed under platforms take precedence: FUNDING.yml adds the platforms that the document doesn’t set, and a platform set in both places uses the document’s accounts.

See FUNDING.yml Integration for an example.

Troubleshooting

If the support section doesn’t appear:

  • Check that the document lists the filter with filters: [support-this].
  • Check the render output for [support-this] warnings. They point out unknown platform keys (such as kofi instead of ko_fi), unknown display or position values, position: custom without a ::: {.support-this} div, and use_funding_yml: true without a FUNDING.yml to read.
  • Set debug: true to see which platforms and accounts the extension found, and which FUNDING.yml file it read.