[apisix-website] branch master updated: docs: README (#1068)

[ju...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

juzhiyuan pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/apisix-website.git


The following commit(s) were added to refs/heads/master by this push:
     new 100205a9b10 docs: README (#1068)
100205a9b10 is described below

commit 100205a9b1088e943380361f3f90a91347c5a2a3
Author: Young <is...@outlook.com>
AuthorDate: Sat May 7 10:23:36 2022 +0800

    docs: README (#1068)
    
    Co-authored-by: 琚致远 <ju...@apache.org>
---
 README.md | 104 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 96 insertions(+), 8 deletions(-)

diff --git a/README.md b/README.md
index 82e678aa2c0..015a8028740 100644
--- a/README.md
+++ b/README.md
@@ -1,20 +1,108 @@
+<br>
 
-# Apache APISIX® Website
+<h1 style="position: relative" align="center">Apache APISIX® Website</h1>
 
-[<img align="right" width="150" src="./website/static/img/join-slack.png">](https://apisix.apache.org/docs/general/join)
+<div align="center">
+The website of <a href="https://github.com/apache/apisix/">Apache APISIX®</a>
 
-The website of [Apache APISIX®](https://apisix.apache.org/), a cloud-native microservices api gateway.
+A cloud-native microservices API Gateway
 
-If you want to write a blog or fix some blog-related issues, please read [Apache APISIX Blog Contributing Guide](http://apisix.apache.org/docs/general/blog) first. Then create a pull request.
+<a href="https://apisix.apache.org/docs/general/join"><img  width="150" src="./website/static/img/join-slack.png"></a>
+</div>
+
+<br>
 
 ## Usage
 
+> If you want to write a blog or fix some blog-related issues, please read [Apache APISIX Blog Contributing Guide](http://apisix.apache.org/docs/general/blog) first.
+
+### Preparation
+
+First, you need to install `Node.js`, `Yarn`, `Git`.
+
+Since the installation method may change, we recommend that you check the installation method on the corresponding official website. If you encounter any problems, please feel free to create an issue.
+
+Then you should fork this repo, and clone your fork:
+
+```bash
+# clone your fork repo
+git clone git@github.com:${your GitHub name}/apisix-website.git
+
+# add this repo as upstream
+git remote add upstream https://github.com/apache/apisix-website.git
+```
+
+### Basic
+
 ```sh
-$ cd website
+# 1. cd
+# default dir should be apisix-website
+cd apisix-website
+
+# 2. install deps
+yarn
+
+# 3. sync docs and generate repos info
+yarn sync-doc && yarn generate-repos-info
 
-$ yarn
+# 4. start dev mode
+yarn start
 
-$ yarn start
+# tip.
+# in development mode, only English site will be built
+# it's a feature of docusaurus
+# if you want to specify the locale,
+# for example, Chinese, your should run
+yarn start --locale zh
+
+# tip.
+# if you want to preview the same site as online
+yarn build && yarn serve
+```
+
+Next, you can modify the documentation or code, commit it and push it to GitHub when you're done. If you're not familiar with this, you can read [GitHub flow](https://docs.github.com/en/get-started/quickstart/github-flow) first.
+
+### Advance
+
+If you only want to modify the `*.md` files, the above guide may be sufficient.
+
+But if you need to develop, please read the guide below.
+
+#### Project Structure
+
+Omitted some documents that may not be important.
+
+```bash
+apisix-website
+├── .github
+│   └── workflows # for GitHub CI, with steps to actually build the site
+├── .husky # git hooks, currently only pre-commit is used
+├── scripts # scripts to help build the site
+└── website # docusaurus
+    ├── articles
+    ├── blog
+    ├── config # are imported in scripts and docusaurus.config.js
+    ├── docs
+    │   └── general # https://apisix.apache.org/docs/general/join
+    ├── i18n
+    │   └── zh # chinese content
+    │       ├── docusaurus-plugin-content-blog # blog
+    │       ├── docusaurus-plugin-content-docs # general
+    │       └── docusaurus-theme-classic # translations of navbar and footer
+    ├── src
+    │   ├── clientModules # docusaurus feature
+    │   ├── hooks # react hooks
+    │   ├── pages
+    │   ├── shaders
+    │   └── theme # swizzled any Docs/Blog component
+    ├── static
+    └── docusaurus.config.js
 ```
 
-Thanks to [docusaurus](https://docusaurus.io/)
+## Acknowledge
+
+Special thanks to [Docusaurus](https://docusaurus.io/).
+
+## License
+
+[Apache License 2.0](./LICENSE)