✍️ Document write guide
Before getting started, please make sure that you are familiar with the basic Markdown syntax.
The structure of a document
--- 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:
titleshould be same as the header title;
descriptionfield should be the excerpt of the document.
Use following components to display more styled content in documentations:
A code block with copy button.
echo hello world
Show a hint text with a styled block.
I am an info block with link.
I am an warning block with link.
<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>
|type||Set the hint style|
A pretty link block to another page.
<doc-link-block url="/docs/faq" title="FAQ"></doc-link-block>
|url||Set the link url|
|title||Description of the link title|
Include another markdown and render inline.
|url||Set the markdown file url, which should be an absolute path without the |
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.
pnpm devstart the review server.
- Go to localhost:3000/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
- Add your images to the folder
- Add an entry for the document in
_layout.md, under the proper section.
- Submit a PR with the changes to our repo in GitHub.