vuepress-plugin-github-markdown

VuePress plugin for importing markdown from Github

Setup

Create Github App for Organization:

1. Register new Github App

• Please follow guide 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.

1. Install Github App

• Please follow guide 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'],
  },