Re: Re: Re: [discussion] To introduce a formatter for Markdown files
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 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 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
> 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
> > > > >
> > > >
> > >
> >
>
RE: Re: Re: [discussion] To introduce a formatter for Markdown files
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 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 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
> > > >
> > >
> >
>
Re: Re: [discussion] To introduce a formatter for Markdown files
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 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 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 > > > > > >
RE: Re: [discussion] To introduce a formatter for Markdown files
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 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 > > >
RE: Re: [discussion] To introduce a formatter for Markdown files
> I was wondering how we could let every contributor follow the same mk rule. 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. > Is there any way to integrate the format check into our CI pipeline? Yes, it is possible. I have tested using GitHub Actions, and I think Azure pipelines also support this feature. ```yml jobs: Check-MD-Format-Actions: runs-on: ubuntu-latest steps: - name: Check out repo code uses: actions/checkout@v3 - name: Prettify code uses: creyD/prettier_action@v4.2 with: prettier_options: --check **/*.md ``` > Another thing is that some docs are written with Hugo syntax. Would they work together with no conflict? Well, it will never cause any conflict. Since Hugo syntax is a superset of regular markdown syntax, and 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 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 > > >
