Build documents using VuePress

preface

The company gave me a task to build an internal front-end document and prepare to use VuePress for development after some research. Of course, there are so many good articles online about VuePress that there was no need to write another one; However, after all, writing an article is a summary of their own learning, or write one!

This article is based on VuePress 1.x

The official documentation

VuePress

Project initialization

Create folder and generate. Json file

// create folder mkdir docs // project initialization NPM initCopy the code

Install and configure VuePress

/ / to entercdVuePress NPM install -d VuePress'docs'// error:'no such file or directory, stat 'F:\web\docs\docs' 'Mkdir docs // Create a Markdown fileecho "# Hello VuePress!"> docs/ readme. md // start preview NPX vuepress dev docsCopy the code

Enter http://localhost:8080/ in your browser to see Hello VuePress! The startup is successful

Then, configure package.json

{
  "scripts": {
    "docs:dev": "vuepress dev docs"."docs:build": "vuepress build docs"}}Copy the code

After the configuration, restart the system

npm run docs:dev
Copy the code

Refresh your browser and you can also see Hello VuePress! The configuration is successful

Test generating static HTML

npm run docs:build
Copy the code

Vuepress folder, dist folder. Vuepress folder, dist folder

| - assets └ ─ ─ CSS └ ─ ─ img └ ─ ─ js | - 404. | - index HTML. HTMLCopy the code

Right click on index.html and open it in the browser, you will find that the style is wrong. The reason for this is the path problem. Let’s set it up and put it on the server

/ / to entercdModule. exports = {// set the website title:'Front end document'// set the output directory dest:'./dist', // Set the site root path if you are visiting the address is'www.xxxx.com/wxDocs'So let's set it to'/wxDocs/'  
  base: '/wxDocs/'// Add a Github link, but this will be on the company's Intranet server, so it is empty // repo:' '} // Pack NPM run docs:buildCopy the code

You will notice that there is a dist folder in the root directory of your project. Upload everything in this folder to the server and delete the dist folder in the.vuepress folder

The configuration icon

/ / to entercdVuepress // Create folder mkdir publicCopy the code

Open an image using online Photoshop, change the image size to 16*16 or 32*32 or 64*64px, save it in ICO format and copy it to public

Change config.js and add the following code

  head: [['link', { rel: 'icon', href: '/logo.ico' }]]
Copy the code

Restart the browser and refresh the browser. If an icon is displayed in the navigation bar, the configuration is successful

Configuration page

If you want to completely customize your home page, here it is:

cdVuepress // create folder mkdir Components // Create the home page file in the normal way of writing vue'login.vue'Write the code vim login.vueCopy the code

Then modify it in the readme. md file to:

---
layout: login
---

<login />

Copy the code

Layout opens custom Settings, target links to your custom login.vue page, and then the following
is introduced

If you don’t want to customize it, you can use the default configuration. This is the official default configuration page of VuePress

I consider that the document is internal and not open to the public. If it is uploaded to the server, public users may find the document address on the search platform without explanation, so I need a login page and need to customize a login home page. I choose Layout and use VUE to completely customize it

Once the UI is written, you can write the login jump logic. First, create a new folder under the project Docs folder:

// Create a home folder in the root directory mkdir home //cdHome / / new'README.md'The files must be there and VuePress will automatically put them in the folder'README.md'convert'index.html'The vim readme.md file is needed to jump to vim readme.mdCopy the code

The newly built project structure is as follows:

| - dist | - docs └ ─ ─. Vuepress └ ─ ─ home └ ─ ─ the README. Md └ ─ ─ the README. Md | - node_modules | - package - lock. Json | - package. JsonCopy the code

Then attach a click to your login button

  methods: {
    goHome() {// Check whether the account password is correct logic... // Skip this.$router.push({ path: "/home/index.html"}); }}Copy the code

Your home page is now configured

Configuration navigation

VuePress configuration navigation is as simple as adding the following code to config.js:

module.exports = {
  themeConfig: {
    nav: [
      {
        text: 'home',
        link: '/home/'
      },
      {
        text: 'H5',
        link: '/H5/'
      },
      {
        text: 'the specification',
        link: '/Standard/'}... ] }}Copy the code

Create a link folder under the project docs folder and create a readme. md folder

Once it’s done, restart and refresh your browser to see what it looks like

Tips: The new folder is level with the home folder created above

Configure the sidebar

Configuring the sidebar is also very simple, starting with config.js

module.exports = {
  themeConfig: {
    sidebar: {
      '/H5/': [
        'H5 and APP Connection Document '.'Manage backend development documents'].'/Standard/': [
        'H5 Development Specification '.'H5 Version Management Specification ']}}}Copy the code

Then, create a new. Md file in the corresponding folder, such as:

| - h5 └ ─ ─ h5 and app docking document. Md └ ─ ─ development document management background. Md └ ─ ─ the README. Md | - Standard └ ─ ─ h5 development specification. Md └ ─ ─ h5 version management specification. Md └ ─ ─ the README, mdCopy the code

The name you set in config.js should be the same as the name you created under the folder, but the actual name of the sidebar is the name of the first title you wrote under the.md file for H5 and app connection

Reboot and refresh the browser. You should see that the Settings have taken effect, but there seems to be a problem. Each title you generate in the.md file will generate a secondary page

module.exports = {
  themeConfig: {
    sidebarDepth: '0',}}Copy the code

Personalized customization

Add it to config.js

Module.exports = {// block display line markdown: {lineNumbers:true}},Copy the code

The document scroll bar is ugly. Change it

/ / to entercdVuepress / / new'styles'Folder mkdir styles // New'index.styl' 和 'palete.styl'VuePress use'stylus'Preprocessor Vim index.styl Vim palete. StylCopy the code

Styl is a global custom style with permissions above the default. Palete. Styl overrides the default theme configuration

The index styl style

/* Define the scrollbar height and background height and width corresponding to the horizontal and vertical scrollbar dimensions */
::-webkit-scrollbar
{
  width: 8px;
  height: 8px;
  border-radius: 10px;
  background-color: #F5F5F5;
}

/* Define scrollbar track inner shadow + rounded corner */
::-webkit-scrollbar-track
{
  border-radius: 10px;
  -webkit-box-shadow: inset 0 0 6px rgba(0,0,0,0.3);
  background-color: #F5F5F5;
}

/* Define slider inner shadow + rounded corner */
::-webkit-scrollbar-thumb
{
  border-radius: 10px;
  -webkit-box-shadow: inset 0 0 6px rgba(0, 0, 3);border-radius: 10px;
  /* Linear gradient */
  background-image: -webkit-gradient(linear, left bottom, left top, color-stop(0.44, RGB (60,186,146)),color-stop(0.72, RGB (253187,)),color-stop(0.86, RGB (253187,)));transition: 0.3 s ease-in-out;
}
/* Define the slider hover style */
::-webkit-scrollbar-thumb:hover{
  background-image: -webkit-gradient(linear, left bottom, left Top, color-stop(0.44, RGB (253,187,45)),olor-stop(0.72, RGB (253187,)),color-stop(0.86, RGB (60186146)));transition: 0.3 s ease-in-out;
}

.site-name{
  background-image: -webkit-linear-gradient(left,
   #22c1c3, #fdbb2d 25%, #22c1c3 50%, #fdbb2d 75%, #22c1c3);
  -webkit-text-fill-color: transparent;
  -webkit-background-clip: text;
  -webkit-background-size: 200% 100%;
  -webkit-animation: myGradientChange 4s infinite linear;
  animation: myGradientChange 4s infinite linear;
}
@keyframes myGradientChange  {
  0%{ background-position: 0 0;}
  100% { background-position: -100% 0;}
}
Copy the code

Palete. Styl style

// click status $accentColor = #3eaf7c // text $textColor = #2c3e50 // borderColor = #eaecef // code background $codeBgColor = #282c34Copy the code

If you want to write a style for a single page, do so

// now a page'.md'Add -- pageClass: custom-page-class -- to the fileCopy the code

Then add it to index.styl

.theme-container.custom-page-class {
  /* page-specific rules */
}
Copy the code

The last

VuePress is relatively simple on the whole, and it is really difficult to write new ideas!

So, that’s it.

reference

Vuepress Pit climbing tour Vuepress Pit climbing quick Vuepress Blog Building notes (2) Personalized configuration