Awesome
remark-github
remark plugin to link references to commits, issues, and users, in the same way that GitHub does in comments, issues, PRs, and releases (see Writing on GitHub).
Contents
- What is this?
- When should I use this?
- Install
- Use
- API
- Examples
- Syntax
- Types
- Compatibility
- Security
- Related
- Contribute
- License
What is this?
This package is a unified (remark) plugin to link references to commits,
issues, and users: @wooorm
-> [**@wooorm**](https://github.com/wooorm)
.
When should I use this?
This project is useful if you want to emulate how markdown would work in GitHub comments, issues, PRs, or releases, but it’s actually displayed somewhere else (on a website, or in other places on GitHub which don’t link references, such as markdown in a repo or Gist). This plugin does not support other platforms such as GitLab or Bitbucket and their custom features.
A different plugin, remark-gfm
, adds support for GFM (GitHub
Flavored Markdown).
GFM is a set of extensions (autolink literals, footnotes, strikethrough, tables,
and tasklists) to markdown that are supported everywhere on GitHub.
Another plugin, remark-breaks
, turns soft line endings
(enters) into hard breaks (<br>
s).
GitHub does this in a few places (comments, issues, PRs, and releases), but it’s
not semantic according to HTML and not compliant to markdown.
Yet another plugin, remark-frontmatter
, adds support
for YAML frontmatter.
GitHub supports frontmatter for files in Gists and repos.
Install
This package is ESM only. In Node.js (version 16+), install with npm:
npm install remark-github
In Deno with esm.sh
:
import remarkGithub, {defaultBuildUrl} from 'https://esm.sh/remark-github@12'
In browsers with esm.sh
:
<script type="module">
import remarkGithub, {defaultBuildUrl} from 'https://esm.sh/remark-github@12?bundle'
</script>
Use
Say we have the following file example.md
:
Some references:
* Commit: f8083175fe890cbf14f41d0a06e7aa35d4989587
* Commit (fork): foo@f8083175fe890cbf14f41d0a06e7aa35d4989587
* Commit (repo): remarkjs/remark@e1aa9f6c02de18b9459b7d269712bcb50183ce89
* Issue or PR (`#`): #1
* Issue or PR (`GH-`): GH-1
* Issue or PR (fork): foo#1
* Issue or PR (project): remarkjs/remark#1
* Mention: @wooorm
Some links:
* Commit: <https://github.com/remarkjs/remark/commit/e1aa9f6c02de18b9459b7d269712bcb50183ce89>
* Commit comment: <https://github.com/remarkjs/remark/commit/ac63bc3abacf14cf08ca5e2d8f1f8e88a7b9015c#commitcomment-16372693>
* Issue or PR: <https://github.com/remarkjs/remark/issues/182>
* Issue or PR comment: <https://github.com/remarkjs/remark-github/issues/3#issue-151160339>
* Mention: <https://github.com/ben-eb>
…and a module example.js
:
import {remark} from 'remark'
import remarkGfm from 'remark-gfm'
import remarkGithub from 'remark-github'
import {read} from 'to-vfile'
const file = await remark()
.use(remarkGfm)
.use(remarkGithub)
.process(await read('example.md'))
console.log(String(file))
…then running node example.js
yields:
Some references:
* Commit: [`f808317`](https://github.com/remarkjs/remark-github/commit/f8083175fe890cbf14f41d0a06e7aa35d4989587)
* Commit (fork): [foo@`f808317`](https://github.com/foo/remark-github/commit/f8083175fe890cbf14f41d0a06e7aa35d4989587)
* Commit (repo): [remarkjs/remark@`e1aa9f6`](https://github.com/remarkjs/remark/commit/e1aa9f6c02de18b9459b7d269712bcb50183ce89)
* Issue or PR (`#`): [#1](https://github.com/remarkjs/remark-github/issues/1)
* Issue or PR (`GH-`): [GH-1](https://github.com/remarkjs/remark-github/issues/1)
* Issue or PR (fork): [foo#1](https://github.com/foo/remark-github/issues/1)
* Issue or PR (project): [remarkjs/remark#1](https://github.com/remarkjs/remark/issues/1)
* Mention: [**@wooorm**](https://github.com/wooorm)
Some links:
* Commit: [remarkjs/remark@`e1aa9f6`](https://github.com/remarkjs/remark/commit/e1aa9f6c02de18b9459b7d269712bcb50183ce89)
* Commit comment: [remarkjs/remark@`ac63bc3` (comment)](https://github.com/remarkjs/remark/commit/ac63bc3abacf14cf08ca5e2d8f1f8e88a7b9015c#commitcomment-16372693)
* Issue or PR: [remarkjs/remark#182](https://github.com/remarkjs/remark/issues/182)
* Issue or PR comment: [#3 (comment)](https://github.com/remarkjs/remark-github/issues/3#issue-151160339)
* Mention: <https://github.com/ben-eb>
API
This package exports the identifier defaultBuildUrl
.
The default export is remarkGithub
.
defaultBuildUrl(values)
Create a URL to GH.
Parameters
values
(BuildUrlValues
) — info on the link to build
Returns
URL to use (string
).
unified().use(remarkGithub[, options])
Link references to users, commits, and issues, in the same way that GitHub does in comments, issues, PRs, and releases.
Parameters
options
(Options
, optional) — configuration
Returns
Transform (Transformer
).
BuildUrl
Create a URL (TypeScript type).
Parameters
values
(BuildUrlValues
) — info on the link to build
Returns
URL to use or false
to not link (string | false
).
BuildUrlCommitValues
Info for commit hash (TypeScript type).
Fields
hash
(string
) — commit hash valueproject
(string
) — project nametype
('commit'
) — kinduser
(string
) — owner of repo
BuildUrlCompareValues
Info for commit hash ranges (TypeScript type).
Fields
base
(string
) — SHA of the range startcompare
(string
) — SHA of the range endproject
(string
) — project nametype
('compare'
) — kinduser
(string
) — owner of repo
BuildUrlIssueValues
Info for issues (TypeScript type).
Fields
no
(string
) — issue numberproject
(string
) — project nametype
('issue'
) — kinduser
(string
) — owner of repo
BuildUrlMentionValues
Info for mentions (TypeScript type).
Fields
type
('mention'
) — kinduser
(string
) — user name
BuildUrlValues
Info (TypeScript type).
Type
type BuildUrlValues =
| BuildUrlCommitValues
| BuildUrlCompareValues
| BuildUrlIssueValues
| BuildUrlMentionValues
Options
Configuration (TypeScript type).
Fields
buildUrl
(BuildUrl
, default:defaultBuildUrl
) — change how things are linkedmentionStrong
(boolean
, default:true
) — wrap mentions instrong
; this makes them render more like how GitHub styles them, but GH itself uses CSS instead ofstrong
repository
(string
, default:repository
frompackag.json
in CWD in Node, otherwise required) — repository to link against; should point to a GitHub repository (such as'user/project'
)
Examples
Example: buildUrl
A buildUrl
can be passed to not link mentions.
For example, by changing example.js
from before like so:
@@ -1,11 +1,15 @@
import {remark} from 'remark'
import remarkGfm from 'remark-gfm'
-import remarkGithub from 'remark-github'
+import remarkGithub, {defaultBuildUrl} from 'remark-github'
import {read} from 'to-vfile'
const file = await remark()
.use(remarkGfm)
- .use(remarkGithub)
+ .use(remarkGithub, {
+ buildUrl(values) {
+ return values.type === 'mention' ? false : defaultBuildUrl(values)
+ }
+ })
.process(await read('example.md'))
console.log(String(file))
To instead point mentions to a different place, change example.js
like so:
@@ -1,11 +1,17 @@
import {remark} from 'remark'
import remarkGfm from 'remark-gfm'
-import remarkGithub from 'remark-github'
+import remarkGithub, {defaultBuildUrl} from 'remark-github'
import {read} from 'to-vfile'
const file = await remark()
.use(remarkGfm)
- .use(remarkGithub)
+ .use(remarkGithub, {
+ buildUrl(values) {
+ return values.type === 'mention'
+ ? `https://yourwebsite.com/${values.user}/`
+ : defaultBuildUrl(values)
+ }
+ })
.process(await read('example.md'))
console.log(String(file))
Syntax
The following references are supported:
- Commits:
1f2a4fb
→1f2a4fb
- Commits across forks:
remarkjs@1f2a4fb
→ remarkjs@1f2a4fb
- Commits across projects:
remarkjs/remark-github@1f2a4fb
→ remarkjs/remark-github@1f2a4fb
- Compare ranges:
e2acebc...2aa9311
→e2acebc...2aa9311
- Compare ranges across forks:
remarkjs@e2acebc...2aa9311
→ remarkjs/remark-github@e2acebc...2aa9311
- Compare ranges across projects:
remarkjs/remark-github@e2acebc...2aa9311
→ remarkjs/remark-github@e2acebc...2aa9311
- Prefix issues:
GH-1
→ GH-1 - Hash issues:
#1
→ #1 - Issues across forks:
remarkjs#1
→ remarkjs#1 - Issues across projects:
remarkjs/remark-github#1
→ remarkjs/remark-github#1 - At-mentions:
@wooorm
→ @wooorm
Autolinks to these references are also transformed:
https://github.com/wooorm
-> [**@wooorm**](https://github.com/wooorm)
Types
This package is fully typed with TypeScript.
It exports the additional types
BuildUrl
,
BuildUrlCommitValues
,
BuildUrlCompareValues
,
BuildUrlIssueValues
,
BuildUrlMentionValues
,
BuildUrlValues
,
DefaultBuildUrl
,
Options
.
Compatibility
Projects maintained by the unified collective are compatible with maintained versions of Node.js.
When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line, remark-github@^12
,
compatible with Node.js 16.
This plugin works with unified
version 6+ and remark
version 7+.
Security
Use of remark-github
does not involve rehype (hast).
It does inject links based on user content, but those links only go to GitHub.
There are no openings for cross-site scripting (XSS) attacks.
Related
remark-gfm
— support GFM (autolink literals, footnotes, strikethrough, tables, tasklists)remark-breaks
— support breaks without needing spaces or escapes (enters to<br>
)remark-frontmatter
— support frontmatter (YAML, TOML, and more)
Contribute
See contributing.md
in remarkjs/.github
for ways
to get started.
See support.md
for ways to get help.
This project has a code of conduct. By interacting with this repository, organization, or community you agree to abide by its terms.