docs-next

The next generation of documentation for HStreamDB.

Table of Contents

• Development
  • Normal markdown files
  • index.md
  • _index.md
  • About sidebar
  • Special markdown syntaxes
• Release a new version

Development

We use pnpm as our package manager. Run following commands to install dependencies and start the development server in your local environment.

pnpm install
pnpm run dev

The rest of the time after that you will most likely be editing the following files:

• Normal markdown files
• index.md
• _index.md

We'll talk about what these files do later.

Normal markdown files

Normal markdown files are just markdown files that are not index.md or _index.md. They are rendered as a single doc page based on the file structure of the docs folder.

index.md

index.md is a special file that is used to represent a separate directory page. This means that when you click on the group in the sidebar, it won't expand or collapse the group by default, but will display the contents of index.md instead.

_index.md

_index.md is a special file that is used to generate the sidebar. It contains the metadata of the group and must exist.

Currently, it supports the following metadata:

---
title: <title>
order: <order>
collapsed: <collapsed:true|false>
---

<title>

• <title> is the name of the group. If it is not present, the group name will be rendered as the folder name.

  The priority of <title> in the front matter is higher than the <title> in the content (all of the content will also be treated as the group name).

  For example, if you write title: User Guides or the content of docs/guides/_index.md is User Guides, so the group guides will be rendered as User Guides in the sidebar.

• <collapsed> is used to control whether the group is collapsed by default. If it is not present, the group will be collapsed by default.

• <order> is used to generate the sidebar. It's a array of strings to specify the order of the items in a group. Every string in the array can be a file name or a folder name.

  Below is an example of the order field:

  order:
    [
      'overview',
      'start',
      'write',
      'receive',
      'process',
      'ingest-and-distribute',
      'deploy',
      'security',
      'reference',
      'release-notes.md',
    ]

  So the group will be rendered as:

  • overview
  • start
  • write
  • receive
  • process
  • ingest-and-distribute
  • deploy
  • security
  • reference
  • release-notes.md

About sidebar

The sidebar is generated base on the file structure of the docs folder automatically. It is generated by the following rules:

• Files in docs/ except files in v* and zh subfolders will be generated as the en latest version sidebar.
• Files in docs/zh except files in v* subfolders will be generated as the zh latest version sidebar.
• Files in docs/v* will be generated as the en v* sidebar.
• Files in docs/zh/v* will be generated as the zh v* sidebar.

Even though the rules are a little complicated, you don't need to worry about it. Once a version is released, the sidebar will be generated automatically.

Special markdown syntaxes

{{ $version() }}

{{ $version() }} is a special syntax that is used to display the current version of the docs. It will be replaced with the current version when the docs are built. For example:

It's important to keep in mind that when using vue-style interpolation in code blocks, you should add a suffix of -vue to the language, such as shell-vue.

Input:

docker pull hstreamdb/hstream:{{ $version() }}

Output:

docker pull hstreamdb/hstream:v0.15.0

Release a new version

To release a new version, all you need to do is create a new tag in the format of v*.*.*. For example, to release a new version v1.0.0, you can run:

git tag v1.0.0

And then push the tag to the remote repository:

git push origin v1.0.0

Then the CI will automatically open a PR to check out the new version from the latest docs.