README.md

remark-gitlab-artifact

A remark plugin that downloads artifacts from Gitlab projects to live alongside your Markdown.

Installation

$ npm install remark-gitlab-artifact

Usage

Authors can link to artifacts generated by Gitlab CI. remark-gitlab-artifact will download the artifacts from the master branch build of a specified job for a specified project alongside the Markdown document.

To do this, authors need to know the Gitlab Project ID (either ID, or URL-encoded name) and Job Name. Authors must specify an entrypoint into the artifact, this is where the user will navigate to when the Markdown is published.

The following will download the artifacts from the docs job for Gitlab project 851. When the user clicks on the API Reference link, they will be taken to docs/index.html.

[API Reference](docs/index.html "gitlab-artifact|851|docs")

API

This plugin has two configuration values, which must be provided:

• apiBase The URL to your Gitlab instance.
• gitlabApiToken A personal access token for Gitlab, to authorise the API calls.

Messages

Messages are added to the vFile's as they are processed and can be accessed using file.messages.

info

Added when artifacts were able to be retrieved successfully:

example.md:1:1-1:60: artifacts fetched from 851 docs

error

Added when something went wrong fetching the artifact:

example.md:1:1-1:62: Not Found from https://gitlab.com/api/v4/projects/fafds/jobs/artifacts/master/download?job=docs.

Example

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

var example = vfile.readSync('example.md');

remark()
  .use(gitlab, {
    apiBase: 'https://gitlab.com',
    gitlabApiToken: 'abc-123'
  })
  .process(example, function (err, file) {
    if (err) throw err;

    console.log(String(file));
  });

The artifacts will be unzipped relative to example.md. To change this, set data.destinationFilePath on the vFile. The following will download the artifacts into the /out directory, and then save example.md to the same directory:

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

var example = vfile.readSync('example.md');
example.data = {
  destinationFilePath: 'out/example.md'
};

remark()
  .use(gitlab, {
    apiBase: 'https://gitlab.com',
    gitlabApiToken: 'abc-123'
  })
  .process(example, function (err, file) {
    if (err) throw err;

    vfile.writeSync({ path: file.data.destinationFilePath });
  });