remark-github

			Stars	Issues	Version	Updated	Created	Size
	remark-github		164	0	12.0.0	7 months ago	8 years ago

!Build build-badge build !Coverage coverage-badge coverage !Downloads downloads-badge downloads !Size size-badge size !Sponsors sponsors-badge collective !Backers backers-badge collective !Chat chat-badge chat
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 GitHubgithub-writing).

What is this?
When should I use this?
Install
Use
API

*   [`defaultBuildUrl(values)`](#defaultbuildurlvalues)
*   [`unified().use(remarkGithub[, options])`](#unifieduseremarkgithub-options)
*   [`BuildUrl`](#buildurl)
*   [`BuildUrlCommitValues`](#buildurlcommitvalues)
*   [`BuildUrlCompareValues`](#buildurlcomparevalues)
*   [`BuildUrlIssueValues`](#buildurlissuevalues)
*   [`BuildUrlMentionValues`](#buildurlmentionvalues)
*   [`BuildUrlValues`](#buildurlvalues)
*   [`Options`](#options)

Examples

*   [Example: `buildUrl`](#example-buildurl)

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-gfmremark-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-breaksremark-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-frontmatterremark-frontmatter, adds support for YAML frontmatter. GitHub supports frontmatter for files in Gists and repos.

Install

This package is ESM only esm. In Node.js (version 16+), install with npm :

npm install remark-github

In Deno with esm.shesmsh:

import remarkGithub, {defaultBuildUrl} from 'https://esm.sh/remark-github@12'

In browsers with esm.shesmsh:

<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 defaultBuildUrlapi-default-build-url. The default export is remarkGithubapi-remark-github.

`defaultBuildUrl(values)`

Create a URL to GH.

Parameters

values (BuildUrlValuesapi-build-url-values)

— 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 (Optionsapi-options, optional)

— configuration

Returns

Transform (Transformerunified-transformer).

`BuildUrl`

Create a URL (TypeScript type).

Parameters

values (BuildUrlValuesapi-build-url-values)

— 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 value

project (string)

— project name

type ('commit')

— kind

user (string)

— owner of repo

`BuildUrlCompareValues`

Info for commit hash ranges (TypeScript type).

Fields

base (string)

— SHA of the range start

compare (string)

— SHA of the range end

project (string)

— project name

type ('compare')

— kind

user (string)

— owner of repo

`BuildUrlIssueValues`

Info for issues (TypeScript type).

Fields

no (string)

— issue number

project (string)

— project name

type ('issue')

— kind

user (string)

— owner of repo

`BuildUrlMentionValues`

Info for mentions (TypeScript type).

Fields

type ('mention')

— kind

user (string)

— user name

`BuildUrlValues`

Info (TypeScript type).

Type

type BuildUrlValues =
  | BuildUrlCommitValues
  | BuildUrlCompareValues
  | BuildUrlIssueValues
  | BuildUrlMentionValues

`Options`

Configuration (TypeScript type).

Fields

buildUrl (BuildUrlapi-build-url, default:

[`defaultBuildUrl`][api-default-build-url])
— change how things are linked

mentionStrong (boolean, default: true)

— wrap mentions in `strong`;
this makes them render more like how GitHub styles them, but GH itself
uses CSS instead of `strong`

repository (string, default: repository from packag.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`][github-sha]

Commits across forks:

`remarkjs@1f2a4fb` →
[remarkjs@`1f2a4fb`][github-sha]

Commits across projects:

`remarkjs/remark-github@1f2a4fb` →
[remarkjs/remark-github@`1f2a4fb`][github-sha]

Compare ranges:

`e2acebc...2aa9311` →
[`e2acebc...2aa9311`][github-sha-range]

Compare ranges across forks:

`remarkjs@e2acebc...2aa9311` →
[remarkjs/remark-github@`e2acebc...2aa9311`][github-sha-range]

Compare ranges across projects:

`remarkjs/remark-github@e2acebc...2aa9311` →
[remarkjs/remark-github@`e2acebc...2aa9311`][github-sha-range]

Prefix issues:

`GH-1` →
[GH-1][github-issue]

Hash issues:

`#1` →
[#1][github-issue]

Issues across forks:

`remarkjs#1` →
[remarkjs#1][github-issue]

Issues across projects:

`remarkjs/remark-github#1` →
[remarkjs/remark-github#1][github-issue]

At-mentions:

`@wooorm` →
[**@wooorm**][github-mention]

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 BuildUrlapi-build-url, BuildUrlCommitValuesapi-build-url-commit-values, BuildUrlCompareValuesapi-build-url-compare-values, BuildUrlIssueValuesapi-build-url-issue-values, BuildUrlMentionValuesapi-build-url-mention-values, BuildUrlValuesapi-build-url-values, DefaultBuildUrlapi-default-build-url, Optionsapi-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)wiki-xss attacks.

remark-gfmremark-gfm

— support GFM (autolink literals, footnotes, strikethrough, tables,
tasklists)

remark-breaksremark-breaks

— support breaks without needing spaces or escapes (enters to `<br>`)

remark-frontmatterremark-frontmatter

— support frontmatter (YAML, TOML, and more)

Contribute

See contributing.mdcontributing in remarkjs/.githubhealth for ways to get started. See support.mdsupport for ways to get help.
This project has a code of conduct coc. By interacting with this repository, organization, or community you agree to abide by its terms.

remark-github

Downloads in past1 Month3 Months6 Months1 Year2 Years5 YearsAll time

Stats

Popular Searches

Readme

Contents

What is this?

When should I use this?

Install

Use

API

defaultBuildUrl(values)

Parameters

Returns

unified().use(remarkGithub[, options])

Parameters

Returns

BuildUrl

Parameters

Returns

BuildUrlCommitValues

Fields

BuildUrlCompareValues

Fields

BuildUrlIssueValues

Fields

BuildUrlMentionValues

Fields

BuildUrlValues

Type

Options

Fields

Examples

Example: buildUrl

Syntax

Types

Compatibility

Security

Related

Contribute

License

Sick of boring JavaScript newsletters?

Downloads in past

`defaultBuildUrl(values)`

`unified().use(remarkGithub[, options])`

`BuildUrl`

`BuildUrlCommitValues`

`BuildUrlCompareValues`

`BuildUrlIssueValues`

`BuildUrlMentionValues`

`BuildUrlValues`

`Options`

Example: `buildUrl`