README

remark-gitlab

remark plugin to automatically link references to commits, issues, merge-requests, and users, like in gitlab issues, MRs, and comments.

Install

npm install remark-gitlab

Use

Say we have the following file, example.md:

Some references:

*   Commit: f8083175fe890cbf14f41d0a06e7aa35d4989587
*   Commit (fork): foo@f8083175fe890cbf14f41d0a06e7aa35d4989587
*   Commit (repo): justjavac/remark-gitlab@e1aa9f6c02de18b9459b7d269712bcb50183ce89
*   Issue (`#`): #1
*   Issue (fork): foo#1
*   Issue (project): justjavac/remark-gitlab#1
*   Mention: @justjavac

Some links:

*   Commit: <https://gitlab.com/justjavac/remark-gitlab/commit/e1aa9f6c02de18b9459b7d269712bcb50183ce89>
*   Commit comment: <https://gitlab.com/justjavac/remark-gitlab/commit/ac63bc3abacf14cf08ca5e2d8f1f8e88a7b9015c#commitcomment-16372693>
*   Issue: <https://gitlab.com/justjavac/remark-gitlab/issues/182>
*   Issue: <https://gitlab.com/justjavac/remark-gitlab/issues/3#issue-151160339>
*   Mention: <https://gitlab.com/justjavac>

And our script, example.js, looks as follows:

var vfile = require('to-vfile')
var remark = require('remark')
var gitlab = require('remark-gitlab')

remark()
  .use(gitlab)
  .process(vfile.readSync('example.md'), function (err, file) {
    if (err) throw err
    console.log(String(file))
  })

Now, running node example yields:

Some references:

*   Commit: [`f808317`](https://gitlab.com/justjavac/remark-gitlab/commit/f8083175fe890cbf14f41d0a06e7aa35d4989587)
*   Commit (fork): [foo@`f808317`](https://gitlab.com/justjavac/foo/commit/f8083175fe890cbf14f41d0a06e7aa35d4989587)
*   Commit (repo): [justjavac/remark-gitlab@`e1aa9f6`](https://gitlab.com/justjavac/remark-gitlab/commit/e1aa9f6c02de18b9459b7d269712bcb50183ce89)
*   Issue (`#`): [#1](https://gitlab.com/justjavac/remark-gitlab/issues/1)
*   Issue (fork): [foo#1](https://gitlab.com/justjavac/foo/issues/1)
*   Issue (project): [justjavac/remark-gitlab#1](https://gitlab.com/justjavac/remark-gitlab/issues/1)
*   Mention: [**@justjavac**](https://gitlab.com/justjavac)

Some links:

*   Commit: [justjavac/remark-gitlab@`e1aa9f6`](https://gitlab.com/justjavac/remark-gitlab/commit/e1aa9f6c02de18b9459b7d269712bcb50183ce89)
*   Commit comment: [justjavac/remark-gitlab@`ac63bc3` (comment)](https://gitlab.com/justjavac/remark-gitlab/commit/ac63bc3abacf14cf08ca5e2d8f1f8e88a7b9015c#commitcomment-16372693)
*   Issue: [justjavac/remark-gitlab#182](https://gitlab.com/justjavac/remark-gitlab/issues/182)
*   Issue comment: [#3 (comment)](https://gitlab.com/justjavac/remark-gitlab/issues/3#issue-151160339)
*   Mention: <https://gitlab.com/justjavac>

API

`remark.use(gitlab[, options])`

Automatically link references to commits, issues, merge-requests, and users, like in gitlab issues, PRs, and comments.

Conversion

Commits: f9c6cca3 → f9c6cca3
Commits within same namespace: foo@f9c6cca3 → foo@f9c6cca3
Commits across projects: user/project@f9c6cca3 → user/project@f9c6cca3
Hash issues: #1 → #1
Issues within same namespace: foo#1 → foo#1
Issues across projects: foo/bar#1 → foo/bar#1
At-mentions: @user → [@user**]**

Repository

These links are generated relative to a project. In Node this is detected automatically by loading package.json and looking for a repository field. In the browser, or when overwriting this, you can pass a repository in options. The value of repository should be a URL to a gitlab repository, such as 'https://gitlab.com/user/project.git', or only 'user/project'.

Mentions

By default, mentions are wrapped in strong nodes (that render to <strong> in HTML), to simulate the look of mentions on gitlab. However, this creates different HTML markup, as the gitlab site applies these styles using CSS. Pass mentionStrong: false to turn off this behavior.

License

remark-gitlab is released under the MIT License. See the bundled LICENSE file for details.

Usage no npm install needed!