# vuepress-plugin-github-markdown

> VuePress plugin for importing markdown files from Github

Latest version **1.0.3** (published 2020-06-24) · MIT license · 0 weekly downloads

## Install

```sh
npm install vuepress-plugin-github-markdown
pnpm add vuepress-plugin-github-markdown
yarn add vuepress-plugin-github-markdown
bun add vuepress-plugin-github-markdown
```

## Health

**Score 20/100 (F)** — status: abandoned.

Positive: has types; no vulnerabilities.

Warnings: low downloads; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.0.3 |
| Published | 2020-06-24 |
| First published | 2020-06-23 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 4 |
| Unpacked size | 11.4 KB |
| Known vulnerabilities | 0 (+25 in 1 direct dependencies) |
| Install scripts | no |
| GitHub stars | 0 |
| Author | Caleb Bodtorf |
| Maintainers | cbodtorf |
| Keywords | github, markdown, plugin, vuepress |

## Links

- npm: https://www.npmjs.com/package/vuepress-plugin-github-markdown
- Repository: https://github.com/getnacelle/vuepress-plugin-github-markdown
- Homepage: https://github.com/getnacelle/vuepress-plugin-github-markdown#readme
- Issues: https://github.com/getnacelle/vuepress-plugin-github-markdown/issues
- npm.io page: https://npm.io/package/vuepress-plugin-github-markdown

## Dependencies (4)

- [axios](https://npm.io/package/axios.md) ^0.19.2
- [@types/node](https://npm.io/package/@types/node.md) ^14.0.13
- [@octokit/rest](https://npm.io/package/@octokit/rest.md) ^18.0.0
- [@octokit/auth-app](https://npm.io/package/@octokit/auth-app.md) ^2.4.7

## Alternatives

- [@mdxeditor/editor](https://npm.io/package/@mdxeditor/editor.md) — 962.4K weekly downloads
- [mmdb-lib](https://npm.io/package/mmdb-lib.md) — 680.9K weekly downloads
- [playcanvas](https://npm.io/package/playcanvas.md) — 36.2K weekly downloads
- [@glw907/cairn-cms](https://npm.io/package/@glw907/cairn-cms.md) — 967 weekly downloads
- [markdown-to-confluence](https://npm.io/package/markdown-to-confluence.md) — 103 weekly downloads

## Recent versions

- 1.0.3 (latest) — 2020-06-24
- 1.0.2 — 2020-06-24
- 1.0.1 — 2020-06-23

## README

# vuepress-plugin-github-markdown

> VuePress plugin for importing markdown from Github

## Setup

### Create Github App for Organization:

1. [Register new Github App](https://github.com/organizations/H2Know/settings/apps/new)
  - Please follow [guide](https://developer.github.com/apps/building-github-apps/creating-a-github-app/) if you have questions.
  - Make sure to save the **Private Key** that is generated to your .env file `GITHUB_PRIVATE_KEY`.
      - May need to format the Private Key properly on single line for env file (The OSX script will format & save to clipboard for easy pasting):

        `awk -v ORS='\\n' '1' github-app-name.2020-06-21.private-key.pem | pbcopy`
      - Some deployment services (ie. Netlify) won't be able to parse the line breaks properly. When calling the env variable replace the line breaks like this: `process.env.GITHUB_PRIVATE_KEY.replace(/\\n/gm, '\n')`.
  - Also save the **App ID** to your .env file `GITHUB_APP_ID`.

2. Install Github App
  - Please follow [guide](https://developer.github.com/apps/installing-github-apps/) for installation.
  - On the installation page of the app, make note of the **Installation ID**** at the end of the url. (ie. `https://github.com/organizations/getnacelle/settings/installations/**9762656**`). Save to your .env file `GITHUB_INSTALLATION_ID`

### Installation:

`npm install -D vuepress-plugin-github-markdown`

### Add to `.vuepress/config`:

```
  plugins: [
    [
      'vuepress-plugin-github-markdown',
      {
        appId: process.env.GITHUB_APP_ID,
        privateKey: process.env.GITHUB_PRIVATE_KEY.replace(/\\n/gm, '\n'),
        installationId: process.env.GITHUB_INSTALLATION_ID,
        files: [
          {
            path: '/nuxt/changelog.html',
            owner: 'getnacelle',
            repo: 'nacelle-nuxt-starter',
            githubFilePath: 'CHANGELOG.md',
            modifyContent(content) {
              // Append title to markdown
              return '# @nacelle/nacelle-nuxt-starter' + '\n' + content
            }
          }
        ]
      }
    ]
  ]
```

#### Plugin Options:

| Name | Param[Type] | Describe |
| ---- | --------- | -------- |
| appId | String | App ID for Github App |
| privateKey | String | Private Key of Github App |
| installationId | String | ID of Github App installation |
| files | File[] | Array of file options for markdown files to import |

#### File Options:

| Name | Param[Type] | Describe |
| ---- | --------- | -------- |
| path | String | url path where the page will live in docs |
| owner | String | github owner/organization |
| repo | String | github repo name |
| githubFilePath | String | the url to the raw markdown file |
| modifyContent | (String): String | (optional) A function that can modify imported content if needed |


## Link to Markdown File in Sidebar:

We can link to the markdown file by using a standard sidebar group in the `config.js`:

```
  {
    title: 'Changelog',
    collapsable: true,
    path: '/nuxt/changelog',
    sidebarDepth: 1,
    children: ['/nuxt/changelog'],
  },
```

---
_Source: https://npm.io/package/vuepress-plugin-github-markdown · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._