본문으로 건너뛰기
버전: dev

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 pnpm install to install the required dependent libraries.
  4. In home directory run pnpm start, you can visit http://localhost:3000 to view the English mode preview of the site
  5. In home directory run pnpm 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 pnpm 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

Writing a blog post​

A post lives in blog/ and, when translated, in i18n/<locale>/docusaurus-plugin-content-blog/ under the same file name.

---
title: Announcement of Apache HertzBeat™ 1.8.0 Release
author: Apache HertzBeat Community
author_url: https://github.com/apache/hertzbeat
tags: [releases]
description: Apache HertzBeat 1.8.0 introduces AI chat and MCP tooling, log monitoring, and major performance improvements.
cover_headline: Apache HertzBeat 1.8.0
---
  • tags — start with exactly one category from blog/tags.yml (releases, engineering, tutorials, community). It drives the category filter on the blog list page. Add free-form topic tags after it if useful.
  • description — one or two sentences. It becomes the card summary and the search-engine snippet. Without it Docusaurus falls back to the first block of the post, which is usually a greeting or a heading.
  • cover_headline — optional. The blog list renders a cover for every post in the site's visual style; this sets the big line of text on it (e.g. Welcome Bob). Without it the text is derived from the version or monitored product found in the title.
  • cover_kicker — optional. The small pill badge on the generated cover (e.g. New Committer). Defaults to the category name. Cover text is English on every locale, matching the shared visual style.
  • image — optional. A real cover image; when set it replaces the generated cover entirely.

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