Highlights of the project

I started experimenting with Vuepress when it was born and there are a lot of great people who have written good articles about it. I didn’t intend to write it at first, but thought it might help some people build a blog faster and easier. I built VuePress as a template, introduce some of the necessary configuration items, a faster understanding of VuePress, while writing articles on it.

After two years, I recently company downsizing, but unemployed, interview a few not satisfied with the idle down, back to the original starting point, summed up this year to learn the knowledge, by the way, these two years off more articles fill back.

Some advantages of this project

  1. Automatically generate sidebars and groups
  2. Automated deployment to GitHub and code cloud

VuePress

A static station generator based on Vue SSR, which was originally created to support the documentation requirements of Vue and its subprojects.

Why not… ?

Nuxt

Nuxt can theoretically do what VuePress can do, but Nuxt was built to build applications, while VuePress focuses on content-centric static websites and offers out-of-the-box features tailored for technical documentation.

Docsify / Docute

Both projects are also Vue based, however they are completely run-time driven and thus not SEO friendly. If you don’t care about SEO and don’t want to install a lot of dependencies, they’re still a great choice!

Hexo

Hexo has always driven Vue documentation — in fact, we probably have a long way to go before we migrate our main site from Hexo to VuePress. Hexo’s biggest problem was that its theme system was too static and relied too much on pure strings, and we wanted to make good use of Vue to handle our layout and interactions, while Hexo’s Markdown rendering configuration was not the most flexible.

GitBook

We have been using GitBook for our subproject documentation. The biggest problem with GitBook is that when there are many files, the reload time after each edit is unbearably long. The default theme navigation structure is also somewhat restrictive, and the theme system is not Vue driven. The team behind GitBook is now more focused on making it a commercial product than an open source tool.

Quick learning

Global installation

Perform the following operations on the CLI, console, or terminal.

Create project directory
mkdir vuepress && cdVuepress // Generate a vuepress folder and enter itInitialize the project
npm init

Install VuePress as a local dependency
yarn add -D vuepress NPM install -d vuepress

Create a new docs folder
mkdir docs

Create a new markDown file
echo '# Hello VuePress! ' > docs/README.md

Copy the code

Next, add some scripts to package.json:

  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"."docs:dev": "vuepress dev docs"."docs:build": "vuepress build docs"
  },
Copy the code

Then you can run the project

yarn docs:dev NPM run docs:dev
Copy the code

Package and deploy to the GitHub server

yarn docs:build NPM run docs:build
Copy the code

Directory structure

Vuepress ├── docs │ ├─.vuepress │ │ ├─ ├─ public │ │ ├─ config.js ├─ ├─ download.txt └─ download.txt └─ download.txtCopy the code

Basic Topic Configuration

The configuration file

Start by creating a.vuepress directory in your documents directory, where all vuepress-related files will be stored.

The necessary configuration file for a VuePress website is.vuepress/config.js, which should export a JavaScript object:

module.exports = {
  title: 'Hello VuePress', // The title of the website description:'Just playing around'// Site description}Copy the code

The navigation bar

// .vuepress/config.js
module.exports = {
  themeConfig: {
    nav: [
      { text: 'home', link: '/' },
      { text: 'guide', link: '/guide/' },
      { text: 'Google', link: 'https://google.com'}}},]Copy the code

When you provide an array of items instead of a single link, it will display as a drop-down list:

module.exports = {
  themeConfig: {
    nav: [
      {
        text: 'language',
        items: [
          { text: 'Chinese', link: '/cn/' },
          { text: 'English', link: '/en/'}]}}Copy the code

Sidebar grouping

// .vuepress/config.js
module.exports = {
  themeConfig: {
    sidebar: [
      {
        title: 'Group 1'// Necessary path:'/foo/'// Optionally, the jump link for the header should be an absolute path and must exist collapsable:false// Optional, the default value istrue, sidebarDepth: 1, // Optional, default is 1 children: ['/'
        ]
      },
      {
        title: 'Group 2',
        children: [ /* ... */ ]
      }
    ]
  }
}
Copy the code

See here, find something, you write the article may be guide catalog or other directory, probably a few articles also good, but given the subsequent hundreds of the article, in the sidebar, need to manually configure paths, subsequent articles to modify the file name and path, a no heart error may waste of similar blogs. Difficult to maintain.

Next, I will introduce how to save the article in the directory and the article will automatically generate the sidebar.

Generate the sidebar automatically

Create an utils directory under the.vuepress directory and create initPage.js and index.js files

InitPage. Js file

const fs = require('fs'); // Exclude checked fileslet excludes = ['.DS_Store'];

let filehelper = {
  getFileName: function(rpath,otherPath) {
    let filenames = [];
    letfileTypes = /\.md$/; // Match only files ending in md fs.readdirsync (rpath).foreach ((file) => {if (excludes.indexOf(file) < 0) {
        fullpath = rpath + '/' + file;
        let fileinfo = fs.statSync(fullpath);
        if (fileinfo.isFile()) {
          if (fileTypes.test(file) > 0) {
            if (file === 'README.md') {
              file = ' ';
            } else {
              file = file.replace('.md'.' '); } file = otherPath ? otherPath + file : file filenames.push(file); }}}}); filenames.sort(); / / sortingreturnfilenames; }}; module.exports = filehelper;Copy the code

Index. Js file

Index.js takes parameters and converts them to object format for easy use in config.js.

const utils = {
  genSidebar: function (title, children = [' '], collapsable = true, sidebarDepth = 2) {
    let arr = new Array();
    arr.push({
      title,
      children,
      collapsable,
      sidebarDepth
    })
    returnarr; }}; module.exports = utils;Copy the code

Create a themeconfig.js file in the.vuepress directory

const path = require('path');
const rootpath = path.dirname(__dirname);
const utils = require('./utils/index');
const filehelper = require('./utils/initPage.js');

const themeConfig = {
  nav: [
    {
      text: 'interview',
      link: '/Interview/',
    },
    {
      text: 'JavaScript',
      link: '/JavaScript/',
    },
    {
      text: 'Vuejs',
      link: '/vue/',
    },
    {
      text: 'CSS',
      link: '/css/',
    },
    {
      text: 'other',
      ariaLabel: 'Menu',
      items: [
        { text: 'VuePress', link: '/other/vuepress/' },
        { text: 'Development tools', link: '/other/ide/' }
      ]
    },
    {
      text: 'home',
      ariaLabel: 'Menu',
      items: [
        { text: 'Home Page 1', link: '/ 404 /' },
        { text: 'Home Page 2', link: '/404/Personal' }
      ]
    },
  ],
  
  sidebar: {
    '/JavaScript/': concatJs(),
  },
};

// JavaScript
function concatJs() {
  const arr = utils.genSidebar( 'JStst', filehelper.getFileName(rootpath + '/JavaScript/'), false); arr.push(... utils.genSidebar('Js-Vue',filehelper.getFileName(rootpath + '/JavaScript/vue/'.'vue/'),false));
  return arr;
}

module.exports = themeConfig;

Copy the code

Put some configuration adjustments here with themeconfig.js, so.vuepress/config.js can be written as follows. To keep the files from getting too long and the code a little more elegant, some directory adjustments on themeconfig.js will do.

const themeConfig = require('./themeConfig');

module.exports = {
  title: 'Liao Chun-xin Blog',
  description: 'Front end, front end tutorial, small program, personal blog, Liao Chunxin blog',
  themeConfig
};
Copy the code

References:

  1. Vuepress automatically generates the sidebar
  2. VuePress Chinese document

The deployment of

Create a deploy.sh file in the project directory and copy the following code.

Make sure the script throws any errors it encounters
# Upload vuepress source code and articles to the code cloud backup
set -e
git add -A
git commit -m 'blogCode'
git push [email protected]:qqlcx5/vuePressCode.git master
Package and switch to the packaged folder
npm run docs:build && cd docs/.vuepress/dist

Deploy to the code cloud
git init
git add -A
git commit -m 'deploy'
git push -f [email protected]:qqlcx5/qqlcx5.git master

# Deploy to Github Page
Git directory and re-upload
rm -rf .git
git init
git add -A
git commit -m 'deploy'
git push -f [email protected]:qqlcx5/qqlcx5.github.io.git master
cd -
Copy the code

The warehouse address will change by itself.

The window user double-clicks the deploy.sh file to upload the article to the cloud backup and deploy it to GitHub Page.

# Enter the vuepress project in the terminal:

./deploy.sh

# If permission denied is displayed, reset the permission and run again.

chmod 777 deploy.sh

./deploy.sh
Copy the code

conclusion

I wrote the VuePress tutorial to make some blog posts easier to manage, maintain and show to users. Fancy things, I think against the simple and beautiful style, the most important thing is that I can’t do, that’s the point. I will add the cool element of blog later, if I have the chance, will I climb together?

Personal blog

GitHub

To subscribe to