Autolinked references and URLs

Quarto Extension

References to GitHub issues, pull requests, and commits are automatically shortened and converted into links.

Author

Mickaël CANOUIL, Ph.D.

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

Warning

This extension has been superseded by the Git Link extension. Please update your project to use the new extension.

To install the new extension, see the installation instructions.

Installation

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.

Usage

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 to define the default repository via the extension configuration or have an origin remote set in your Git configuration.

extensions:
  github:
    base-url: https://github.com # optional, defaults to https://github.com
    repository-name: mcanouil/quarto-github

Deprecated

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

repository-name: mcanouil/quarto-github

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/mcanouil/quarto-github/issues/3`	#3
`#` and issue, discussion, or pull request number *`repository-name` is required!*	`#3`	#3
`GH-` and issue, discussion, or pull request number *`repository-name` is required!*	`GH-3`	#3
`Username/Repository#` and issue, discussion, or pull request number	`mcanouil/quarto-github#3`	mcanouil/quarto-github#3
`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	`https://github.com/mcanouil/quarto-github/commit/0b2eb553779f0a7cd56d59c2ec102b8bb643e9c3`	0b2eb55
SHA *`repository-name` is required!*	`0b2eb553779f0a7cd56d59c2ec102b8bb643e9c3`	0b2eb55
`User@SHA` *Not supported!*	`mcanouil@0b2eb553779f0a7cd56d59c2ec102b8bb643e9c3`	*Not supported!*
`Username/Repository@SHA`	`mcanouil/quarto-github@0b2eb553779f0a7cd56d59c2ec102b8bb643e9c3`	mcanouil/quarto-github@0b2eb55