GitHub Extension For Quarto

github is an extension for Quarto to automatically shortens and converts GitHub references into links.

Installing

quarto add mcanouil/quarto-github

This will install the extension under the _extensions subdirectory. If you're using version control, you will want to check in this directory.

Using

You can reference GitHub issues, pull requests, and commits in your content using GitHub short references. This Quarto extension automatically shortens and converts GitHub references into links.

To activate the filter, add the following to your YAML front matter:

• Old (<1.8.21):

  filters:
    - quarto
    - github

• New (>=1.8.21):

  filters:
    - path: github
      at: post-quarto

Important

The extension must be run after Quarto's processing (i.e., at: post-quarto) to ensure that references (e.g., @fig-my-beautiful-figure) are processed first by Quarto, then by the GitHub filter to avoid conflicts.

Some references require a default repository to be set. Use the extension configuration structure:

extensions:
  github:
    base-url: https://github.com # optional, defaults to https://github.com
    repository-name: jlord/sheetsee.js

Warning

The old top-level repository-name syntax is deprecated but still supported:

repository-name: jlord/sheetsee.js  # deprecated

Configuration

base-url

Specifies the base URL for GitHub or GitHub Enterprise instances. Defaults to https://github.com.

repository-name

Specifies the default GitHub repository in the format owner/repository. This is required for references that don't include the repository name (like #123 or GH-123).

References

Source: Autolinked references and URLs - GitHub Docs.

Mentioning users

User/Organisation	Raw reference	Short link
User mention	@mcanouil	@mcanouil
----------------------	----------------	---------------
Organisation mention	@quarto-dev	@quarto-dev

Issues and pull requests

Reference type	Raw reference	Short link
Issue, discussion, or pull request URL (repository-name is optional!)	https://github.com/jlord/sheetsee.js/issues/26	#26 or lord/sheetsee.js#26
# and issue, discussion, or pull request number (repository-name is required!)	#26	#26
GH- and issue, discussion, or pull request number (repository-name is required!)	GH-26	GH-26
Username/Repository# and issue, discussion, or pull request number	jlord/sheetsee.js#26	jlord/sheetsee.js#26
Organization_name/Repository# and issue, discussion, or pull request number	github-linguist/linguist#4039	github-linguist/linguist#4039

Commit SHAs

Reference type	Raw reference	Short link
Commit URL (repository-name is optional!)	https://github.com/jlord/sheetsee.js/commit/a5c3785ed8d6a35868bc169f07e40e889087fd2e	a5c3785 or jlord/sheetsee.js@a5c3785
SHA (repository-name is required!)	a5c3785ed8d6a35868bc169f07e40e889087fd2e	a5c3785
User@SHA (Not supported! )	jlord@a5c3785ed8d6a35868bc169f07e40e889087fd2e	Not supported!
Username/Repository@SHA	jlord/sheetsee.js@a5c3785ed8d6a35868bc169f07e40e889087fd2e	jlord/sheetsee.js@a5c3785

Example

Here is the source code for a minimal example: example.qmd.