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

<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#

Doc#

A pretty link block to another page.

Usage#

<DocLinkBlock url="/docs/faq" title="FAQ"></DocLinkBlock>

Props#

Include#

Include another markdown and render inline.

Usage#

<IncludeBlock url="/docs/document-write-guide"></IncludeBlock>

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:3001/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 /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.