Practical Guide – Quickly build documentation sites

The background,

Requirements are productivity. Documentation for regular projects is mostly recorded and documented under readme.markdown, but for externally enabled projects, an open documentation system is essential.

The following is a standard online documentation system interface for reference:

Two, technology selection

First, clarify the requirements of building an online documentation system:

• Built-in Markdown file transfer web page
• Friendly to SEO
• React extends the web page
• The interface is beautiful
• Documentation is clear, easy to use, and easy to deploy
• Rich features, such as searchable, document versioning

In the context of the above requirements, the following technology stacks are identified for reference:

The following table data source: document website generation tool selection

Docusaurus, which is easy to use, friendly to SEO and rich in functions, was chosen to build the document system.

Three, fast construction

1. Start

1.1 New Project

Install Node and create a new Docusaurus site

npx create-docusaurus@latest my-website classic
Copy the code

1.2 Starting the Project

Local start-up project

yarn start
Copy the code

A local documentation system has been set up:

2. Directory structure

Familiar with the directory structure of Docusaurus document system, clear subsequent custom configuration and document storage location.

. ├ ─ ─ a blog// The Markdown file containing the blog│ └ ─ ─2022- 01- 13- first - blog - post. Markdown ├ ─ ─ the docs// The Markdown file containing the document│ ├── ├.markdown │ ├─ API. Markdown │ ├─ markdown │ ├─ SRC// Non-document file│ ├ ─ ─ components │ │ ├ ─ ─ HomepageFeatures. Js │ │ └ ─ ─ HomepageFeatures. The module. The CSS │ ├ ─ ─ CSS │ │ └ ─ ─ the custom. The CSS │ └ ─ ─ pages// Convert to a web page│ ├ ─ ─ index. Js │ ├ ─ ─ index. The module. The CSS │ └ ─ ─ markdown - page. Markdown ├ ─ ─ the static// Static resources│ ├─ img ├─ docusaurus.config.js// Config file└ ─ ─ sidebars. Js// Specify the order of the sidebar documents

Copy the code

3. Customize content

Once we were familiar with the directory structure, we started to customize the configuration by changing the initial document project to our own content.

3.1 Configuring Site Metadata

Include:

• title: the title
• url: Document system domain name
• baseUrl: Level-1 address under a domain name
• favicon: Site icon

Modify docusaurus. Config. Js:

const config = {
  title: 'distribute-sdk'.url: 'http://tls-pre.jd.com'.baseUrl: '/distribute-sdk-docs/'.favicon: 'img/favicon.ico'};Copy the code

3.2 Configuring the Navigation Bar

Includes the navigation bar, logo, host name, and coding address.

Modify docusaurus. Config. Js:

const config = {
  themeConfig:
    / * *@type {import('@docusaurus/preset-classic').ThemeConfig} * /
    ({
      navbar: {
        title: 'Distribute SDK'.logo: {
          alt: 'Distribute SDK Logo'.src: 'https://img11.360buyimg.com/ling/jfs/t1/103667/23/20676/2779/61d59cd2Ef2665258/239330f23ecbae81.png'.href: 'docs/',},items: [{type: 'doc'.docId: 'README'.position: 'left'.label: 'document'}, {to: '/blog'.label: 'Blog'.position: 'left' },
          {
            href: 'xx'.// git remote
            label: 'Coding'.position: 'right',},],},}),};Copy the code

3.3 Adding Documents

Creating a markdown file under the blog path will automatically generate a level 1 directory showing static web pages from markdown files under the blog, in order of title.

Create a new Markdown file under the docs path and sort it by the size of sidebar_position declared in the markdown file to automatically generate a level 1 directory. Static web page showing markdown file transfers under Docs.

The following is the effect of the document website:

Fourth, rich functions

1. Automatic deployment

Automatic deployment was realized by creating projects in the company’s internal TALOS system and configuring Webhook in coding.

There was a problem that the Node version was lower than Docusaurus required when compiling on TalOS, so the compilation process had to be carried out locally.

Github Pages and Gitee Pages are used for automatic deployment on the Internet.

2. Automatically updates the Changelog

Lerna Version provides the function of automatically updating Changelog. This document system is also a project service built for LerNA.

The following lerNA version release process is standardized, which can automatically update the Changelog page in the document system when the version is updated:

• Lerna VERSION — Straw-commits Identify the version number and automatically generate Changelog;

• NPM run Changelog Deploy the automatically generated Changelog to the document system (write a script to copy the file to the specified location).

• Lerna publish from- Git release version.

Five, the summary

This article describes the complete process of setting up a document system quickly, which is summarized as the following three points:

• Technology selection, according to the needs of the scene to choose the appropriate means to achieve the function;
• Build websites quickly through official documents;
• More functions according to requirements.

Past wonderful

• Practice Guide – Web page generation PDF

The resources

• Learn as you Write — Docusaurus is a great framework for creating web sites
• Document website generation tool selection