Git Hosting Platform for Quarto

Quarto Extension

Author

A Quarto extension that automatically converts Git hosting platform references (issues, pull requests, commits, users) into clickable links. Supports GitHub, GitLab, Codeberg, Gitea, and Bitbucket.

Installation

quarto add mcanouil/quarto-gitlink

This will install the extension under the _extensions subdirectory.

If you’re using version control, you will want to check in this directory.

Usage

Add the extension to your document’s YAML front matter:

---
title: "My Document"
filters:
  - path: gitlink
    at: post-quarto
extensions:
  gitlink:
    platform: github               # Platform: github, gitlab, codeberg, gitea, bitbucket
    base-url: https://github.com   # Base URL (optional, auto-detected from platform)
    repository-name: owner/repo    # Repository name for relative references
---

Tip

For best results, wrap URLs in angle brackets (<URL>) rather than using bare URLs. For example, use <https://github.com/owner/repo/issues/123> instead of https://github.com/owner/repo/issues/123.

Examples

Configure for GitHub (default):

extensions:
  gitlink:
    platform: github
    base-url: https://github.com
    repository-name: mcanouil/quarto-gitlink

Reference issues and pull requests:

Simple issue reference: #1GitHub
Cross-repository issue: mcanouil/quarto-gitlink#1GitHub
Commit reference: cb0350dGitHub
Cross-repository commit: mcanouil/quarto-gitlink@cb0350dGitHub
User mention: @mcanouilGitHub
GitHub-style issue: #1GitHub

Full URL examples (automatically shortened):

Issue URL: #1GitHub
Pull request URL: #10GitHub
Commit URL: cb0350dGitHub
Cross-repository issue URL: quarto-dev/quarto-cli#10000GitHub
User/organisation URL: @mcanouilGitHub

Configure for GitLab by changing the platform:

extensions:
  gitlink:
    platform: gitlab
    base-url: https://gitlab.com
    repository-name: group/project

Then you can use:

Issue reference: #123
Merge request: !456
Cross-repository issue: group/project#123
Cross-repository merge request: group/project!456
Commit reference: a5c3785dc2e23c1d8e7e4d9a8b91c6f234567890
Cross-repository commit: group/project@a5c3785dc2e23c1d8e7e4d9a8b91c6f234567890
User mention: @username

Full URL examples (automatically shortened):

Issue URL: group/project#123GitLab
Merge request URL: group/project!456GitLab
Commit URL: group/project@a5c3785GitLab
Cross-repository issue URL: other-group/other-project#789GitLab
User/organisation URL: @usernameGitLab

Configure for Codeberg by changing the platform:

extensions:
  gitlink:
    platform: codeberg
    base-url: https://codeberg.org
    repository-name: owner/repo

Then you can use:

Issue reference: #123
Pull request reference: #456 (same as issue in Codeberg/Forgejo)
Cross-repository issue: owner/repo#123
Commit reference: a5c3785dc2e23c1d8e7e4d9a8b91c6f234567890
Cross-repository commit: owner/repo@a5c3785dc2e23c1d8e7e4d9a8b91c6f234567890
User mention: @username

Full URL examples (automatically shortened):

Issue URL: owner/repo#123Codeberg
Pull request URL: owner/repo#456Codeberg
Commit URL: owner/repo@a5c3785Codeberg
Cross-repository issue URL: other-owner/other-repo#789Codeberg
User/organisation URL: @usernameCodeberg

Configure for Gitea:

extensions:
  gitlink:
    platform: gitea
    base-url: https://gitea.com
    repository-name: owner/repo

Reference Gitea Documentation for more details.

Then you can use:

Issue reference: #123
Pull request reference: #456 (same as issue)
Cross-repository issue: owner/repo#123
Cross-repository pull request: owner/repo#456
Commit reference: a5c3785dc2e23c1d8e7e4d9a8b91c6f234567890
Cross-repository commit: owner/repo@a5c3785dc2e23c1d8e7e4d9a8b91c6f234567890
User mention: @username

Full URL examples (automatically shortened):

Issue URL: owner/repo#123Gitea
Pull request URL: owner/repo#456Gitea
Commit URL: owner/repo@a5c3785Gitea
Cross-repository issue URL: other-owner/other-repo#789Gitea
User/organisation URL: @usernameGitea

Configure for Bitbucket by changing the platform:

extensions:
  gitlink:
    platform: bitbucket
    base-url: https://bitbucket.org
    repository-name: workspace/repo

Bitbucket follows the official markup syntax and requires “issue” or “pull request” keywords before the reference:

Issue reference: issue #123
Pull request reference: pull request #456
Cross-repository issue: issue workspace/repo#123
Cross-repository pull request: pull request workspace/repo#456
Commit reference: a5c3785dc2e23c1d8e7e4d9a8b91c6f234567890
Cross-repository commit: workspace/repo@a5c3785dc2e23c1d8e7e4d9a8b91c6f234567890
User mention: @username

Full URL examples (automatically shortened):

Issue URL: workspace/repo#123Bitbucket
Pull request URL: workspace/repo#456Bitbucket
Commit URL: workspace/repo@a5c3785Bitbucket
Cross-repository issue URL: other-workspace/other-repo#789Bitbucket
User/organisation URL: @usernameBitbucket

Note

Unlike GitHub or GitLab, Bitbucket requires the issue or pull request prefix to distinguish between different reference types.

Platform-Specific Features

Supports GH-123 format for issues
Pull requests use same format as issues (#123)
Reference: GitHub Autolinked references

Merge requests use !123 format
Issues use #123 format
URLs include /-/ in path
Reference: GitLab Flavored Markdown

Pull requests and issues both use #123 format
Based on Forgejo/Gitea architecture
Reference: Codeberg Documentation

Issues use #123 format
Pull requests use #123 format (same as issues)
Supports both internal and external issue trackers
Reference: Gitea Documentation

Issues use issue #123 format (requires “issue” prefix)
Pull requests use pull request #456 format (requires “pull request” prefix)
Cross-repository references: issue workspace/repo#123 or pull request workspace/repo#456
Pull request URLs use /pull-requests/ path
Follows Bitbucket’s official markup syntax

Configuration Options

Platform Detection

The extension automatically detects the platform based on the platform setting:

github - GitHub (default)
gitlab - GitLab
codeberg - Codeberg
gitea - Gitea
bitbucket - Bitbucket

Base URL

The base-url setting allows you to use self-hosted instances:

extensions:
  gitlink:
    platform: gitlab
    base-url: https://gitlab.example.com
    repository-name: group/project

Repository Name

The repository-name setting is used for relative references. If not provided, the extension will attempt to detect it from the Git remote:

git remote get-url origin

Platform Badges

In HTML output, Gitlink displays subtle platform badges next to links for improved accessibility and quick visual identification.

Features:

Always visible badges showing the full platform name (GitHub, GitLab, etc.).
Tooltips on both links and badges.
Accessible to screen readers with proper ARIA labels.
Theme-aware styling using Bootstrap classes.

Configuration:

extensions:
  gitlink:
    show-platform-badge: true      # Show/hide badges (default: true)
    badge-position: "after"        # "after" or "before" link (default: "after")

Options:

show-platform-badge (boolean): Toggle badge visibility, default true.
badge-position (string): Badge placement relative to link, default "after".

To disable badges and use only tooltips:

extensions:
  gitlink:
    show-platform-badge: false

Custom Platforms

You can add support for additional platforms or customise existing ones by providing a custom platforms configuration file.

Creating a Custom Platforms File:

Create a YAML file (e.g., custom-platforms.yml) with your platform definitions:

platforms:
  gitplatform:
    base-url: https://git.example.com
    patterns:
      issue:
        - '#(%d+)'
        - '([^/]+/[^/#]+)#(%d+)'
      merge-request:
        - '#(%d+)'
        - '([^/]+/[^/#]+)#(%d+)'
      commit:
        - '^(%x+)$'
        - '([^/]+/[^/@]+)@(%x+)'
        - '(%w+)@(%x+)'
      user: '@([%w%-%.]+)'
    url-formats:
      issue: '/{repo}/issues/{number}'
      merge-request: '/{repo}/pull/{number}'
      pull: '/{repo}/pulls/{number}'
      commit: '/{repo}/commit/{sha}'
      user: '/{username}'

Using Custom Platforms:

Reference your custom platforms file in the document metadata:

extensions:
  gitlink:
    platform: gitplatform
    custom-platforms-file: custom-platforms.yml
    repository-name: owner/repo

The extension will load both built-in and custom platform definitions, allowing you to use any platform you define.

Customising Badge Appearance

You can customise the appearance of platform badges in HTML and Typst output:

extensions:
  gitlink:
    show-platform-badge: true           # Show/hide badges (default: true)
    badge-position: "after"             # Position: "after" or "before" (default: "after")
    badge-background-colour: "#e8f4f8"  # Badge background colour (default: "#c3c3c3")
    badge-text-colour: "#003366"        # Badge text colour (optional)

Colour Options:

badge-background-colour: Set the background colour using hex codes (e.g. #e8f4f8) or colour names.
badge-text-colour: Set the text colour (optional). If not specified, the default text colour is used.

Example with Custom Colours:

Here is an example with a light blue background and dark blue text:

extensions:
  gitlink:
    badge-background-colour: "#e8f4f8"
    badge-text-colour: "#003366"

These colours will be applied to badges in both HTML and Typst output formats.

Contributing New Platforms:

To contribute a new platform to the built-in configuration:

Fork the repository.
Edit _extensions/gitlink/platforms.yml to add your platform definition.
Test your configuration with a custom platforms file first.
Submit a pull request with your changes.