-
-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathexample.qmd
More file actions
145 lines (119 loc) · 11.5 KB
/
example.qmd
File metadata and controls
145 lines (119 loc) · 11.5 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
---
title: "Autolinked references and URLs"
subtitle: "Quarto Extension"
author:
- name: "Mickaël CANOUIL, _Ph.D._"
orcid: "0000-0002-3396-4549"
url: "https://mickael.canouil.fr"
format:
html:
output-file: index
toc: true
description: |
References to GitHub issues, pull requests, and commits are automatically shortened and converted into links.
page-layout: full
filters:
- path: github
at: post-quarto
---
`github` is an extension for [Quarto](https://quarto.org) to automatically shortens and converts [GitHub references](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/autolinked-references-and-urls) into links.
:::: {.callout-warning}
This extension has been superseded by the [Git Link extension](https://github.com/mcanouil/quarto-gitlink).
Please update your project to use the new extension.
To install the new extension, see the [installation instructions](https://github.com/mcanouil/quarto-gitlink?tab=readme-ov-file#installation).
:::
## Installation
```bash
quarto add mcanouil/quarto-github@1.4.0
```
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):
```yml
filters:
- quarto
- github
```
- New (>=1.8.21):
```yml
filters:
- path: github
at: post-quarto
```
:::: {.callout-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.
```yml
extensions:
github:
base-url: https://github.com # optional, defaults to https://github.com
repository-name: mcanouil/quarto-github@1.4.0
```
:::: {.callout-warning}
## Deprecated
The old top-level `repository-name` syntax is deprecated but still supported:
```yml
repository-name: mcanouil/quarto-github@1.4.0
```
:::
## Mentioning users
+----------------------+----------------+-------------+
| User/Organisation | Raw reference | Short link |
+======================+================+=============+
| | ```txt | |
| User mention | @mcanouil | @mcanouil |
| | ``` | |
+----------------------+----------------+-------------+
| | ```txt | |
| Organisation mention | @quarto-dev | @quarto-dev |
| | ``` | |
+----------------------+----------------+-------------+
## Issues and pull requests
+-------------------------------------------------------------------------------+----------------------------------------------------+----------------------------------------------------+
| Reference type | Raw reference | Short link |
+===============================================================================+====================================================+====================================================+
| | ```txt | |
| Issue, discussion, or pull request URL | https://github.com/mcanouil/quarto-github@1.4.0/issues/3 | https://github.com/mcanouil/quarto-github@1.4.0/issues/3 |
| ***`repository-name` is optional!*** | ``` | |
+-------------------------------------------------------------------------------+----------------------------------------------------+----------------------------------------------------+
| | ```txt | |
| `#` and issue, discussion, or pull request number \ | #3 | #3 |
| ***`repository-name` is required!*** | ``` | |
+-------------------------------------------------------------------------------+----------------------------------------------------+----------------------------------------------------+
| | ```txt | |
| `GH-` and issue, discussion, or pull request number \ | GH-3 | GH-3 |
| ***`repository-name` is required!*** | ``` | |
+-------------------------------------------------------------------------------+----------------------------------------------------+----------------------------------------------------+
| | ```txt | |
| `Username/Repository#` and issue, discussion, or pull request number | mcanouil/quarto-github@1.4.0#3 | mcanouil/quarto-github@1.4.0#3 |
| | ``` | |
+-------------------------------------------------------------------------------+----------------------------------------------------+----------------------------------------------------+
| | ```txt | |
| `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 |
+======================================+===========================================================================================+===========================================================================================+
| | ```txt | |
| Commit URL | https://github.com/mcanouil/quarto-github@1.4.0/commit/0b2eb553779f0a7cd56d59c2ec102b8bb643e9c3 | https://github.com/mcanouil/quarto-github@1.4.0/commit/0b2eb553779f0a7cd56d59c2ec102b8bb643e9c3 |
| | ``` | |
+--------------------------------------+-------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------+
| | ```txt | |
| SHA \ | 0b2eb553779f0a7cd56d59c2ec102b8bb643e9c3 | 0b2eb553779f0a7cd56d59c2ec102b8bb643e9c3 |
| ***`repository-name` is required!*** | ``` | |
+--------------------------------------+-------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------+
| | ```txt | |
| `User@SHA` \ | mcanouil@0b2eb553779f0a7cd56d59c2ec102b8bb643e9c3 | ***Not supported!*** |
| ***Not supported!*** | ``` | |
+--------------------------------------+-------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------+
| | ```txt | |
| `Username/Repository@SHA` | mcanouil/quarto-github@0b2eb553779f0a7cd56d59c2ec102b8bb643e9c3 | mcanouil/quarto-github@0b2eb553779f0a7cd56d59c2ec102b8bb643e9c3 |
| | ``` | |
+--------------------------------------+-------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------------+