preface

  • 【 Music Blog 】Online!
  • Why do you want to document?
  • Because a project if there is no documentation, docking difficulty increased, and then also convenient to see their own code, don’t three days, when the code to treat each other, convenient to others, more convenient to yourself
  • : or because colleagues recently on the hungry, and then found by hungry? Document is tied together with code components, want to pull away from the document, the results found that the coupling is too high, also thinking about their own project should also have a document, so inspired after go to understanding once found vuepress is nice, md, written document
  • Recently we have been re-packaging the hungry me components, which can be placed on the Vuepress document
  • Some of my github friends didn’t get over the wall, so I deployed another set on vuePress documents on Ali Cloud

Site Effects Style

Six aspects:

1. Download vuepress

  • Github portal: github.com/git-Dignity…

  • Liverpoolfc.tv: caibaojian.com/vuepress/gu…

  • Git Clone official Github first, run to see the complete effect. Then according to the official website introduction and reference articles, combined with the complete code, step by step configuration content. Finally, reference Element’s design style, modify and add code to form a platform component library website.

  • After pulling the code on Github, you can try NPM Run Docs :dev directly. The second three points in this article will give you a better understanding of VuePress

2. Understand the VuePress structure

  • The configuration file

  • Configuration (see links: caibaojian.com/vuepress/co…). The basic file for the VuePress site is.vuepress/config.js, which exports a JavaScript object:

  • Module. exports = {title: 'export ', base: '/vuePressDos/', description:' export ', // './dist', // set output directory port: 2333, // themeConfig: {// theme configuration // add navigation bar nav: [{text: 'home ', link: '/'}, // navigation bar {text:' home ', link: '/'}, // navigation bar {text: 'home ', link: '/'}, // navigation bar {text: 'Component documentation ', link: '/baseComponents/'}, {text:' knowledge base ', link: '/knowledge/'}, {text: 'interface specification ', link: '/interfaceSpecification/', {text: 'github', // here is a dropdown display. Items: [{text: 'focus-outside', link: 'https://github.com/TaoXuSheng/focus-outside' }, { text: 'stylus-converter', link: 'https://github.com/TaoXuSheng/stylus-converter'},]}], / / for the following routing add sidebar sidebar: {'/baseComponents: [{title: Collapsable: True, Children: ['base/test1', 'Base /test2',' Base /test3', 'Base /test4',' Base /test5']}, {title: 'Visual components ', collapsable: True, children: []}, {title: 'collapsable: true, children: []}], '/interfaceSpecification/': [{title: collapsable: true, children: []}, {title:' Collapsable: true, children: []}], '/interfaceSpecification/': [{title: collapsable: Collapsable: True, Children: [' Base /apiRequest', 'Base /apiRespone',' Base /apiOther']}]}}}Copy the code

  • The theme configuration section: Modify the style in.vuepress/override.styl:

  • $accentColor = #3EB9C8 // theme color $textColor = #2c3e50 // textColor $borderColor = #eaecef // borderColor $codeBgColor = #282c34 // Content pre{margin: 0! important; }Copy the code

  • Add other extensions

  • Plugin NPM installation: element-UI, vue-echarts, vue-highlight.

  • Introduced at.vuepress/ enhanceapp.js:

  • /** * extension VuePress */ import VueHighlightJS from 'vue-highlight.js'; import 'highlight.js/styles/atom-one-dark.css'; import Element from 'element-ui' import 'element-ui/lib/theme-chalk/index.css' import VueECharts from 'vue-echarts' Import './.. /. Vuepress/public/CSS/index. The CSS 'export default ({Vue, / / vuepress is using the Vue constructor options, / / attached to the root instance of some options for the router, SiteData => {//... Use (VueHighlightJS) vue. use(Element) Vue.component('chart', VueECharts)}Copy the code

3. Some apps on Markdown

  • Markdown extension

  • Call someone else to write good wheels: www.npmjs.com/package/vue…

  • <highlight-code slot="codeText" lang="vue"> <template> <div class="demo-button"> <div> <dt-button> default </dt-button> <dt-button type="primary"> <dt-button type="success"> <dt-button type="success" </dt-button> <dt-button type="primary" </dt-button type="warning"> </dt-button type="warning"> </dt-button type="danger"> </dt-button> </div>  </template> </highlight-code>Copy the code

  • Use Vue—– to insert button styles in Markdown

  • Start with a button component.\vuepress\docs\.vuepress\components\ SRC \button.vue

  • <template> <button class="dt-button" @click="handleClick" :disabled="disabled" :autofocus="autofocus" :type="nativeType"  :class="[ size ? 'dt-button--' + size : '', type ? 'dt-button--' + type : '', { 'is-disabled': disabled, 'is-round': round, 'is-plain': plain } ]"> <i :class="icon" v-if="icon"></i> <span v-if="$slots.default"><slot></slot></span> </button> </template> <script> export default { name: 'DtButton', props: { size: String, type: { type: String, default: 'default' }, nativeType: { type: String, default: 'button' }, disabled: Boolean, round: Boolean, plain: Boolean, autofocus: Boolean, icon: { type: String, default: '' } }, methods: { handleClick (event) { this.$emit('click', event) } }, mounted () { this.$emit('click', event) } } </script>Copy the code

  • Vuepress \docs\.vuepress\public\ CSS \button.css

  • In. \ study \ vuepress \ docs \. Vuepress \ \ public \ CSS index. The CSS summary

  • @import './iconfont.css'; @import './icon.css'; @import './card.css'; @import './button.css'; // button component @import './checkbox.css';Copy the code

  • Call button under the.vuepress\ docs\.vuepress\components\test\test1.vue folder

  • <template> <div class="demo-button"> <div> <dt-button> <dt-button type="primary"> <dt-button type="success"> <dt-button type="info"> <dt-button type="info"> <dt-button type="info"> <dt-button type="success" </dt-button> <dt-button type="danger"> </dt-button> </div> </div> </template> <script> import DtButton from '.. /src/button' export default { name: 'buttonWrap', components: { DtButton } } </script> <style lang="less" scoped> .demo-button{ width: 100%; text-align: center; div { margin: 10px 0; } } </style>Copy the code

  • Vuepress automatically registers components by path, and we can invoke components by mapping file paths.

  • In the. \ vuepress \ docs \ baseComponents \ base \ test1 md

  • Test1 -- < common-democode title=" basic usage "description=" basic button usage "> <test-test1></test-test1> <highlight-code slot="codeText" Lang ="vue"> <template> <div class="demo-button"> <div> <dt-button> Default button </dt-button> <dt-button Type ="primary"> <dt-button type="success"> <dt-button type="info"> <dt-button type="warning"> </dt-button type="danger"> </dt-button> </div> </div> </template> </highlight-code> </Common-Democode> | Tables | Are | Cool | | ------------- |:-------------:| -----:| | col 3 is | right-aligned | $1600 | | col 2 is | centered | $12 | | zebra stripes | are neat | $1 |Copy the code

  • The display effect is shown as follows:

4. Deploy to Github

  • Create a new repository on GitHub
! [](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/db7004c553c64500b16b21f329b8380f~tplv-k3u1fbpfcp-zoom-1.image) **Copy the code

  • The repository name must have the same value as the base attribute in config.js

  • Modify the base

  • If we deploy.github. IO, github will automatically deploy it as GitPages

  • If we want to deploy to Github or other gitee repositories, ** we must specify base, the base property name must be the same as the repository name, otherwise we will get a 404 problem on the blog front page

  • As shown in the figure, my github repository name is vuePressDos, then base must be configured as:

  • Go to docs/.vuepress/config.js and configure base

  • Module. exports = {title: 'export ', base: '/vuePressDos/', description:' export ', // './dist', // set output directory port: 2333, // port....... }Copy the code

  • Now run: NPM run docs: Build package, cut the dist file to the root directory, delete the empty dist folder, and push the root directory to Github.

  • Go to Settings, slide down, go to GitHub Pages (usually for static websites), see the green, Your site is Published at url, and there you go, click on the link to see our document

  • PS: The link appears because the packaged Dist is taken as the master branch. You must select the github branch corresponding to the packaged file

5. Deploy to Ali Cloud server

  • base

    Type: string Default: / The base path of the deployment site, which you will need to set if you want your site to be deployed to a subpath. Github Pages, if you want to deploy your site to foo.github. IO /bar/, then base should be set to “/bar/” and its value should always start with and end with slashes. Base will automatically be inserted as a prefix in all links for other options starting with /, so you only need to specify it once.

  • This configuration is the most basic routing configuration. Vuepress, like other vUE projects, is a single page application. This configuration solves the problem of basic routing. The problem I ran into was how to configure this route on Nginx.

  • Configuration on nginx

  • Vuepress insidedocs\.vuepress\config.jsSet the base configuration to “/” (important)

  • We put the packaged vuepress files on nginx

    server { listen 8088; server_name localhost;

    location / { root html; // Build the server path) index index.html index.htm; try_files $uri $uri/ /index.html; } # root /usr/local/nginx/ HTML; index index.html index.htm;Copy the code

    }

Base: ‘/vuePressDos/’, Uncaught SyntaxError: Unexpected Token < An error

6. Github branch store source code

  • The above method is to put the packaged file on github main support, we want to put the source code what to do?

  • At this point we can branch out again

  • Master put the packaged dist out of the file

  • The Dev branch holds our source code

  • Create branches on Github

7. Precautions

  • If you jump to 404, check

  • Base is configured with the same name as the Github project repository

  • The website address of the code cloud Gitee Pages service is all lowercase. Change the base part of config.js to lowercase to solve the problem of vuepress redirect 404

  • Possible errors:

The original address

Juejin. Cn/post / 685457…

reference

VuePress website

VuePress quickly pits

VuePress deploys GitHub and Gitee in the same potholes

How to deploy vuePress on Github Pages

Build an Element-like document using VuePress

Quick vUE documentation/blog + free deployment preview for VuePress

Vuepress generates static files and is deployed to the Nginx reverse proxy server

[Long and repetitive] Build and optimize VuePress step by step (watch video)