https://github.com/hstreamdb/docs-next
The next generation of documentation for HStreamDB.
https://github.com/hstreamdb/docs-next
Last synced: about 1 year ago
JSON representation
The next generation of documentation for HStreamDB.
- Host: GitHub
- URL: https://github.com/hstreamdb/docs-next
- Owner: hstreamdb
- Created: 2023-04-14T10:35:36.000Z (about 3 years ago)
- Default Branch: main
- Last Pushed: 2024-05-29T09:12:36.000Z (about 2 years ago)
- Last Synced: 2025-03-15T00:51:13.095Z (over 1 year ago)
- Language: Python
- Homepage: https://docs.hstream.io
- Size: 2.62 MB
- Stars: 1
- Watchers: 2
- Forks: 6
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Security: docs/security/_index.md
Awesome Lists containing this project
README
# docs-next
The next generation of documentation for HStreamDB.
## Table of Contents
- [Development](#development)
- [Normal markdown files](#normal-markdown-files)
- [`index.md`](#indexmd)
- [\_index.md](#_indexmd)
- [About sidebar](#about-sidebar)
- [Special markdown syntaxes](#special-markdown-syntaxes)
- [Release a new version](#release-a-new-version)
## Development
We use [pnpm](https://pnpm.io/) as our package manager. Run following commands to install dependencies and start the development server in your local environment.
```bash
pnpm install
pnpm run dev
```
The rest of the time after that you will most likely be editing the following files:
- [Normal markdown files](#normal-markdown-files)
- [`index.md`](#indexmd)
- [`_index.md`](#_indexmd)
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](#about-sidebar). It contains the metadata of the group and **must exist**.
Currently, it supports the following metadata:
```markdown
---
title:
order:
collapsed:
---
```
- `` is the name of the group. If it is not present, the group name will be rendered as the folder name.
> The priority of `` in the front matter is higher than the `` 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.
- `` is used to control whether the group is collapsed by default. If it is not present, the group will be collapsed by default.
- `` is used to generate the [sidebar](#about-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:
```yaml
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](#release-a-new-version), 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:
```sh
docker pull hstreamdb/hstream:{{ $version() }}
```
Output:
```sh
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:
```bash
git tag v1.0.0
```
And then push the tag to the remote repository:
```bash
git push origin v1.0.0
```
Then the CI will automatically open a PR to check out the new version from the latest docs.