Added linter/formatter for markdown files; Formatted documentation

[alexandrtovmach]

Short story

This PR contain configured remark-lint with remark-preset-lint-gatsby and formatted documentation.

Long story

After translation process initiated, I started looking for some linter for docs. We already have a prettier, so I thought:

"Let's find linter for linting and use prettier for formatting"

I made a big research, and find few good linters:

• https://github.com/DavidAnson/markdownlint
• https://github.com/textlint/textlint
• https://github.com/remarkjs/remark

Then I started playing with configaration, but faced with blocker just in a few hours. This blocker is "formatting ordered list marker values to one stardard". That's awful, but just a first document in Gatsby tutorial can't be formatted in a good way:

Example: docs/tutorial/index.md

## Gatsby fundamentals

0.  [Set up your development environment](/tutorial/part-zero/): We'll introduce you to core technologies that power Gatsby, and guide you through setting up your development environment.
1.  [Get to know Gatsby building blocks](/tutorial/part-one/): Starting new projects, developing, and deploying sites.
1.  [Introduction to using CSS in Gatsby](/tutorial/part-two/): Explore libraries like Typography.js and CSS Modules.
1.  [Building nested layouts in Gatsby](/tutorial/part-three/): Layouts are sections of your site that are reused across multiple pages like headers and footers.

## Intermediate tutorials

In these intermediate tutorials, you'll learn how to pull data from almost anywhere into your Gatsby site with GraphQL.

4.  [Querying for data in a blog](/tutorial/part-four/): Create a blog and use a GraphQL query to pull your site title into the blog header.
5.  [Source plugins and rendering queried data](/tutorial/part-five/): Use a source plugin to pull Markdown blog posts into your site and create an index page with a list of blog posts.
6.  [Transformer plugins](/tutorial/part-six/): Use a transformer plugin to transform your Markdown blog posts into a form the blog can render.
7.  [Programmatically create pages from data](/tutorial/part-seven/): Learn how to programmatically create a set of pages for your blog posts.
8.  [Preparing a site to go live](/tutorial/part-eight/): Learn how to audit your site for performance and best practices for accessibility, SEO, and more.

The problem is first ol(ordered list) starting with 0, and next values is 1, but for a second ol start value is 4. That mess of styles, and by good approach should be standartized to one style...

I asked Google ― "how to configure prettier for ordered list". But no response...

Okay, I cloned prettier reviewed codebase, discovered that it's based on https://github.com/remarkjs/remark, mentioned above, but didn't find solution for my question. Then I spend a bit more time and implemented functionality that I needed, made PR...

It's rejected by their philosophy

What's next?

After changing my mental model, understanding that's prettier won't help me, and I need to looking for something else, I decided to use remark.

Why remark?

Because it can lint, format, has CLI and sponsored by Gatsby

Firstly I created preset of rules for Gatsby:
https://github.com/alexandrtovmach/remark-preset-lint-gatsby

Then installed and configured remark into https://github.com/gatsbyjs/gatsby project

And fixed all linter warnings (400 files changed)

For what we need this linter?

standard markdown format in original repo -> autotests for new content -> reducing count of problems with translation merges

Does it final version?

Of course, it's not!
I just initialized the process and hope to have feedback and help from community to complete this part.

[pieh]

Does remark has autofix support? Looking just on package.json changes I saw that you added lint:docs script, but no equivalent for formatting scripts.

[alexandrtovmach]

@pieh Yes remark provide autofix functionality. Added npm-script here b6a5488

[alexandrtovmach]

@gatsbyjs/gatsby-deploy @gatsbyjs/core friendly ping

[tesseralis]

What sort of rules do you want to enforce with Remark that Prettier doesn't already auto-format? I feel like configuring Prettier to work in the translation repos (as done here) would be the better option.

[muescha]

which setting changes an list from 1 space to 3 spaces?
i know it only with 1 space

My List:

- - word
-   - word
+ -   word
+     -   word

[alexandrtovmach]

@tesseralis I explained in a long description one case related to ordered list. Here is a full list that I noted
prettier can't:

• force one style for everything in a whole project. Instead of that it's formatting each block separately. As result, we get different styles (for example list markers, order, emphasis/bold symbols) in each file
• test files without formatting, like a linter
• be extended with different rules to strictify docs as we want. Remark can do that, just check the list of rules of remark-preset-lint-gatsby.

With prettier we haven't any control and strict rules about how markdown should look

[muescha]

can it changed to have only one space after the -?

[MichaelDeBoey]

Prettier will always format lists, emphasis/bold symbols, ... the same (see Markdown Playground)

[muescha]

I tried the playground and it changes all lists there to a one space list even if there are 3 space lists are in the source

+   List 3 spaces

+ List 1 space
+  List 2 spaces

Becomes:

- List 3 spaces

- List 1 space
- List 2 spaces

But most of your diffs are going from one space to 3 spaces - that is the question: why?

[alexandrtovmach]

@muescha Sorry for long response. It seems like remark autofix from b6a5488 commit. I'll check the remark config

@MichaelDeBoey take a look on this example

[MichaelDeBoey]

@alexandrtovmach The zero-started one is a bug in Prettier I think

[alexandrtovmach]

@MichaelDeBoey prettier based on remark, where this issue is coming from remarkjs/remark-lint#219

but if you check the prettier codebase you can find their custom realization:
https://github.com/prettier/prettier/blob/ce008c9593227f99edc55ee12a1349546e9a2470/src/language-markdown/printer-markdown.js#L271-L296

which are not allowed "zero" start value at all

[alexandrtovmach]

@MichaelDeBoey Another thing is forcing one style:

1. list
1. list
1. list

or

1. list
2. list
3. list

prettier cannot do that

[MichaelDeBoey]

but if you check the prettier codebase you can find their custom realization

Prettier only has 1 Markdown parser, so if they're using remark, they should update. If not they have the same bug.

Another thing is forcing one style

Maybe this can be added as a feature to prettier? 🤔
CC @vjeux @azz @evilebottnawi

[alexander-akait]

@MichaelDeBoey Can you open issue in prettier?

[alexandrtovmach]

@MichaelDeBoey I already did that prettier/prettier#6625 but it's rejected in reasons of their philosophy

[alexander-akait]

Maybe you can use remark-lint for these cases

[MichaelDeBoey]

We could indeed use prettier as the base and use remark-lint if we really want to always have an ascending number.

Issue for broken zero-based links : prettier/prettier#6813
Issue for broken double lists: prettier/prettier#6814

If those 2 issues are fixed, I think we really have everything (except for the ascending list numbers) in place what you're trying to do here @alexandrtovmach.
But I think we can still just use prettier right now, 'cause these are really edge cases we're not going to come across very often anyways.

[muescha]

it looks like it uses some default 4 spaces tab. But can be adjusted in the plugin options - see readme: https://github.com/remarkjs/remark-lint/blob/master/packages/remark-lint-list-item-indent/readme.md

[muescha]

is it possible to add bad words for better language like in #18702

[alexandrtovmach]

@muescha Yes it's possible to add this plugin https://github.com/zerok/remark-lint-write-good

[JounQin]

You can try eslint-mdx and remark-preset-prettier.