✍️ Document write guide
Before getting started, please make sure that you are familiar with
The structure of a document .md
file
---
title: Document write guide
description: This section shows the steps of writing a document.
---
# How to write a document?
First, you need to write down the main concept of your documentation.
To optimize documentation SEO, we should save its metadata between the --- xxx ---
block. Typically used fields are:
title
should be same as the header title;description
field should be the excerpt of the document.
Blocks
Use following components to display more styled content in documentations:
Table
Col1 | Col2 | Col3 |
---|---|---|
Bob | 30 | ✔️ |
Alice | 15 | |
David | 20 | ✔️ |
Code
A code block with copy button.
echo hello world
Hint
Show a hint text with a styled block.
I am an info block with link.
Extra description.
I am an warning block with link.
Extra description.
Usage
<HintBlock type="info">
Bytebase has already prepared some sample data. In particular, it has created a Test environment and a Prod environment, each containing a mysql instance. To establish the connection to those instances, one quick way is to [start a MySQL docker instance](#start-a-mysql-docker-instance-for-testing).
</HintBlock>
Props
Name | Type | Default | Description |
---|---|---|---|
type | info | warning | info | Set the hint style |
Doc
A pretty link block to another page.
Usage
<DocLinkBlock url="/docs/faq" title="FAQ"></DocLinkBlock>
Props
Name | Type | Default | Description |
---|---|---|---|
url | string | '' | Set the link url |
title | string | '' | Description of the link title |
Include
Include another markdown and render inline.
Usage
<IncludeBlock url="/docs/document-write-guide"></IncludeBlock>
Props
Name | Type | Default | Description |
---|---|---|---|
url | string | '' | Set the markdown file url, which should be an absolute path without the /docs prefix |
How to run the site locally
- Set up your development environment.
- Write the full content in any editor that supports Markdown. e.g. VSCode, Typora, or Notion.
- Run
pnpm dev
start the review server. - Go to localhost:3001/docs and check your creation.
- If everything looks fine, submit a PR with the changes to our repo in GitHub.
How to add a new page
- Add your .md file to the folder
/content/docs/xxx
. - Add your images to the folder
/docs/xxx
. - Add an entry for the document in
_layout.md
, under the proper section. - Submit a PR with the changes to our repo in GitHub.