✍️ 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?

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

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="/docs/document-write-guide"></include-block>

Props

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

How to run the site locally

  1. Set up your development environment.
  2. Write the full content in any editor that supports Markdown. e.g. VSCode, Typora, or Notion.
  3. Run pnpm dev start the review server.
  4. Go to localhost:3000/docs and check your creation.
  5. If everything looks fine, submit a PR with the changes to our repo in GitHub.

How to add a new page

  1. Add your .md file to the folder /content/docs/xxx.
  2. Add your images to the folder /static/docs/xxx.
  3. Add an entry for the document in _layout.md, under the proper section.
  4. Submit a PR with the changes to our repo in GitHub.