This is the documentation for npm package @oak-tree-house/vuepress-plugin-encrypt (opens new window). It's used to encrypt some part of text in markdown with keys. And without key, no one can get the content of your post, even when you GitHub repository is public.

1 Introduction

Sometime, it's necessary to encrypt some part of your posts which contain sensitive messages. Furthermore, when we are talking about encryption, we doesn't mean a div which display is none and then set to block when input string matches. What we want is a real encryption. This plugin encrypted the posts with aes-128-ctr, which I think can satisfy the needs of most people.

However, you may wonder whether this plugin is safe when the repository is public. This's exactly my situation. Don't worry. This plugin provide a CLI to encrypt or decrypt markdown files. It can also work with husky (opens new window) git hooks to ensure that you don't push unencrypted posts accidentally.

What's more, this plugin hacks VuePress, so that your customized markdown plugins and components can work normally. There are a few exceptions:

• Heading in the encrypted sections are not extracted.
• <script> and <style> in the encrypted sections are ignored.

Here is a demonstration. Just input vuepress-plugin-encrypt in the following dialog and click the button. Then you can see the content.

2 Getting Started

To install the plugin, run the following command. It provide a script named encrypt.

yarn add -D @oak-tree-house/vuepress-plugin-encrypt

And add the following lines to your <root>/.vuepress/config.js

module.exports = {
  plugins: [
    ['@oak-tree-house/encrypt']
  ]
}

It's recommended to add following part to your package.json. Replace <YOUR_SOURCE_DIR> with your real source dir. In the most case, it will be docs.

{
  "scripts": {
    "decrypt": "encrypt --source-dir <YOUR_SOURCE_DIR> --key-file keys.json --temp .temp-encrypt decrypt",
    "encrypt": "encrypt --source-dir <YOUR_SOURCE_DIR> --key-file keys.json --temp .temp-encrypt encrypt"
  }
}

Then add the following lines to .gitignore.

/keys.json
/.temp-encrypt

It is also recommended that you install husky and run a pre-commit hook to ensure encryption before commission.

To install husky, run:

yarn add -D husky

And then add the following lines to package.json.

{
  "scripts": {
    "check": "encrypt --source-dir site --key-file keys.json --temp .temp-encrypt check"
  },
  "husky": {
    "hooks": {
      "pre-commit": "npm run check"
    }
  }
}

And finally create keys.json with the following content. Replace YOUR-USERNAME with your preferred id. KEY-NAME and YOUR-USERNAME must match regular expression [A-Za-z0-9_]+.

{
  "user": "YOUR-USERNAME",
  "keys": {}
}

To encrypt some parts of your markdown, surround them when encrypt container.

::: encrypt key=KEY-NAME owners=USERNAME1,USERNAME2,...
hello
:::

Your must keep the supplied arguments order. That is first key and then owners. owners is a ',' separated username list. Only when the list contains your username, the encryption and decryption will take place.

Then run:

npm run encrypt

3 Configuration

This module can accept the following options. Supplied values are default values.

module.exports = {
  plugins: [
    ['@oak-tree-house/encrypt', {
      contentTitle: 'Encrypted Content',
      unencryptedText: 'The content is shown below. It should be encrypted when published.',
      encryptedText: 'This part of content is encrypted. To view it, you need to enter the correct key in the input field below.',
      decryptedText: 'The encrypted content is successfully decrypted and shown below.',
      decryptButtonText: 'Decrypt',
      decryptFailText: 'Failed to decrypt!',
      unencryptedIcon: undefined,
      encryptedIcon: undefined,
      decryptedIcon: undefined
    }]
  ]
}

When *Icon are provided, they act as the icon classes. It is meant to be used with FontAwesome or Material Design Icons.