Documentation Notice

Good documentation is critical for any type of software. Any contribution that can improve the HertzBeat documentation is welcome.

Get the document project

Documentation for the HertzBeat project is maintained in git repository home directory.

First you need to fork the document project into your own github repository, and then clone the document to your local computer.

git clone git@github.com:<your-github-user-name>/hertzbeat.git

Preview and generate static files

This website is compiled using node, using Docusaurus framework components

1. Download and install nodejs (version 18.8.0)
2. Clone the code to the local git clone git@github.com:apache/hertzbeat.git
3. In home directory run npm install to install the required dependent libraries.
4. In home directory run npm run start, you can visit http://localhost:3000 to view the English mode preview of the site
5. In home directory run npm run start-zh-cn, you can visit http://localhost:3000 to view the Chinese mode preview of the site
6. To generate static website resource files, run npm run build. The static resources of the build are in the build directory.

Document Format Inspection

In Apache HertzBeat, all MD articles have to pass MD's CI inspection before they can be merged. The purpose is to keep the website looking nice and the formatting of the articles consistent.

After you have written an MD article, you can execute the following command locally to check whether the content of the MD article meets the requirements, so as to reduce the workload of review and save your time:

cd home && pnpm install

pnpm md-lint

# If the documentation is wrong, you can use pnpm md-lint-fix to fix it.
pnpm md-lint-fix

For formatting rules for MD articles you can refer to: Markdown-lint-rules MD format configuration file in the project: .markdownlint-cli2.jsonc

Directory structure

|-- docs
|-- blog   
|-- i18n
|   `-- zh-CN  // internationalized chinese
|       |-- code.json
|       |-- docusaurus-plugin-content-blog
|       |-- docusaurus-plugin-content-docs
|       `-- docusaurus-theme-classic
|-- resource  // static resource file
|-- src
|   |-- theme
|   |-- css
|   |-- js
|   |-- pages
|   |   |-- components
|   |   |-- index.js
|   |-- constants.js
|-- static // picture static resource
|   |-- img  //
|   |   |-- blog // blog picture
|   |   |-- docs // document picture
|   |   |-- home // product picture
|   |   |-- icons // icon
|-- docusaurus.config.js
|-- sidebars.js // document sidebar menu configuration

Specification

Naming convention of files

Consist entirely of lowercase letters, numbers, underscores, and dashes.

Positive example: render-dom.js / signup.css / index.html / company-logo.png / hertz_beat.md

Counter example: renderDom.js / UserManagement.html

Resource Path

Image resources are unified under static/img/{module name}

css and other style files are placed in the src/css directory

Page content modification

All pages doc can be directly jumped to the corresponding github resource modification page through the 'Edit this page' button at the bottom