Add Markdown linter

[ilyatitovich]

Fixes #97

When searching for a Markdown linter, I settled on remark. The linter has an extensive collection of plugins and presets for processing Markdown files, allowing us to check only the necessary rules. It is possible to write custom rules to perform specific tasks.

I added 4 packages:

• remark-cli: CLI linter interface
• remark-lint-no-dead-urls: plugin that checks whether links are live
• remark-validate-links: plugin that checks links to files and folders
• remark-lint-code-block-style: plugin that checks code blocks and can format the file if necessary. To format files during linting, you need to add --output to the script: "test:markdown": "remark . --output".

We may also need the remark-toc plugin, which allows us to generate TOC for *.md files.

Additionally, a .remarkrc.js file has been added, in which the necessary plugins are connected.

Using this linter, we can check whether links in a document are alive. For other tasks we need to write our own rules.

If this linter suits us, then I’ll start to work with GitHub Actions to add .github/workflows/docs.yml to run linter on */.md files changes.

And I'm a little confused by the task: Find way to avoid calling in .github/workflows/root.yml, because I don't see this file in the workflows directory.

Motivation

Add to the project a good, flexible linter for checking *.md files for mistakes.

Checklist

• [x] Don’t rush. Check all changes in PR again.
• [x] Think about changing documentation.
  • If you added a script to scripts/, add a comment with a description.
  • If you added a new folder, add its description to the project’s README.md.
  • If you added config, describe how we use this tool in the config’s comment.
  • If you added something to the project’s architecture, describe it in the project’s README.md.
  • Try to focus on “why?”, not “how?”.
• [x] If you added a new dependency, check our requirements.
• [ ] Think about testing
  • If you added a feature, add unit tests.
  • If you added a new state to the UI, add visual tests.
  • If you fixed the bug, think about preventing bug regression in the future.
• If you changed web client:
  • [ ] Think about moving code to core/. What code will also be useful on other platforms?
  • [ ] Run pnpm size and check the difference in the JS bundle size. Is it relevant to the changes? Change the limit in web/.size-limit.json if necessary.
  • [ ] Think about keyboard UX. Is it easy to use the new feature with only one hand on a keyboard? Is it easy to understand what keys to press?
  • [ ] Think about HTML semantics.
  • [ ] Think about accessibility. Check a11y recommendations. Think about how screen reader users will use the tool. Is it easy to use on a screen with bad contrast?
  • [ ] Think about translations. Will
  • [ ] Think about right-to-left languages. What parts of the screen should be mirrored for Arabic or Hebrew languages?
• If you changed the colors token in the web client:
  • [ ] Think about app loading styles inlined in index.html.
• If you changed core/:
  • [ ] Think about making types more precise. Can you better explain data relations by type?
  • [ ] Think about conflict resolution. We don’t need some very smart changing merging; just 2 changes of the same item on different clients should not break the database. What if the user changes an item on one machine and removes it on another?
  • [ ] Think about log and storage migration.
• If you changed English translations:
  • [ ] Change translation ID if you change the meaning of the text.

[ai]

We may also need the remark-toc plugin, which allows us to generate TOC for *.md files.

We may need to write custom rule here too, since we need not generate TOC but to test current TOC (i am not sure how this plugin works to be honest, maybe it checks).

And I'm a little confused by the task: Find way to avoid calling in .github/workflows/root.yml, because I don't see this file in the workflows directory.

Oops. I renamed this file to test.yml since I created an issue.

Here is a problem. We run test.yml on non-md changes because it runs a lot of expensive test (like staging deploy).

We need to keep separation between “just test docs quickly on spellchecking PR” and “change a code”. But test.yml now runs all tests which started from test:. So we need to change test.yml to not run test:markdown (but run it on pnpm test which should test everything).

[ilyatitovich]

In order to exclude the running of the "test:markdown" script from GitHub Actions, I suggest adding the grep -v "test:markdown" filter. It will skip and run all scripts starting with "test:" except "test:markdown".

Added docs.yml file to run tests specifically for .md files.

I removed the remark-lint-code-block-style package, because it really doesn’t do what we need. I have not yet discovered a plugin that checks indentation inside a list element.

Added --frail to the script: "test:markdown": "remark . --frail". Now linter displays a warning and returns an error:

Added the remark tool to the Tools section in README.md.

[ilyatitovich]

Updated the docs.yml file, adding PR bypass and standard installation of the environment and packages.

Updated the script in the test.yml file for running tests by adding the regular expression '/^test:(?!markdown\b)/'. It will allow us to run all tests except the "test:markdown". Checked locally - it works.

[ai]

1. When you will fix issues, press Resolve conversation
2. We need also to resolve conflicts

But I think it is the last code review. We are very close to merging.

[ilyatitovich]

Corrected logical mistakes in docs.yml. Resolved conflicts.

Interesting task! I learned a lot of new things :)

[ai]

Thanks! I created an issue for next step https://github.com/hplush/slowreader/issues/140