Let’s start with a demonstration. Almost identical to vUE’s official documentation, page content is customizable. A preview of the effects of this tutorial after deployment.

After you’ve built your project with the tutorial, you’ll learn:

  • Quickly build a document/blog, later only need to modify markdown content and navigation parameters, can be packaged to generate a page in one click.
  • Pages have great load performance and search engine optimization (SEO), while other pages load on demand only when the user is browsing.
  • Automatically generates global search and records the last modification time.
  • You can embed vUE components or jump to other pages, and customize your own style templates for easy extension.
  • One-click free deployment to Github. Pages, no server required to have your own online documents/blogs.

Vuepress is a UE-driven static website generator developed by the University of Utah. The overall Markdown centric structure of the project allows you to document/blog writing with minimal configuration. However, the official Vuepress documentation is really unfriendly to people who have never used a library like this, which is in stark contrast to the accessibility of the official Vue documentation. What’s the theme? Why are there no page and navigation Settings in the configuration? Where are the first and other pages? Why can topics also be exported? The biggest feeling after reading the official vuepress document is confusion.

Pre-requirements:

  • Understand markdown file formats: * * * * *
  • Install NPM/YARN in the following environment: ☆☆☆☆

★☆☆☆

How to make a document structure?

First of all, I want to give you two very important ideas:

  1. The document structure of the Vuepress project must follow the official document format. For example, if you want to change the overall theme color, you must change palette. Styl under the styles folder. If you want to add vUE components to Markdown, the VUE components must be in the Components folder, and so on. When vuePress is packaged, it iterates through specific paths and file names, reading content to generate page structure and style.
  2. The ones we’re using here are the official default themes. Theme means the style and structure of the page. When you select a topic, the content structure of your document will be set according to the current topic.

Let’s start our production. Start by opening your Git client, creating a folder, and going to the folder.

Mkdir testproject // Create a folder, preferably in lower casecdTestproject // Go to the folderCopy the code

Then use NPM to install our vuePress globally.

npm install -g vuepress
Copy the code

Next initialize the project our project information and create our pageckage.json file

npm init -y 
Copy the code

Once created, go to our pageckage.json file and add two commands to our script

"scripts": {
    "dev": "vuepress dev docs", // for live preview"build": "vuepress build docs"// To package items},Copy the code

Next we need to create folders and files for the Vuepress project, create the overall architecture first and then follow the tutorial to see what is inside. If you don’t want to create it manually, you can clone my project directly. After clone, the structure will be exactly the same.

// Some contents are not necessary, you can refer to the official document if you want to customize your own. This is the way I wrote it. │ ├─ ├─ public │ ├─ Public │ ├─ ├─ public │ ├─ Public │ ├─ Public │ ├─ Public │ ├─ Public │ ├─ Public Such as image │ │ ├ ─ ─ styles / / store the style of the need to customize │ │ │ └ ─ ─ the palette. Styl theme colors / / configuration page file │ │ └ ─ ─ config. Js / / set the top navigation bar, side navigation, etc. The core of the project configuration file │ ├ ─ ─ Pages // Store markdown file, ├─ ├─ ├─ ├─ ├─ ├─ ├─ ├─ ├─ ├─ package.json // New NodeCopy the code

The official directory structure

How to set the specific content of the page?

Modify the overall page Settings

First let’s set up some Settings related to the browser TAB bar. Add the following code directly to our config.js file.

module.exports = {
    title: 'Split Spring Home page'// The name of the page displayed in the upper left corner and the title name of the homepage displayed in the browser TAB description:'Crack spring front end record', // meta description text for SEO // inject the tag head into the HTML <head> of the current page: [['link', 
            { rel: 'icon', href: '/egg.png'} // The browser TAB bar for the page icon, the first one'/'Will iterate through the public folder files],],}Copy the code

After modification, place our logo image in docs/.vuepress/public folder.

Then run our NPM run dev and open http://localhost:8080/ to get something like this. The icon and page name in the upper left corner are set:

Setting the Home Page content

Next, let’s set the content of the home page, modify the readme. md file according to the format given by the official website, and fill in the following content

---
home: trueActionText: Enter now → actionLink: /pages/folder1/testMarkdown-centric project structure that helps you focus on writing with minimal configuration. - Enjoy the development experience of Vue + Webpack, use Vue components in Markdown, and use Vue to develop custom themes. - Title: High performance Details: VuePress pre-renders static HTML for each page and runs as SPA when the page is loaded. ---Copy the code

Reminder: The first ‘/’ in the heroImage address configuration points to docs/.vuepress/public by default. You’ll need to place your home image in this folder. The first ‘/’ in the actionLink address configuration points to docs/ by default. If there is no path and the file does not exist, click in to redirect to 404. More on file paths later

You can view each of the above items against the image below, one to one. Run NPM run Dev again, and your page should look like the image below.

Modify the page navigation bar and side navigation bar

The navigation and sidebar changes were made in our config.js file, and added the following code to moudule. Exports:

module.exports = { //... // The path of the MD file and other files involved below will be explained in detail next themeConfig: {logo:'/egg.png'// The icon in the upper left corner of the navigation bar // the nav in the top navigation bar: [//'/'To not add a route, skip to the home page {text:'home', link: '/'}, // Format 2: add a dropdown menu, link to the file path {text:'classification'// By default, ariaLabel:'classification', // Label items for identification: [{text:'articles', link: '/pages/folder1/test1.md'}, // Click the tag to jump to the page generated by link's markdown file {text:'little', link: '/pages/folder2/test4.md' },
                ]
            },
            { text: 'Function Demo', link: '/pages/folder1/test3.md'}, // Format three: to jump to an external page, need HTTP/HTTPS prefix {text:'Github', link: 'https://github.com/dwanda'},], // Sidebar: automatically show/hide the sidebar according to whether the current file path matches the sidebar data: {'/pages/folder1/':[         
                {
                    title: 'Test Menu 1'// Collapsable:false, / /falseExpand menu for default, default valuetrue// Set the side navigation to automatically extract the markdown file title level, default 1 is h2 level children: [['test1.md'.'Submenu 1'], // The menu name is'Submenu 1', go to /pages/folder1/test1.md
                        ['test3.md'.'Submenu 2']
                    ]
                },
                {
                    title: 'Test Menu 2',
                    collapsable: false, 
                    children: [
                        ['test2.md'.'Submenu 1'[]}], //... Multiple different sidebars can be added, and different pages will display different sidebars according to the path}}}Copy the code

Our homepage should look something like this. Other pages cannot be redirected temporarily, because when clicking the menu here, the corresponding Markdown file of the page will be empty and the page will be redirected to 404 page. The sidebar will automatically match the current page path. If the sidebar data exists in the current page path, it will be displayed. If the path does not match, the sidebar will be hidden, which is why it can match different sidebars from page to page.

Markdown and other file path resolution

At this point, our navigation bar, sidebar and home page have been roughly conceptualized, but if you click on our navigation jump page, you will be redirected to 404. Our links all link to markdown files, which automatically generate pages when vuePress is packaged. If the markdown file for the link does not exist, 404 will be jumped. If so, jump to the page generated by parsing.

It is also important to clarify the concept of vuepress file addressing. Different types of files have different default paths preset. Logo image reference path like step on, for instance, is to traverse the docs /. Vuepress/public/an egg. The PNG for file, we only need to put the pictures in this folder. Markdown files are placed as I wrote them in the Docs/Pages folder, where each folder name is a subpath. And so on. Each different type of document must be placed in a specified location.

The default addressing mode for the file path

  • For static resources such as ICONS/images, the first ‘/’ default points to docs/.vuepress/public/
  • The markdown file linked to in the sidebar/navigation bar, the first ‘/’ by default points to docs/, which we put in docs/ Pages
  • Vue components used in the embedded in the markdown, placed in the docs /. Vuepress/components directory

Category – Articles
Test menu 1- Submenu 1
'/pages/folder1/test1.md'
docs/pages/folder1/test1.md

According to the navigation parameters set earlier, we need to create the following files in the Pages folder, and fill in certain content in each Markdwn file, so as to test the effect.

## Markdown sample content, you can fill in other.

#### several ways to introduce third-party external Js into Vue components
https://blog.csdn.net/u010881899/article/details/80895661

#### nginx one-click configuration
https://nginxconfig.io/

#### Lodash is loaded on demand
https://www.jianshu.com/p/f03ff4f3a8b3
Copy the code

Once our Markdown file is created, our navigation and sidebar jump links have corresponding files. Click the category – Article in the top navigation bar again to jump to the following page:

After the document structure is roughly sorted out, we only need to modify the navigation bar and sidebar in the config.js file each time to ensure that there are corresponding files in the corresponding position of each path, and we can focus on editing the Markdown document.

How to deploy to Github Page with one click?

Creating a remote repository

The official purpose of Github. Pages is to provide a custom interface for Github projects, so that users can have richer pages to introduce their projects. Each repository can only have one main site of its own and expand from there. Because there is no database relationship, so can only build static web pages. This is essentially a free server that allows you to deploy your own pages.

The steps to create and use them are also simple. First log in to your Github account, hover over the plus sign in the upper right corner, click New Repository, and enter ‘your username ‘+.github. IO for Repository name, e.g. Danda.github. After that, you don’t need to set anything, just click Create Repository below to complete the steps of creating the repository.

The repository name must be your username +.github. IO, otherwise it needs to be set separately.

Configure the permission for the local push to the remote repository

Here is the configuration procedure for how to upload local projects to Github. Gitbash is used, it is recommended to install one if Windows does not have one. For A MAC, see the configuration process in this article.

Go to the Git-bash screen and:

Step one, input

git config --global --list 
Copy the code

Verify that the mailbox is the same as the account and name used to create the repository on GitHub. If they are inconsistent, run the following command to modify them.

Git config --global user.name git config --global user.name Git config --global user.email git config --global user.emailCopy the code

Second, run the following command to produce the key on your local computer

Ssh-keygen -t rsa-c Specifies your login email addressCopy the code

Step 3: The command will generate the following file in your computer’s C:\Users\ your username \. SSH folder after successful execution.

id_rsa.pub

Step 4: Open our Github page, click the profile picture in the upper right corner, click setting in the drop-down menu, jump to the page, click SSH and GPG keys in the sidebar, and click New SHH Key to enter our following interface

Step 5, test whether you are connected to Github

ssh -T [email protected]
Copy the code

If it works, the following screen will be displayed:

Use scripting to write package and upload commands

Next, following the official deployment tutorial, we need to modify the deploy.sh file we created initially. The purpose of this file is to batch execute our packaging, upload to warehouse and other commands. The. Sh format is a script file.

Sh File contents:

Make sure the script throws any errors it encounters
set -e

Package to generate static files
npm run build

# Go to the packed folder
cd docs/.vuepress/dist

Create a local git repository and commit your changes
git init
git add -A
git commit -m 'deploy'

Publish local repositories to Github overwrite, since publishing does not require a history
Git push -f [email protected]:' username '/' repository '.git master
git push -f [email protected]:dwanda/dwanda.github.io.git master

cd -
Copy the code

Then modify our package.json to add a command to execute our script file

"scripts": {..."deploy": "bash deploy.sh"}, // the git-bash command is used to execute files"start deploy.sh"
Copy the code

And then every time we execute it, we just run it

npm run deploy
Copy the code

Github will automatically update the page agent for us. It usually takes a minute or two before you open https:// your username.github. IO and see your docs/blog page. After completing the structure adjustment of the entire project, only need to edit a lost place, you can achieve editing documents + maintenance, is not very convenient!

Other questions:

Hot update problem

Since there is no hot update to the project structure, NPM run dev needs to be rerun every time you adjust config.js. Updates to existing Markdown files are hot in real time.

Change the theme color

Only need in our * * ‘. Vuepress/styles/palette. Styl ‘* * file to add the code, change its color to save again, will automatically change.

/ / the default value$accentColor = # 3eAF7c // Theme color
    $textColor = #2c3e50
    $borderColor = #eaecef
    $codeBgColor = #282c34
    $badgeTipColor = #42b983
    $badgeWarningColor = darken(#ffe564, 35%)
    $badgeErrorColor = #DA5961
Copy the code

For more colors, see the default Settings on the official website.

Embed vUE components in Markdown

First put the vue component editor, directly on our previously created docs /. Vuepress/components folder, as shown in the figure below:

You just need to use the component directly in the Markdown file as follows. Vue components can be loaded without additional imports.

<ClientOnly> <HomeLayout/> // Your component name </ClientOnly>Copy the code

The warehouse name is not formatted

If the repository name cannot use username +github. IO, or needs to be placed in a subdirectory of a project. You need to change the root directory of our config.js file by referring to the official website, and change the directory of the deploy.sh file to Github by referring to this section. Then go to the github Pages of setting in the repository and set your source to master, refresh and you can see the address of the page deployed in the Github Pages of Setting. The path associated with the image also needs to be changed, see the solution in the comments section. Suggest novice press my top to good, little trouble.

Vue component loading delay problem

Because the loading of vue and the page components parsed by Markdown create inconsistent loading times, it can be visually slow.

  • It is recommended that you only write pages using pure MarkDown
  • Or embed only vUE components in markdown without adding additional MarkDown statements.

Additional extensions to markdown content

  • Add a local image resource
  • Other extension rules for Markdown styles include line numbers, highlighting of code in different formats, custom containers, and more.
  • Default jump rules for markDown links, the default is to jump to other pages inside the site, if you need to jump to external pages remember to addhttp/httpsPrefix.

Some other features on the official website

  • Overall directory structure
  • Other details of config.js configuration
  • Enable automatic recording of the last change time and is displayed in the lower right corner of the page
  • Enable PWA to implement offline cache
  • Develop your own theme

That’s the end of the article. Here are two people who read it: