Recently, an open source project is very popular, that is VuePress developed by You Xiaoyou. VuePress makes it very easy for you to write Vue code in Markdown documents, and VuePress does some search engine optimization for the compiled HTML files. In addition, VuePress has made some extensions to the Markdown file to make it more powerful. This article will focus on building a static blog on Github.

Join VuePress for the project

The first step is to install VuePress for your project. If you don’t have a package.json file in your project code, execute NPM init first.

NPM install -d vuepress // or yarn add -d vuepress // Add docs folder mkdir docs // create a Markdown file echo "# Hello VuePress!" > docs/README.mdCopy the code

The second step is to add these scripts to package.json and run them.

// package.json "scripts": { "docs:dev": "vuepress dev docs", "docs:build": "Vuepress build docs"} // NPM run docs:dev // build static HTML file NPM run docs:buildCopy the code

VuePress extends Markdown so that we can use YAML syntax in Markdown files. VuePress uses — to isolate Markdown syntax.

-- // This syntax means that the current page title automatically generates the sidebar: auto --Copy the code

VuePress basic configuration

From the VuePress profile you can use some custom functions such as adding sidebars, adding navigation bars and so on. First create a.vuepress directory under the docs directory and create config.js under it.

  1. By default, VuePress packages files in.vuepress/distDirectory, we can go throughdestProperty to modify the output directory of the file, for example, to output the file in the project root directorydistFolder.
  2. By setting therepoVuePress will add a link to the Github repository in the navigation bar.
  3. Through Settings in VuePresstitleProperty to set the site’s title, which will be used as a prefix for all page titles, and will be applied to the navigation bar under the default theme.
  4. When writing a blog using VuePress and Posting to Github Pages, we may encounter the problem shown below, where the page is already there, but the styles and JS are not loading successfully. We can configure itbaseProperty to solve this problem,baseThe default value for the property is/. Suppose you plan to deploy code totaoxusheng.github.io/mt-blog/, thenbaseProperty should be set to/mt-blog/.Note: The value of the base attribute always starts with/and ends with /.

// dcos/.vuepress/config.js module.exports = {title: 'my-blog', dest: './dist', base: '/ mt - blog /, / / set the site root repo:' https://github.com/TaoXuSheng/mt-blog '/ / add lot link}Copy the code

Navigation bar and sidebar

If you want to add a navigation bar to your website in VuePress, you can add a navigation link by setting themeConfig. Nav and add a sidebar by setting the themeConfig. Sidebar property. If your navigation is a drop-down list, you can set it through the Items property.

// dcos/.vuepress/config.js module.exports = {themeConfig: {// add nav: [{text: 'vue', link: '/'}, {text: 'CSS' link: '/ blog/'}, {text:' js, link: '/ zhihu/'}, {text:' lot ', / / here is show form the drop-down list. The 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: ['/', '/ git', '/ vue']}}Copy the code

Sometimes we might need a multilevel sidebar, such as a blog system that places similar articles under the same directory, and we want to add a sidebar for all files in those directories, like the one below.

School exercises ── School exercises, school exercises, school exercises, school exercises, school exercises, school exercises, school exercises, school exercises, school exercises, school exercises, school exercises, school exercises, school exercises, school exercises, school exercisesCopy the code

For the multilevel directory sidebar, we need to use the object description. The following /git/ indicates that in the git directory, the default point is to the /git/ readme. md file.

// dcos/.vuepress/config.js
module.exports = {
  themeConfig: {
    sidebar: {
      '/vue/': [
        'one',
        'two'
      ],
      '/css/': [
        'three',
        'four'
      ]
    }
  }
}
Copy the code

Register components in VuePress

Writing Vue code in VuePress is consistent with the way we normally write single files, and there may be times when we need to use Vue’s UI component library. For example, Element, Mint, etc. When we use these UI component libraries in our projects, we register them in main.js or botostrap.js. Fortunately, VuePress also supports this functionality. We can do some application-level configuration by creating a.vuepress/ enhanceapp. js file. This file exprot default is a hook function, where you can do some special processing. Such as adding global routing hooks and registering external component libraries.

Import Vue from 'Vue' import Element from 'element-ui' import 'element-ui/lib/theme-chalk/index.css' export default ({ Vue, options, router }) => { Vue.use(Element) }Copy the code

In normal Vue development, sometimes we need to do some custom components. In VuePress, we can write our custom components in the.vuepress/ Components directory, and VuePress iterates through all the *. Vue files in that directory at compile time. And see them registered as global components.

/ / register a custom components / / docs /. Vuepress/components/hello.html vue < template > < div class = "CPT - hello" > hello vuepress Demo < / div > </template>Copy the code

This way we don’t need to register these components when we write Vue code in Markdown files, and we can use edges directly in Markdown.

// docs/.vuepress/vue/README.md <template> <div class="test-demo"> {{ msg }} <my-hello></my-hello> <el-button>button</el-button> </div> </template> <script> export default { data () { return { msg: 'Hello VuePress! ' } } } </script>Copy the code

Viewing online Examples

Deploy to Github Pages

After we have written the document, we come to the place we are most concerned about, how to push the packaged code to the gh-Pages branch of the remote repository. There should be many articles on the Internet describing how to do this, but many methods are quite troublesome. Fortunately, there are tools to solve this problem for us.

NPM install -d gh-pages // 2. Add the script command "scripts": {"docs:dev": "vuepress dev docs", "docs:build": "Vuepress build docs", // I changed the output directory of vuepress, so if you did not change the dest attribute of.vuepress/config.js //, Vuepress /dist "deploy": "gh-pages -d dist", "deploy:build": "npm run docs:build && gh-pages -d dist" } // 3. Package and push to the GH-Pages branch NPM run deploy:build // 4. Open your Github Pages at https://<yourname>/ Github. IO /<repo>Copy the code

Viewing online Examples

conclusion

Compared to Hexo, VuePress is easier to get started with and more powerful. For example, custom components can be registered in VuePress, and the learning cost of writing a Vue in VuePress is almost zero as usual. So if you are open sourcing a VUE-related library or other project, you can use VuePress as your document editing tool. Although I haven’t covered all the content of VuePress, I believe you will have a general understanding of VuePress after reading this article. You can at least set up a blog quickly. If you want to know more about VuePress, please refer to the VuePress Chinese API. Finally, AMway wave of stylus-Converter, an open source project I am working on, can be joined by interested students. Wish you all a happy life and have a good time during the May Day holiday.