👀 Introduction toggle

✍️ Document write guide

Before getting started, please make sure that you are familiar with the basic Markdown syntax.

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?

Firstly you need to write down the main concept of your documention.

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;

How to write a new document?

  1. Write the full content in any editor that supports Markdown. e.g. VSCode/typora/notion
  2. Add the metadata block at the top of the markdown file.
  3. Add an entry for the document in _layout.md.
  4. Run pnpm dev start the review server.
  5. Go to localhost:3000/docs and check your creation.
  6. If everything is fine, create a new PR with the changes to our repo in GitHub.

Blocks

Use following components to display more styled content in documentations:

Table

Col1Col2Col3
Bob30✔️
Alice15
David20✔️

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

<hint-block 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).

</hint-block>

Props

NameTypeDefaultDescription
typeinfo | warninginfoSet the hint style

Doc

A pretty link block to another page.

Usage

<doc-link-block url="/docs/faq" title="FAQ"></doc-link-block>

Props

NameTypeDefaultDescription
urlstring''Set the link url
titlestring''Description of the link title

Include

Include another markdown and render inline.

Usage

<include-block url="features/archive"></include-block>

Props

NameTypeDefaultDescription
urlstring''Set the markdown file url, which should be an absolute path without the /docs prefix