Hi Zhongpu, Thanks for sharing. That sounds good to me. Once we get consensus in the community, please don't forget to update the content at [1] wrt mk guide and format guide.
Best regards, Jing On Thu, Feb 23, 2023 at 4:54 AM Zhongpu Chen <chenlov...@gmail.com> wrote: > Hi Jing, > > Prettier is a versatile formatting tools with very limited options for > markdown files. If we need to specify the rules, I think other tools, > such as markdownlint [1], can be a better choice. As for markdownlint, > we can specify many kinds of rules. Here is an example for `unordered > list` whose style ID is MD004 [2]. > > ```json > > { "default": true, "MD004": { "style": "asterisk" } } > > ``` > > Then markdown files only accept '*' for making a list item. > > The specific formatting tools may be left as a vote later. > > [1] https://github.com/DavidAnson/markdownlint > > [2] https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md > > > On 2023/02/22 21:22:02 Jing Ge wrote: > > Hi Zhongpu, > > > > Thanks for the clarification. Prettier looks fine for formatting mk > files. > > Is there any way to validate rules like e.g. only using '*' for listing > > items in the CI pipeline? > > > > Best regards, > > Jing > > > > On Wed, Feb 22, 2023 at 2:28 PM Zhongpu Chen <ch...@gmail.com> wrote: > > > > > Hi Jing, > > > > > > Sorry for the last reply in a messed up formatting, as I am not quite > > > familiar with the mail list usage. > > > > > > First, as long as contributors install Prettier with the same version, > > > markdown files can be auto-formatted in the same way without extra > working > > > via the `prettier --write **/*.md` command, and this can also be > set as a > > > part of pre-commit hook. To check whether markdown files satisfy > formatting > > > requirements, we can use `prettier --check **/*.md` where exit code > 0 means > > > it does follow the styles. > > > > > > Secondly, the format check can be integrated with the CI pipeline > easily. > > > Here is an example using GitHub Actions, and I think the setting in > Azure > > > pipelines is similar. > > > > > > ```yml > > > jobs: > > > Check-MD-Format-Actions: > > > runs-on: ubuntu-latest > > > steps: > > > - name: Check out repo code > > > uses: actions/checkout@v3 > > > - name: Use Node.js > > > uses: actions/setup-node@v3 > > > with: > > > node-version: "12.x" > > > - name: Install pretty > > > run: npm i -g prettier > > > - name: Prettify code > > > run: prettier --check **/*.md > > > ``` > > > > > > At last, it will never cause any conflict. Prettier is compatible with > > > CommonMark (https://commonmark.org/) and GitHub Flavored Markdown. > > > > > > > > > On 2023/02/22 10:22:46 Jing Ge wrote: > > > > Hi Zhongpu, > > > > > > > > Thanks for starting this discussion. I was wondering how we could > let > > > every > > > > contributor follow the same mk rule. I am not familiar with > Prettier. > > > Would > > > > you like to help me understand some basic questions? Thanks. > > > > > > > > Is there any way to integrate the format check into our CI pipeline? > > > > Otherwise, it will be hard to control it. Another thing is that > some docs > > > > are written with Hugo syntax [1]. Would they work together with no > > > conflict? > > > > > > > > > > > > Best regards, > > > > Jing > > > > > > > > [1] https://gohugo.io/ > > > > > > > > On Wed, Feb 22, 2023 at 9:50 AM Zhongpu Chen <ch...@gmail.com> > wrote: > > > > > > > > > As I mentioned in FLINK-31177 ( > > > > > https://issues.apache.org/jira/browse/FLINK-31177): > > > > > > > > > > Currently, markdown files in *docs* are maintained and updated > by many > > > > > contributors, and different people have varying code style > taste. By > > > the > > > > > way, as the syntax of markdown is not really strict, the styles > tend to > > > be > > > > > inconsistent. > > > > > > > > > > To name a few, > > > > > > > > > > - Some prefer `*` to make a list item, while others may prefer > `-`. > > > > > - It is common to leave many unnecessary blank lines and spaces. > > > > > - To make a divider, the number of `-` can be varying. > > > > > > > > > > To this end, I think it would be nicer to encourage or demand > > > contributors > > > > > to format their markdown files before making a pull request. > > > Personally, I > > > > > think Prettier (https://prettier.io/) is a good candidate. > > > > > What do you think? > > > > > > > > > > -- > > > > > Zhongpu Chen > > > > > > > > > > > > > > >