search

pingcap / tidb-dev-guide

A comprehensive development guide to help you be more and more familiar with the TiDB community and become an expert finally.
https://pingcap.github.io/tidb-dev-guide/
117 stars 62 forks source link

migrate from mdbook to docusaurus #166

Open zhangyangyu opened 3 years ago

zhangyangyu commented 3 years ago

Currently the dev guide uses mdbook. But from my reading experience there are two problems: 1. the theme makes me feel bored and tired quickly, lacking color contrast; 2. no ToC (this is not supported by mdbook builtin). I'd like to propose docusaurus as the doc system. It could solve the two problems and it's actively maintained. There are already many sites hosted by it.

A preliminary try is like:

image

But due to the lack of category index page, we might need to wait several days still. Although I think the category pages of contribute to TiDB and get started are somehow redundant but the page of understand TiDB is valuable.

tisonkun commented 3 years ago

@zhangyangyu thanks for starting this thread!

Could you also add a link to the sample page? Although I agree that mdBook is lack of smooth TOC as well as font / color configuration, there are too many doc / blog systems to try out. I'd like to prevent we just move from one to the other but later figure out new problems.

zhangyangyu commented 3 years ago

The try is a local site. But it uses the default theme of docusaurus so it should be nothing different from the docusaurus tutorial. Yes, too many doc/blog systems. Actually docusaurus gives its subjective comparisons with other popular systems. docusaurus is not a must for me. I just think its out-of-box installation could solve mdbook's problems and it's actively maintained.