✍️ Document write guide

Before getting started, please make sure that you are familiar with

• Basic Markdown Syntax
• Bytebase Technical Writing Style Guide

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

Code

A code block with copy button.

echo hello world

Hint

Show a hint text with a styled block.

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

Doc

A pretty link block to another page.

Usage

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

Props

Include

Include another markdown and render inline.

Usage

<include-block url="/docs/document-write-guide"></include-block>

Props

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.