Mustom
Simple design theme for VuePress，Blog，耀 の 个人网站 | Mark の Personal Website (QQ Group: 595614161)
  
Sample: [vuepress-theme-mustom-sample](https://github.com/jinyaoMa/vuepress-theme-mustom-sample)
Language:
- [中文](https://github.com/jinyaoMa/vuepress-theme-mustom/blob/master/README.zh.md)
- [English](https://github.com/jinyaoMa/vuepress-theme-mustom/blob/master/README.md)
> **If you still feel confused after reading this documentation, please read and learn how my `$docs` is structured [here](https://github.com/jinyaoMa/vuepress-theme-mustom/blob/master/$docs), or welcome to ask me questions via Github Issues.**
> **Any Bug reports or suggestions can be posted into Github Issues in any format.**
# Installation
Create a folder with structure as below, and for detailed source folder structure `$docs`, see [\$docs](https://github.com/jinyaoMa/vuepress-theme-mustom/blob/master/$docs). `_posts` folder refers to [\$docs/_posts](https://github.com/jinyaoMa/vuepress-theme-mustom/blob/master/$docs/_posts).
```yml
# inside the new folder of your site
+ $docs # folder contains source of your site
- _posts # folder contains posts
- .vuepress # folder contains static source and config
+ public # folder contains static source
+ config.js # file stores configuration
+ package.json # file generated by using `npm init`
```
Run one of the following commands in the new folder of your site to install `vuepress` and `vuepress-theme-mustom`.
```bash
yarn add @jinyaoma/vuepress-theme-mustom -D
```
or with npm
```bash
npm i @jinyaoma/vuepress-theme-mustom -D
```
or manually download the clone `.zip` file [here](https://github.com/jinyaoMa/vuepress-theme-mustom/archive/master.zip), and extract the theme source code to the new folder of your site. Then, set `theme` attribute of `config.js` as below.
```js
theme: require.resolve('../../vuepress-theme-mustom-master/')
```
After installation succeeded, your site should be run on `localhost` using the command below.
```bash
vuepress dev \$docs
```
or built into `$docs/.vuepress/dist`
```bash
vuepress build \$docs
```
> Note: The backward slash ("\\") above is an escape character here while typing commands in command line or terminal.
# Explanation of `_secret.tpl.js`
To see how my `_secret.tpl.js` looks like, click [here](https://github.com/jinyaoMa/vuepress-theme-mustom/blob/master/$docs/.vuepress/_secret.tpl.js).
Using a secret config file, any `appid` and `appkey` can be stored locally and referred to `config.js` as showed below.
```js
const secret = require('./_secret');
module.exports = { // https://www.vuepress.cn/zh/config/
// ...
themeConfig: {
// ...
translate: secret.translate, // baidu translation
comment: secret.comment, // vssue setting
// ...
}
// ...
}
```
# Explanation of `config.js`
To see how my `config.js` looks like, click [here](https://github.com/jinyaoMa/vuepress-theme-mustom/blob/master/$docs/.vuepress/config.js).
## General VuePress Settings
```js
module.exports = { // https://www.vuepress.cn/zh/config/
// Entry of used theme
// theme: require.resolve('../../'), // My value
// manually download theme, and folder `vuepress-theme-mustom-master` is in the root of the project
// theme: require.resolve('../../vuepress-theme-mustom-master/'),
theme: '@jinyaoma/vuepress-theme-mustom', // Your value
// Site base
// base: '/', // My value, due to https://ma-jinyao.cn/
base: '/MyBlog/', // Your value, if https://yourUsername.github.io/MyBlog/
// Default title that appended to your site title
// title: '耀 の 个人网站 | Mark の Personal Website', // My value
title: 'XXX 的博客 | XXX\'s Blog', // Your value
// Default description that appended to your site description
description: 'XXX 的博客, XXX\'s Blog, XXX, Mustom, VuePress',
themeConfig: {
// ...
// About this section, go to header "Configuration of themeConfig"
}
// It isn't necessary to change 'head' if you want to replace files directly
// favicon is in folder $docs/.vuepress/public/
// apple-touch-icon is in folder $docs/.vuepress/public/assets/img/
head: [
// PWA settings, https://www.vuepress.cn/plugin/official/plugin-pwa.html
['link', { rel: 'icon', href: '/favicon.ico', type: "image/x-icon" }],
['link', { rel: 'manifest', href: '/manifest.json' }],
['meta', { name: 'theme-color', content: '#ffffff' }],
['meta', { name: 'apple-mobile-web-app-capable', content: 'yes' }],
['meta', { name: 'apple-mobile-web-app-status-bar-style', content: '#ffffff' }],
['link', { rel: 'apple-touch-icon', href: '/assets/img/apple-touch-icon.png' }]
],
// It isn't necessary to change 'markdown' if you don't mind to use settings below
// https://www.vuepress.cn/zh/config/#markdown
markdown: {
lineNumbers: false,
extractHeaders: ['h1', 'h2', 'h3', 'h4', 'h5', 'h6']
},
// It isn't necessary to change 'evergreen'
evergreen: true, // using old browser ?
// To use jsdelivr cdn, you should change the publicPath below
configureWebpack: () => {
if (process.env.NODE_ENV === 'production') {
return {
output: {
// My value, username=jinyaoMa, repo=vuepress-theme-mustom, branch=gh-pages
//publicPath: 'https://cdn.jsdelivr.net/gh/jinyaoMa/vuepress-theme-mustom@gh-pages/'
// Your value, if username=XXX, repo=MyBlog, branch=gh-pages
publicPath: 'https://cdn.jsdelivr.net/gh/XXX/MyBlog@gh-pages/'
}
}
}
}
}
```
## Configuration of `themeConfig`
> All of following attributes are inside `themeConfig` of `config.js`
> `author`, `year`, `maximizeLaunch`, `noEmpty` and `images`; These attributes are very simple, and you can try yourselves. `maximizeLaunch` set to `true` can help you to fully fill the launch with image covering the window. `noEmpty` can disable the empty component that occupies the empty space. `images` can let you replace images in custom urls, but you need to follow the structure below.
```js
images: { // for image replacment; no base needed; first layer key points to component name
ad: '/assets/img/ad.png',
avatar: '/assets/img/avatar.png',
brand: '/assets/img/brand.png',
hitokoto: {
left: '/assets/img/hitokoto.left.png',
right: '/assets/img/hitokoto.right.png',
},
empty: '/assets/img/empty.png',
records: '/assets/img/records.png',
},
```
### domain
This attribute is for sitemap generation **ONLY**.
- My value: `'https://ma-jinyao.cn'`
- Your Value: `'https://yourdomain.com/'`
### clustrmaps
Set `clustrmaps` to `null` or ignore it to disable above. This requires service from [clustrmaps.com](https://clustrmaps.com/).
```js
clustrmaps: {
id: "clustrmaps", // clstr_globe / clustrmaps
src: "//cdn.clustrmaps.com/map_v2.js?cl=333333&w=a&t=t&d=kuCCiVvtASTqmAMxPSTLcjxs-p8j6ht3LUi9z9Q-OKc&co=ffffff&cmo=3acc3a&cmn=ff5353&ct=333333"
},
```
### customBackgrounds
This attribute is for adding background images to the site under `skin-default`. If there are multiple images, they will be in slide show. You can have value looking like the below.
```js
customBackgrounds: [
'/assets/img/background.png',
'https://timgsa.baidu.com/timg?image&quality=80&size=b9999_10000&sec=1596065328389&di=ad7a9cc49e45547721005bd528325f0d&imgtype=0&src=http%3A%2F%2Fpic1.win4000.com%2Fwallpaper%2F2%2F58b4ef69ed377.jpg',
'https://timgsa.baidu.com/timg?image&quality=80&size=b9999_10000&sec=1596063652971&di=8b659ee5cd46f4006d082b626eb3bd0d&imgtype=0&src=http%3A%2F%2Fpicture.ik123.com%2Fuploads%2Fallimg%2F180330%2F4-1P330160644.jpg'
],
```
### socialShare
Looking to [this](https://sns.goyfe.com/guide/) for reference. The following example generates the result of above.
```js
socialShare: { // https://sns.goyfe.com/guide/
networks: ['qq', 'weibo', 'douban', 'email', 'whatsapp', 'facebook', 'reddit', 'telegram', 'line'],
email: 'jinyao.ma@outlook.com',
fallbackImage: '/assets/img/avatar.png',
noGlobalSocialShare: true
},
```
### notification
> `msg` strings should be in current sequence/index. 0 => `zh`, 1 => `en`
You can have multiple notification on start up, and they will be displayed in sequence and one-by-one. `msg` contains both strings in `zh` and `en`. The following example generates the result of above.
```js
notification: [
{ // welcome msg
type: 'default', // default or warning or error
msg: [
'欢迎来到我的个人网站！技术交流请加 QQ 群：595614161，也可以加本人QQ：907881445，或者点击页面左下角扫码找我哦~', // zh
'Welcome to my personal website! ' // en
]
},
],
```
### qrcodes
> `locale` strings should be in current sequence/index. 0 => `zh`, 1 => `en`
`locale` contains both string in `zh` and `en`. The following example generates the result of above.
```js
qrcodes: [{ // qrcode for contact and friending
locale: [
'QQ', // zh
'QQ' // en
],
path: '/assets/img/qq.png' // no base needed
}, {
locale: [
'微信', // zh
'WeChat' // en
],
path: '/assets/img/wechat.png' // no base needed
}],
```
### header
> `sitename` strings should be in current sequence/index. 0 => `zh`, 1 => `en`
`sitename` contains both string in `zh` and `en`. The following example generates the result of above.
```js
header: {
sitename: [
'耀 の 个人网站', // zh
'Mark の Personal Website' // en
]
},
```
### brand
> `signatures` strings should be in current sequence/index. 0 => `zh`, 1 => `en`
`signatures` contains both string in `zh` and `en`. The following example generates the result of above.
```js
brand: {
signatures: [
'我只想安静地做笔记', // zh
'I just wanna note silently' // en
],
contacts: [{
icon: '',
text: 'jinyaoMa',
link: 'https://github.com/jinyaoMa'
}, {
icon: '',
text: 'jinyao.ma@outlook.com',
link: 'mailto://jinyao.ma@outlook.com'
}, {
icon: '',
text: '907881445',
link: 'tencent://Message/?uin=907881445'
}]
},
```
### menus
> `caption` and `text` strings should be in current sequence/index. 0 => `zh`, 1 => `en`
`caption` and `text` contain both string in `zh` and `en`.
You can erase some of the items. This attribute isn't necessary to be edited if you have the same structure as my [\$docs](https://github.com/jinyaoMa/vuepress-theme-mustom/blob/master/$docs).
```yml
# inside the new folder of your site
+ $docs # folder contains source of your site
- _posts # folder contains posts, 'Home' and 'Archive' pages are auto-generated
- .vuepress # folder contains static source and config
- about # 'About' page
- codes # 'Code Library' page
- icons # 'Icon Font Library' page
- letter # 'Cover Letter Tips' page
- records # 'Records' page
- resume # 'Resume Tips' page
# 'Gallery' page is auto-generated
```
The following example matches the structure of above.
```js
menus: [{
caption: [
'本站', // zh
'MAIN' // en
],
icon: '',
items: [{
icon: '',
text: [
'首页', // zh
'Home' // en
],
link: '/'
}, {
icon: '',
text: [
'归档', // zh
'Archive' // en
],
link: '/archive/'
}, {
icon: '',
text: [
'关于', // zh
'About' // en
],
link: '/about/'
}]
}, {
caption: [
'工作', // zh
'JOB RELATED' // en
],
icon: '',
items: [{
icon: '',
text: [
'简历小贴士', // zh
'Resume Tips' // en
],
link: '/resume/'
}, {
icon: '',
text: [
'求职信小贴士', // zh
'Cover Letter Tips' // en
],
link: '/letter/'
}]
}, {
caption: [
'其他', // zh
'OTHERS' // en
],
icon: '',
items: [{
icon: '',
text: [
'代码库', // zh
'Code Library' // en
],
link: '/codes/'
}, {
icon: '',
text: [
'图标字体库', // zh
'Icon Font Library' // en
],
link: '/icons/'
}, {
icon: '',
text: [
'记录', // zh
'Records' // en
],
link: '/records/'
}, {
icon: '',
text: [
'图库', // zh
'Gallery' // en
],
link: '/gallery/'
}]
}],
```
### meting
The following example generates the result of above.
```js
meting: {
server: 'netease', // netease, tencent, kugou, xiami, baidu
type: 'playlist', // song, playlist, album, search, artist
id: '4989572738', // song id / playlist id / album id / search keyword
theme: 'var(--link)', // e.g. #ff3300
height: '297px' // playlist height, 297px ==> 9 lines
},
```
### portals
The following example generates the result of above.
```js
// external links; use for the component that displays after clicking on the left-top button of header
portals: [{
name: 'My Site',
desc: '耀 の 个人网站 | Mark の Personal Website',
icon: 'https://jinyaoMa.github.io/asset/img/author.medium.png',
link: 'https://jinyaoMa.github.io/'
}, {
name: 'MPlayer',
desc: 'APlayer 个人模仿练习版',
icon: 'https://blog.ma-jinyao.cn/asset/img/icon.medium.png',
link: 'https://blog.ma-jinyao.cn/MPlayer'
}, {
name: 'Resume',
desc: 'Resume Template',
icon: 'https://blog.ma-jinyao.cn/extension/resume/icon.png',
link: 'https://blog.ma-jinyao.cn/extension/resume/english/'
}, {
name: '简历',
desc: '简历模板',
icon: 'https://blog.ma-jinyao.cn/extension/resume/icon.reverse.png',
link: 'https://blog.ma-jinyao.cn/extension/resume/chinese/'
}, {
name: 'Cover Letter',
desc: 'Cover Letter Template',
icon: 'https://blog.ma-jinyao.cn/extension/letter/icon.png',
link: 'https://blog.ma-jinyao.cn/extension/letter/english/'
}, {
name: '求职信',
desc: '求职信模板',
icon: 'https://blog.ma-jinyao.cn/extension/letter/icon.reverse.png',
link: 'https://blog.ma-jinyao.cn/extension/letter/chinese/'
}, {
name: 'Palette',
desc: '想知道图片主题色？',
icon: 'https://blog.ma-jinyao.cn/extension/palette/icon.png',
link: 'https://blog.ma-jinyao.cn/extension/palette/'
}],
```
### hitokoto
You can put your words to `customs` for displaying, and these words are randomly picked on home page loaded. `type` is for hitokoto service setting referred to [developer.hitokoto.cn](https://developer.hitokoto.cn/sentence/#请求参数)
```js
hitokoto: {
customs: [/*{ // format; if customs exist, API will be ignored, and customs will be in use
word: 'https://developer.hitokoto.cn',
from: '一言开发者中心'
}*/],
type: 'i' // https://developer.hitokoto.cn/sentence/#请求参数
},
```
### gallery
You can add online images to gallery page, and they will be inserted to very top of the page and following by your local images that are auto appended. Local images are located at `/$docs/.vuepress/public/gallery`. To see mine, click [here](https://github.com/jinyaoMa/vuepress-theme-mustom/blob/master/$docs/.vuepress/public/gallery).
```js
gallery: [/*{ format; these gallery items will be appended to /gallery/ page
name: 'test image from baidu',
url: 'https://timgsa.baidu.com/timg?image&quality=80&size=b9999_10000&sec=1596063652971&di=8b659ee5cd46f4006d082b626eb3bd0d&imgtype=0&src=http%3A%2F%2Fpicture.ik123.com%2Fuploads%2Fallimg%2F180330%2F4-1P330160644.jpg'
}*/],
```
### pwa
> `message` and `buttonText` strings should be in current sequence/index. 0 => `zh`, 1 => `en`
`message` and `buttonText` contain both string in `zh` and `en`.
`popupComponent` is set to the custom component in theme source code. If you don't like the update popup, you can set `updatePopup` to `false`. Or if you don't want to use service worker, you can set both `serviceWorker` and `updatePopup` to `false`.
```js
pwa: { // https://www.vuepress.cn/plugin/official/plugin-pwa.html
serviceWorker: true,
popupComponent: 'CustomSWUpdatePopup',
updatePopup: {
message: [
'检测到可用的新内容。', // zh
'New content is available.' // en
],
buttonText: [
'更新缓存', // zh
'Refresh' // en
]
}
}
```
## Front-Matter for Posts
> `categories` and `tags` should be in flat. This theme does NOT support multi-dimensional arrays.
Every post should have similar structure of front-matter as showed below.
```yml
---
title: 'Post Title'
categories: # flat, ONLY ONE layer acceptable
- cate1
- cate2
tags: # flat, ONLY ONE layer acceptable
- tag1
- tag2
date: 2020-12-12 00:00:00
updated: 2020-12-12 00:00:00
---
```
## Front-Matter for Normal Pages
Example from my 'About' page, or to look at the original `index.md` file, click [here](https://github.com/jinyaoMa/vuepress-theme-mustom/blob/master/$docs/about/index.md).
```yml
---
title: 关于 | About
---
```
### Want to have a page similar to my 'Records' page?
Follow the format as showed below, or to look at the original `index.md` file of my 'Records' page, click [here](https://github.com/jinyaoMa/vuepress-theme-mustom/blob/master/$docs/records/index.md).
```yml
---
title: # page title
records:
enabled: true # set this to true to enable Records component
items:
- cover: # [empty] to use default cover
date: # string
title:
# e.g. [empty]
# e.g. book / article / paper / newspaper / report / picture / anime / video / movie / audio / project / website
# e.g. [customized] --> "Journal"
type:
author:
source:
# format 'number/total' OR '100%' OR [customized]; [empty] to use 'N/A', NO DECIMAL POINT ALLOW
# e.g. 12 / 34 ; 32/52 ; 22% ; 88% ; "Latest" ; "Complete"
progress:
summary:
---
```
### Want to have a page similar to my 'Code Library' page?
> To see how the Code Library structured in a Github Repository, refer to [jinyaoMa/code-lib](https://github.com/jinyaoMa/code-lib)
Follow the format as showed below, or to look at the original `index.md` file of my 'Code Library' page, click [here](https://github.com/jinyaoMa/vuepress-theme-mustom/blob/master/$docs/codes/index.md).
```yml
---
title: # page title
github:
user: # Github username
repo: # Github repo
readme:
enabled: true # set this to true to enable Readme component
stack:
enabled: true # set this to true to enable Stack component
---
```
### Want to have a page similar to my 'Icon Font Library' page?
> To see how the Icon Font Library structured in a Github Repository, refer to [jinyaoMa/icon-lib](https://github.com/jinyaoMa/icon-lib)
Follow the format as showed below, or to look at the original `index.md` file of my 'Icon Font Library' page, click [here](https://github.com/jinyaoMa/vuepress-theme-mustom/blob/master/$docs/icons/index.md).
```yml
---
title: # page title
github:
user: # Github username
repo: # Github repo
readme:
enabled: true # set this to true to enable Readme component
iframe:
enabled: true # set this to true to enable Iframe component
url: https://blog.ma-jinyao.cn/icon-lib/ # subpage should be in same-origin
---
```