I agree with using Docusaurus warnings to sort and replace all existing plain text comments.
Also is it possible to make the links[1] more prominent or higher in the README file of APISIX ？ [1] https://apisix.apache.org/docs/apisix/getting-started/ Best Regards Yilin Zeng <yzen...@wisc.edu.invalid> 于2021年8月3日周二 上午11:04写道： > Hi Community, > > As more and more users are using Apache APISIX, documents are getting more > important. A community user pointed out that the notes in Apache APISIX > documents were not unified, it is inconvenient for those who prefer to read > documents directly from GitHub repository. > > Notes in Apache APISIX documents are split into two groups: one is written > in plain text, such as ’note’ or ’Note’; the other is written in Docusaurus > structure, such as ‘:::note’ and ends with ‘:::’. > > The first group of notes in plain text is somewhat ambiguous (i.e. it > could be a note, an info, a tip, a caution, or a warning). In addition, > plain text is easy to be ignored or skipped. For example, note under > ‘Attributes’ chart > https://apisix.apache.org/docs/apisix/plugins/serverless#attributes. > > The second group of notes (:::note :::) takes advantages of Docusaurus > admonitions, makes it more noticeable on Apache APISIX document website. > For example, note under ‘Prerequisites’ section in ‘Getting Started’ > document: > https://apisix.apache.org/docs/apisix/getting-started/#pre-requisites. > > Furthermore, Docusaurus supports 5 sorts of admonitions: note, tip, info, > caution and danger, which is an ideal solution for the problem of > ambiguity. For more details, Docusaurus provides usages of admonitions on > its official website: > https://docusaurus.io/docs/next/markdown-features/admonitions. > > While the second group of notes enhances user experience when reading from > the Apache APISIX document website, it also creates inconvenience for those > who are reading directly from GitHub repository. Since Docusaurus > admonitions is not able to show up as expected in GitHub repository, as > shown in here: > https://github.com/apache/apisix/blob/master/docs/en/latest/getting-started.md#pre-requisites, > some might recognize it as typo and create an issue or pull request trying > to fix it. > > Unfortunately, there is no perfect solution to satisfy both website > readers and GitHub readers. > > I took a look at other open-source projects’ documents, including Zilliz, > TiDB and Rancher, none similar case was reported in their pull requests or > issues. It seems like reading directly from GitHub repository is a rare > case. > > As far as I am concerned, community users are encouraged to read from > Apache APISIX document website first. When a problem is found in documents, > community users can then actually dig into Apache APISIX GitHub repository > to either file an issue, or submit a pull request to fix the problem. > > My proposal is to sort and replace all existing plain text notes with > Docusaurus admonitions (i.e. note, tip, info, caution and danger) to make > it more noticeable on document website, since documents under the Apache > APISIX repository served as data source for Apache APISIX website, and we > expect community users to visit and read the documents from Apache APISIX > website rather than GitHub repository. > > What's your opinion? If you have better solutions, please don’t hesitate > to speak up. Thanks! > > Regards, > Yilin Zeng >
