Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/temando/remark-gitlab-artifact
A remark plugin that downloads artifacts from Gitlab projects to live alongside your Markdown.
https://github.com/temando/remark-gitlab-artifact
gitlab gitlab-ci remark remark-plugin
Last synced: about 2 months ago
JSON representation
A remark plugin that downloads artifacts from Gitlab projects to live alongside your Markdown.
- Host: GitHub
- URL: https://github.com/temando/remark-gitlab-artifact
- Owner: temando
- License: mit
- Created: 2017-08-14T08:02:28.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2017-08-15T08:02:00.000Z (over 7 years ago)
- Last Synced: 2024-10-31T16:51:08.093Z (about 2 months ago)
- Topics: gitlab, gitlab-ci, remark, remark-plugin
- Language: JavaScript
- Homepage:
- Size: 48.8 KB
- Stars: 2
- Watchers: 5
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# remark-gitlab-artifact
[](https://npmjs.org/packages/remark-gitlab-artifact/)
[](https://travis-ci.org/temando/remark-gitlab-artifact)
[](https://en.wikipedia.org/wiki/MIT_License)
A [remark](https://github.com/wooorm/remark) plugin that downloads artifacts
from [Gitlab](https://gitlab.com) projects to live alongside your Markdown.
## Installation
```sh
$ 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](https://docs.gitlab.com/ee/ci/yaml/README.html#jobs). 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`.
```md
[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:
```sh
example.md:1:1-1:60: artifacts fetched from 851 docs
```
### `error`
Added when something went wrong fetching the artifact:
```sh
example.md:1:1-1:62: Not Found from https://gitlab.com/api/v4/projects/fafds/jobs/artifacts/master/download?job=docs.
```
## Example
```js
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:
```js
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 });
});
```