preface

Because I often write blogs and have blog websites, the Leader asked me to make a technical selection for the HELP center of CMS. The function of the help center of CMS is to teach users how to use our project through articles.

So the author wants to make a static website technology selection, the author tried the popular online VuePress and GitBook two ways, and made a comparison, here to write an article to summarize, by the way, my own blog website for a new, haha.

Good news.

I think every developer should have their own website and server, it would be cool to learn Linux, run scripts, build a website, build a blog, whatever.

1. VuePress

1.1 introduction

VuePress is a VUUe-powered static web site generator.

Simple is the highest

Markdown-centric project structure helps you focus on writing with minimal configuration.

Vue drive

Enjoy the development experience of Vue + Webpack, using Vue components in Markdown and developing custom themes using Vue.

A high performance

VuePress pre-renders static HTML for each page and runs it as a SPA when each page is loaded.

1.2 the effect

Home page:

Comment on:

See: biaochenxuying. Making. IO/blog /.

1.3 Simple Use

As easy as counting 1, 2, 3

# installation
yarn global add vuepress NPM install -g vuepress

Create project directory
mkdir vuepress-starter && cd vuepress-starter

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

# Start writing
vuepress dev .

Build a static file
vuepress build .
Copy the code

1.4 Directory Structure

VuePress follows the principle of convention over configuration. The recommended directory structure is as follows:

├ ─ ─ docs │ ├ ─ ─. Vuepress (optional) │ │ ├ ─ ─ components (optional) │ │ ├ ─ ─ the theme (optional) │ │ │ └ ─ ─ Layout. The vue │ │ ├ ─ ─ public │ (optional) │ ├ ─ ─ styles (optional) │ │ │ ├ ─ ─ but styl │ │ │ └ ─ ─ the palette. Styl │ │ ├ ─ ─ templates (optional, Careful configuration) │ │ │ ├ ─ ─ dev. HTML │ │ │ └ ─ ─ SSR. HTML │ │ ├ ─ ─ the config, js (optional) │ │ └ ─ ─ enhanceApp. Js (optional) │ │ │ ├ ─ ─ the README. │ md ├ ─ ─ guide │ │ └ ─ ─ the README. Md │ └ ─ ─ config. The md │ └ ─ ─ package. The jsonCopy the code

Note: Please note that the directory name is capitalized.

  • docs/.vuepress: stores global configurations, components, and static resources.
  • docs/.vuepress/components: in the directoryVueComponents are automatically registered as global components.
  • docs/.vuepress/theme: Stores local themes.
  • docs/.vuepress/styles: is used to store style related files.
  • docs/.vuepress/styles/index.styl: the global style file that will be automatically applied will be generated in the finalCSSEnd of file, with higher priority than the default style.
  • docs/.vuepress/styles/palette.styl: Used to override the default color constant, or set a new onestylusColor constant.
  • docs/.vuepress/public: static resource directory.
  • docs/.vuepress/templates: storageHTMLTemplate file.
  • docs/.vuepress/templates/dev.html: for the development environmentHTMLTemplate file.
  • docs/.vuepress/templates/ssr.html: Build based onVue SSR 的 HTMLTemplate file.
  • docs/.vuepress/config.js: indicates the entry file of the configuration fileYML 或 toml.
  • docs/.vuepress/enhanceApp.js: Client application enhancements.

Note:

  1. When you want to customize templates/ssr.html or templates/dev.html, it’s best to base your changes on the default template file, otherwise you may end up with a build error.

  2. Templates /ssr.html and templates/dev.html add the following line:

<meta id="referrer" name="referrer" content="never" />
Copy the code

Because the author’s pictures are stored in the simple book, this code is added in order to access the pictures of the third party. If your pictures are stored locally, you can remove this code. Please refer to the article written by the author for specific reasons: Front end to solve the third party image anti-theft link method – HTML referrer access to picture resources 403 problems.

  1. The author’s directory is also recommended by the official, as follows:

1.5 comment

The comments feature uses GitTalk.

1.5.1 Applying for an OAuth App

Specific practices are as follows:

  1. First log in to your GitHub account and click on Settings.

  1. Click OAuth Apps, Register a new Application or New OAuth App.

  1. Input information.

  1. Application information:Client ID && Client Secret

Create Client ID and Client Secret, save it, we will use it later.

  1. Creating a comment component

Vuepress default components in the.vuepress/Components folder are registered globally, so we create a comment component.

Gittalk.css click here

<template> <div class="gitalk-container"> <div id="gitalk-container"></div> </div> </template> <script> export default {  name: 'comment', data() { return {}; }, mounted() { let body = document.querySelector('.gitalk-container'); let script = document.createElement('script'); script.src = 'https://cdn.jsdelivr.net/npm/gitalk@1/dist/gitalk.min.js'; body.appendChild(script); Script.onload = () => {const commentConfig = {clientID: 'your clientID', clientSecret:' your clientSecret', repo: Select * from 'admin ', owner:' username ', // select * from 'admin ', owner:' username ' [' admin username '], // id is the unique identifier for the current page. Generally speaking, pathName is sufficient, // But GitHub will not create an issue if your pathname is more than 50 characters long, Id: location. Pathname, distractionFreeMode: false,}; const gitalk = new Gitalk(commentConfig); gitalk.render('gitalk-container'); }; }}; </script> <style> @import '.. /css/gittalk.css'; </style>Copy the code
  1. Using the Comment component

In theory, we could add this component directly to each markdown file, but adding it each time is a bit cumbersome, so let Node do it for us

AddComponents. Js, delComponents. Js, findMarkDown.js.

// addComponents.js
const fs = require("fs");
const findMarkdown = require("./findMarkdown");
const rootDir = "./docs";

findMarkdown(rootDir, writeComponents);

function writeComponents(dir) {
    if (!/README/.test(dir)) {
        fs.appendFile(dir, `\n \n <comment/> \n `, err => {
            if (err) throw err;
            console.log(`add components to ${dir}`); }); }}Copy the code
// delComponents.js
const fs = require("fs");
const findMarkdown = require("./findMarkdown");
const rootDir = "./docs";

findMarkdown(rootDir, delComponents);

function delComponents(dir) {
    fs.readFile(dir, "utf-8", (err, content) => {
        if (err) throw err;

        fs.writeFile(
            dir,
            content.replace(/\n \n <comment\/> \n /g.""),
            err => {
                if (err) throw err;
                console.log(`del components from ${dir}`); }); }); }Copy the code
// findMarkdown.js
const fs = require("fs");

function findMarkdown(dir, callback) {
    fs.readdir(dir, function(err, files) {
        if (err) throw err;
        files.forEach(fileName= > {
            let innerDir = `${dir}/${fileName}`;
            if (fileName.indexOf(".")! = =0) {
                fs.stat(innerDir, function(err, stat) {
                    if (stat.isDirectory()) {
                        findMarkdown(innerDir, callback);
                    } else {
                        // Skip the readme file, although you can modify it yourself
                        if (/\.md$/.test(fileName) && !/README/.test(fileName)) callback(innerDir); }}); }}); }); }module.exports = findMarkdown;
Copy the code

Modify package.json scripts by adding components for each MD file, then packaging, and finally removing the comment component in markdown one by one.

"build": "node ./builds/addComponents.js && vuepress build docs && node ./builds/delComponents.js".Copy the code

In my project, I added two commands, such as NPM run dev:md and NPM run build:md, which have comment components.

"scripts": {
    "dev": "vuepress dev docs"."dev:md": "node ./builds/addComponents.js && vuepress dev docs && node ./builds/delComponents.js"."docs:dev": "vuepress dev docs"."build": "vuepress build docs"."build:md": "node ./builds/addComponents.js && vuepress build docs && node ./builds/delComponents.js"."docs:build": "vuepress build docs"."delay": "bash delay.sh"."test": "echo \"Error: no test specified\" && exit 1"
  },
Copy the code

You can modify the packaging commands you want.

  1. Pay attention to: If your article comments andgithub 的 issuesIn the case of synchronization, but also inissues 的 labelAdd the correspondingpathname 和 gitalk, includingpathnameIt’s in the comments componentlocation.pathname 。

Like mine:

1.6 Deployment on Github Pages

Once we had written the document, we came to the point where we were most concerned about pushing the packaged code to the GH-Pages branch of the remote repository.

  1. Create an deploy.sh file
touch deploy.sh
Copy the code
  1. Write a script
#! /usr/bin/env sh
Make sure the script throws any errors it encounters
set -e

Generate static files
npm run docs:build

Go to the generated folder
cd docs/.vuepress/dist

# if publish to custom domain name
# echo 'www.example.com' > CNAME

git init
git add -A
git commit -m 'deploy'

# if posted to https://
      
       .github
      
# git push -f [email protected]:<USERNAME>/<USERNAME>.github.io.git master

Github. IO /
      
# git push -f [email protected]:<USERNAME>/<REPO>.git master:gh-pages

cd -

Copy the code
  1. Set up thepackage.json
{
    "scripts": {
        "deploy": "bash deploy.sh"}},Copy the code
  1. release
NPM run deploy // Can be automatically built and deployed on Github.Copy the code
  1. Access to their own domain name, such as: the author biaochenxuying. Making. IO/blog /.

For details, visit the website of vuepress at vuepress.vuejs.org.

2. GitBook

Effect:

See biaochenxuying.cn:2021 for details.

2.1 Common instructions of GitBook

  • Install GitBook:npm i gitbook-cli -g
  • Initialize the GitBook project:gitbook init
  • Install GitBook dependencies:gitbook install
  • Enable the GitBook service:gitbook serve
  • Package the GitBook project:gitbook build
  • GitBook Command line view:gitbook -help
  • GitBook version view:gitbook -V

2.2 Easy to Get started

Then, we find an empty folder and initialize a GitBook project.

  • gitbook initInitialize the readme. md and summary. md files.
  • gitbook buildThe service is built locally but not run, and the default output is to the _book/ directory.
  • gitbook serveThe service is built and run locally, accessed by defaulthttp://localhost:4000Live preview.
- GitBook
 - README.md
 - SUMMARY.md
Copy the code

  • README.mdIs the default home page file, equivalent to the home page of the websiteindex.html, usually introductory text or related navigation links.
  • SUMMARY.mdIs the default summary file, mainly according to the file content to generate the corresponding directory structure, the sameREADME.mdIt’s all the samegitbook initInitialize important files created by default.
  • _bookIs the default output directory that holds the originalmarkdownAfter renderinghtmlFiles that can be packaged directly to the server for use as static websites. It’s usually executedgitbook build 或 gitbook serveAutomatically generated.
  • book.jsonIs a configuration file used for personalizationgitbookFor example, define the title, cover, author and other information of the ebook. Although created manually, this is usually mandatory.
  • GLOSSARY.mdIs the default vocabulary, mainly explains the specialized vocabulary in detail, so that there will be corresponding prompts when reading the specialized vocabulary, also manually created but optional.
  • LANGS.mdIs the default language file for internationalized version translation andGLOSSARY.mdAgain manually created but optional.

Book. Json

  1. title: Website title
  2. author: Website author
  3. description: Website function description
  4. language: Language used on the site
  5. styles: additional stylesheets for site configuration
  6. plugins: plugins used by websites
  7. pluginsConfig: Add-ons for web sites

The author of the book. The json:

{
  "title": "The blog of the Night."."author": "biaochenxuying"."description": "Be a lifelong learner, focusing on big front-end technology, supplemented by reading notes, essays and financial management."."language": "zh-hans"."plugins": [
    "-highlight"."copy-code-button"."search-pro"."-search"."-lunr"."expandable-chapters"."splitter"."-sharing"."github-buttons"."donate"."tbfed-pagefooter"."baidu-tongji"."anchor-navigation-ex"]."pluginsConfig": {
    "github-buttons": {
      "buttons": [{"user": "biaochenxuying"."repo": "blog"."type": "star"."count": true."size": "small"
        }, 
        {
          "user": "biaochenxuying"."width": "160"."type": "follow"."count": true."size": "small"}},"donate": {
      "button": "Exceptional"."wechatText": "Wechat Tip"."wechat": "https://camo.githubusercontent.com/ee094d402f957e5d656a399b9dc50ff8c010114e/68747470733a2f2f75706c6f61642d696d616765732 e6a69616e7368752e696f2f75706c6f61645f696d616765732f31323839303831392d666661623762643234643038633030642e6a7065673f696d616 7654d6f6772322f6175746f2d6f7269656e742f7374726970253743696d61676556696577322f322f772f31323430"
    },
    "tbfed-pagefooter": {
      "copyright":"Copyright &copy biaochenxuying.cn 2019"."modify_label": "Revision date of this document:"."modify_format": "YYYY-MM-DD HH:mm:ss"
    },
    "baidu-tongji": {
      "token": "XXXXX"
    },
    "anchor-navigation-ex": {
      "showLevel": false}}}Copy the code

2.3 plug-in

The configuration of plug-ins is at the heart of GitBook.

For more information, see GitBook – A quick way to create a wage-able blog, which I won’t go into here.

3. VuePress VS GitBook

The same

  1. Currently only supportedmarkdownStatic resources such as formats, pictures and videos can be saved locally or to third-party service providers that allow access (such as Qiuniuyun).
  2. If it isworldDocument orhtmlFormat to convert tomdFormat is ok.
  3. Looking for a fewworldTools for converting documents to MD format are not easy to use, especially if the original document has images.

The difference between

  1. GitBookThe configuration cost is small, can be locally edited, then directly deployed;GitBookThere’s also an online editor, but the content has to existGitBookOn the server.
  2. VuePressIs slightly more expensive to configure, but can be usedVueSyntax with components, customization a little more freedom, andVuePressIn the writingVueAs usual, learning costs almost nothing, can be edited locally with VsCode, and then deployed directly from the command line.

conclusion

  1. With amarkdownGrammar to write articles,markdownJust a few common syntax, very easy to use.
  2. GitBook is recommended for non-technical people, and VuePress is recommended for technical people, especially front-end technicians.
  3. Personally preferVuePress 。

4. Project source code

The complete sample code for VuePress and GitBook builds in this article has been uploaded to GitHub and can be downloaded to use.

Just change some of the configuration information to your own, such as repository, Client ID && Client Secret, author, etc.

Source code address: github.com/biaochenxuy… .

Examples of VuePress and GitBook are in blog-gitbook and blog-vuepress.

The result of this requirement

What makes the author vomit blood is: it took three days to do the research, but the leader returned to wordpress instead of 😭.

For non-technical people, the cost of learning 😂 is relatively high, such as markdown syntax, IDE editor, basic packaging commands, and possibly Git. For non-technical people, WPS 😂 is generally used when editing documents.

More gratified is: after the author finished the research, their own blog website can also be used, haha.

The last

How to find great open source projects is a trick that most people don’t know, even senior engineers don’t know.

Reference article: Add GitTalk comments to your VuePress blog