A few days ago, I sorted out the design pattern and put the documents into the warehouse: github.com/swiftdo/des… .

Recently, I found that the experience of reading MD files directly on Github was not very good. So think about htmashing the document and adding a static site to the repository.

I’ve used hexo, Vuepress, Gitbook before. However, if you use these tools for existing documents, there are some complications:

  • If hexo, Vuepress is adopted, some additional notes need to be added to the existing MD file header. There are also some upfront configurations
  • If you use a Gitbook, the style is too simple

For those who don’t want to change the source code, don’t want too much configuration, but also want to be more personal aesthetic needs, I found that there is a tool that fits. That’s docsify.

See this home page, have feel very very concise, very very beautiful. Whether you like it or not, I do.

docsify

Docsify is a document site generator. Can quickly help you generate a document site. Unlike GitBook, Hexo does not generate static.html files; all conversion is done at run time. If you want to get started, just create an index.html and start writing documentation and deploy it directly on GitHub Pages.

Github address: github.com/docsifyjs/d…

Its main features are as follows:

  • No need to build, publish directly after writing the document (markdown document conversion at runtime)
  • Easy to use and lightweight (~21kB after compression, not including the size of the Markdown document)
  • Intelligent full text search
  • Rich API
  • Emoji support, you can add emojis in the text
  • Compatible IE11
  • Support server side rendering SSR

For more details, please refer to the documentation: docsify.js.org/#/zh-cn/

I went through the official documents and successfully built the site. You can experience:

Oldbird.run /design-patt…

The overall operation is very simple, and the only problem encountered on the way is that Gitalk has some problems.

Gitalk

Gitalk is a comment plugin based on GitHub Issue and Preact.

Github address: github.com/gitalk/gita…

Gitalk features:

  • 1. Log in to GitHub
  • 2, support for multiple languages [EN, zh-CN, zh-TW, ES-ES, FR, ru]
  • 3. Support individuals or organizations
  • 4. Distraction-free mode (set distractionFreeMode to True)
  • 5, shortcuts to submit comments (CMD | CTRL + enter)

Gitalk configuration

Integration into Docsify is fairly straightforward. Fill in the following parameters:

GitHub OAuth Application

  • 1. Open the Github website, log in, click the user icon in the upper right corner, and select Settings

  • 2. On the Settings page, select the Developer Settings option.

  • 3. Select OAuth Apps in Developer Settings, and then there will be a New OAuth App button on the right of the page. Click this button to enter the New OAuth Application page.

Parameter Description of Gitalk

In https://github.com/swiftdo/design-patterns, for example:

const gitalk = new Gitalk({
      clientID: '2c899ee8d4dc774ee56f'.clientSecret: 'e69d5fcc23e6c8396a31ad3a3a011b4523a3a73e'.repo: 'design-patterns'.owner: 'swiftdo'.admin: ['OHeroJ'].distractionFreeMode: false,})Copy the code
  • ClientID: indicates the Client ID of the OAuth App
  • ClientSecret: Client Secret of the OAuth App
  • Repo: The name of the repository on Github where Gitalk comments are stored
  • Owner: Indicates the name of the Github repository owner
  • Admin: Owner and collaborator of the Github repository (user with write permission to the repository)

I’ll let you know when problems arise

All the young people, young people, young people, I'll tell you about itCopy the code

Error: Not Found. The error.

Sometimes, the URL contains links with page titles, causing the URL length to exceed 50 characters. As a result, the creation of comment issues fails.

How to solve it? Just configure the ID (which is not in the Docsify document)

const gitalk = new Gitalk({
      clientID: '2c899ee8d4dc774ee56f'.clientSecret: 'e69d5fcc23e6c8396a31ad3a3a011b4523a3a73e'.repo: 'design-patterns'.owner: 'swiftdo'.admin: ['OHeroJ'].distractionFreeMode: false.id: decodeURI(window.location.pathname),
    })
Copy the code

Although id is not a mandatory parameter, it is important:

The id parameter is used to uniquely mark the comment record and page. Sometimes, it is found that several pages have the same comment, because the id parameter is configured when these pages have the same ID. Since the id parameter defaults to the location.href page URL.

conclusion

Docsify was also the first time I used it and it was like love at first sight. It is still very important for some of my later thematic type articles (one thematic site).

Due to the first use of Docsify, some advanced features have not been used. So it’s better to take a look at the documentation.

To read more, please follow the wechat official account OldBirds