At the forefront of

I believe many people have this experience, a project written, especially a component library, you do not have a documentation, who can understand? So a good project, must have an easy to understand documentation. Of course, the Github page allows you to quickly generate simple documentation during the years of Markdown, but it’s still a good idea to write in a readme.md. If a project or component is large enough, it can’t be all in one file. Even if you write it carefully, honestly, no one wants to read it.

The cause of

For those of you who have worked on the front end, the Element UI is no stranger, and the component library is quite nice and easy to get started with. Why is that? Because he had a well-documented, easy-to-understand document.

start

I came to know about Docsify by chance. After a day’s exploration, I felt it was necessary to write something to prevent myself from looking up something in the future.

Install docsify
npm i docsify-cli -g
Copy the code
Initialize the

Initialization must go to the project root directory, of course, if you are like me and write documents only for the purpose of writing a document, create a new empty folder. However, I want to make it a little more complicated here, because we don’t always write documents for ourselves, we always put them on Github for more people to see. So let’s start by creating an empty Github library. Of course, I’m not going to bother you with the process, but you can create it yourself. Clone the RepO locally once it is created.

docsify init ./docs
Copy the code

A new docs directory is generated in the current directory.

index.html 

docsify serve docs
Copy the code

Open your browser again: http://localhost:3000 and you’ll see an initialized page.

Of course, you might think this is a long list of instructions to remember, so let’s do a simple one.

Open package.json and add one to your script. If not, add NPM init -y

"doc": 'docsify serve docs'
Copy the code

NPM run doc directly from now on. At this point, a simple document model emerges. Let’s focus on its configuration:

configuration

Too simple configuration is not tired to describe, give an address, we click into their own docsify, next focus on the following configuration items.

loadSidebar

Set this parameter to true and it will automatically load the _navbar.md file in the specified path. To do this, we’ll create _navbar.md under the./docs directory. This way, we can customize our sidebar in this file.

window.$docsify = {
  / / load _navbar. Md
  loadSidebar: true./ / load the nav. Md
  loadSidebar: 'summary.md'
};
Copy the code

setup.md

The plug-in

copy to clipboard

Add the following js to the bottom of index.html.

<script src="//unpkg.com/docsify-copy-code"></script>
Copy the code

README.md

There are a few other plug-ins that are relatively simple to configure, but here’s a slightly more verbose one.

Gittalk

Github Issue is a comment plugin based on Github Issue and Preact. Here’s how to use it!

<link rel="stylesheet" href="//unpkg.com/gitalk/dist/gitalk.css">

<script src="//unpkg.com/docsify/lib/plugins/gitalk.min.js"></script>
<script src="//unpkg.com/gitalk/dist/gitalk.min.js"></script>
<script>
  const gitalk = new Gitalk({
    clientID: 'Github Application Client ID',
    clientSecret: 'Github Application Client Secret',
    repo: 'Github repo',
    owner: 'Github repo owner',
    admin: ['Github repo collaborators, only these guys can initialize github issues'].// facebook-like distraction free mode
    distractionFreeMode: false
  })
</script>
Copy the code

The configuration files are the ones above, but there are a few more things we need to fill in ourselves. Github Application configuration. Nonsense not to say, open github.com/settings/de…


      
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Document</title>
  <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />
  <meta name="description" content="Description">
  <meta name="viewport" content="Width =device-width, user-scalable=no, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0">
  <link rel="stylesheet" href="//unpkg.com/docsify/lib/themes/vue.css">
  <link rel="stylesheet" href="//unpkg.com/gitalk/dist/gitalk.css">
</head>
<body>
  <div id="app"></div>
  <script>
    window.$docsify = {
      name: ' '.themeColor: '#19BE6B'.repo: ' '.loadSidebar: true
    }
  </script>
  <script src="//unpkg.com/docsify/lib/docsify.min.js"></script>
  <script src="//unpkg.com/docsify-copy-code"></script>
  <script src="//unpkg.com/docsify/lib/plugins/gitalk.min.js"></script>
  <script src="//unpkg.com/gitalk/dist/gitalk.min.js"></script>
  <script>
    const gitalk = new Gitalk({
      clientID: '9b4355e11242485017da',
      clientSecret: 'fe82f322d0571768a6bf838b515105318397e274',
      repo: 'docsify-starter',
      owner: 'swimly',
      admin: ['swimly'].// facebook-like distraction free mode
      distractionFreeMode: true
    })
  </script>
</body>
</html>

Copy the code

The final configuration of index.html is basically like this, declaring that the clientID and clientSecret I have here are wrong, do not copy directly!

Finally, a little picture to appreciate the fruits of labor!

A basic document is now complete, and the next step is to improve the document!

Deployment to making

We have created github, so we can submit it to the master branch of Github. This is not the end, how to synchronize to Github, how to let others see the key is the last step, we open the original github project, switch to Setting

master branch /docs folder

Some links

Doc address making

Thank you for browsing, welcome to leave a message, discuss together!