vuepress-plugin-encrypt Documentation
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.