search

open-feature / docs.openfeature.dev

OpenFeature Documentation
https://openfeature.dev
Creative Commons Attribution 4.0 International
6 stars 19 forks source link

feat: add linters #249

Closed aepfli closed 1 year ago

aepfli commented 1 year ago

This PR

Added the following linters:

Related Issues

Notes

:warning: Relies on #247

See https://github.com/aepfli/docs.openfeature.dev/actions/runs/3901207823 as an example

If this is something we would love to see, I can also fix all the errors generated by the linters

current errors by markdownlint:

blog/06-07-2022-external-posts.md:16 MD012/no-multiple-blanks Multiple consecutive blank lines [Expected: 1; Actual: 2]
blog/19-05-2022-announcing-open-feature.md:22 MD022/blanks-around-headings/blanks-around-headers Headings should be surrounded by blank lines [Expected: 1; Actual: 0; Below] [Context: "## Everybody needs an SDK"]
blog/19-05-2022-announcing-open-feature.md:31 MD022/blanks-around-headings/blanks-around-headers Headings should be surrounded by blank lines [Expected: 1; Actual: 0; Below] [Context: "## OpenTelemetry, but for feature flags"]
blog/19-05-2022-announcing-open-feature.md:42 MD022/blanks-around-headings/blanks-around-headers Headings should be surrounded by blank lines [Expected: 1; Actual: 0; Below] [Context: "## Flag evaluation requires context"]
blog/19-05-2022-announcing-open-feature.md:45 MD022/blanks-around-headings/blanks-around-headers Headings should be surrounded by blank lines [Expected: 1; Actual: 0; Below] [Context: "## A win-win-win"]
docs/explanations/operator.md:10 MD036/no-emphasis-as-heading/no-emphasis-as-header Emphasis used instead of a heading [Context: "Links"]
docs/reference/contributing.md:5 MD025/single-title/single-h1 Multiple top-level headings in the same document [Context: "# Providing Feedback"]
docs/reference/contributing.md:9 MD025/single-title/single-h1 Multiple top-level headings in the same document [Context: "# Contributing"]
docs/tutorials/ofo.md:7 MD025/single-title/single-h1 Multiple top-level headings in the same document [Context: "# Cloud native feature-flaggin..."]
docs/tutorials/ofo.md:11:15 MD026/no-trailing-punctuation Trailing punctuation in heading [Punctuation: '!']
docs/tutorials/ofo.md:21:25 MD026/no-trailing-punctuation Trailing punctuation in heading [Punctuation: '!']
docs/tutorials/ofo.md:26 MD031/blanks-around-fences Fenced code blocks should be surrounded by blank lines [Context: "```shell"]
docs/tutorials/ofo.md:43 MD031/blanks-around-fences Fenced code blocks should be surrounded by blank lines [Context: "```shell"]
docs/tutorials/ofo.md:45 MD031/blanks-around-fences Fenced code blocks should be surrounded by blank lines [Context: "```"]
docs/tutorials/ofo.md:53:51 MD009/no-trailing-spaces Trailing spaces [Expected: 0 or 2; Actual: 1]
docs/tutorials/ofo.md:54 MD031/blanks-around-fences Fenced code blocks should be surrounded by blank lines [Context: "```shell"]
docs/tutorials/ofo.md:61:71 MD009/no-trailing-spaces Trailing spaces [Expected: 0 or 2; Actual: 1]
docs/tutorials/ofo.md:62 MD031/blanks-around-fences Fenced code blocks should be surrounded by blank lines [Context: "```shell"]
docs/tutorials/ofo.md:69 MD031/blanks-around-fences Fenced code blocks should be surrounded by blank lines [Context: "```shell"]
docs/tutorials/ofo.md:92 MD031/blanks-around-fences Fenced code blocks should be surrounded by blank lines [Context: "```shell"]
docs/tutorials/ofo.md:98:41 MD034/no-bare-urls Bare URL used [Context: "http://localhost:30000"]
docs/tutorials/ofo.md:123 MD031/blanks-around-fences Fenced code blocks should be surrounded by blank lines [Context: "```shell"]
docs/tutorials/ofo.md:125:3 MD047/single-trailing-newline Files should end with a single newline character
external-content/specification/specification/glossary.md:7 MD025/single-title/single-h1 Multiple top-level headings in the same document [Context: "# Glossary"]
external-content/specification/specification/README.md:8 MD025/single-title/single-h1 Multiple top-level headings in the same document [Context: "# OpenFeature Specification"]
external-content/specification/specification/sections/01-flag-evaluation.md:7 MD025/single-title/single-h1 Multiple top-level headings in the same document [Context: "# 1. Flag Evaluation API"]
external-content/specification/specification/sections/02-providers.md:7 MD025/single-title/single-h1 Multiple top-level headings in the same document [Context: "# 2. Provider"]
external-content/specification/specification/sections/02-providers.md:33 MD001/heading-increment/header-increment Heading levels should only increment by one level at a time [Expected: h4; Actual: h5]
external-content/specification/specification/sections/02-providers.md:131 MD040/fenced-code-language Fenced code blocks should have a language specified [Context: "```"]
external-content/specification/specification/sections/03-evaluation-context.md:7 MD025/single-title/single-h1 Multiple top-level headings in the same document [Context: "# 3. Evaluation Context"]
external-content/specification/specification/sections/04-hooks.md:7 MD025/single-title/single-h1 Multiple top-level headings in the same document [Context: "# 4. Hooks"]
external-content/specification/specification/types.md:7 MD025/single-title/single-h1 Multiple top-level headings in the same document [Context: "# Types and Data Structures"]
external-content/specification/tools/specification_parser/test_specification.md:7 MD001/heading-increment/header-increment Heading levels should only increment by one level at a time [Expected: h3; Actual: h5]
README.md:5 MD001/heading-increment/header-increment Heading levels should only increment by one level at a time [Expected: h2; Actual: h3]

How to test

netlify[bot] commented 1 year ago

Deploy Preview for lucky-creponne-baf9b3 ready!

Name Link
Latest commit 6b907014ddb7405a7385b0f992953973d1eab871
Latest deploy log https://app.netlify.com/sites/lucky-creponne-baf9b3/deploys/63ceafd4211fe100081969fb
Deploy Preview https://deploy-preview-249--lucky-creponne-baf9b3.netlify.app
Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site settings.

aepfli commented 1 year ago

so I set up the linters, and there are a few issues markdownlint complains about:

  1. if there is a title and a first-level heading - because this is seen as two first-level headings within a document (which might also be the case) - sometimes they're the same, so it is redundant, but sometimes they diverge like in the introduction. Furthermore, sometimes we use a first-level heading and not a front-matter-title. Sometimes, we use a front-matter-title but no first-level heading. This is currently a little bit inconsistent, and the question is, what is the way we want to use it :)

  2. markdownlint can also lint the mdx files, which is working. But the imports before the first level heading is a problem. Now, if we say we always use the front-matter-title, this issue is resolved. If we do want to use markdown first-level headings, we can think of either moving those imports or ignoring this rule (i don't have a strong opinion on that)

I already caught some issues with inconsistent ordering of ordered lists etc., so it will add a benefit. - just let me know what your opinion is regarding this and, most importantly, how I should move forward regarding the issues

blog/02-09-2022-creating-a-provider-for-the-go-sdk.mdx:10 MD025/single-title/single-h1 Multiple top-level headings in the same document [Context: "# Creating a Provider For The ..."]
docs/reference/concepts/01-evaluation-api.mdx:6 MD041/first-line-heading/first-line-h1 First line in a file should be a top-level heading [Context: "import Tabs from '@theme/Tabs'..."]
docs/reference/concepts/02-provider.mdx:6 MD041/first-line-heading/first-line-h1 First line in a file should be a top-level heading [Context: "import Tabs from '@theme/Tabs'..."]
docs/reference/concepts/03-evaluation-context.mdx:6 MD041/first-line-heading/first-line-h1 First line in a file should be a top-level heading [Context: "import Tabs from '@theme/Tabs'..."]
docs/reference/concepts/04-hooks.mdx:6 MD041/first-line-heading/first-line-h1 First line in a file should be a top-level heading [Context: "import Tabs from '@theme/Tabs'..."]
docs/reference/intro.mdx:7 MD025/single-title/single-h1 Multiple top-level headings in the same document [Context: "# Welcome to OpenFeature"]
docs/reference/technologies/client/index.mdx:7 MD025/single-title/single-h1 Multiple top-level headings in the same document [Context: "# Client"]
docs/reference/technologies/client/web.mdx:1 MD041/first-line-heading/first-line-h1 First line in a file should be a top-level heading [Context: "import { WebFeatures } from '@..."]
docs/reference/technologies/index.mdx:7 MD025/single-title/single-h1 Multiple top-level headings in the same document [Context: "# Technologies"]
docs/reference/technologies/server/dotnet.mdx:1 MD041/first-line-heading/first-line-h1 First line in a file should be a top-level heading [Context: "import { DotnetFeatures } from..."]
docs/reference/technologies/server/go.mdx:1 MD041/first-line-heading/first-line-h1 First line in a file should be a top-level heading [Context: "import { GoFeatures } from '@s..."]
docs/reference/technologies/server/index.mdx:7 MD025/single-title/single-h1 Multiple top-level headings in the same document [Context: "# Server"]
docs/reference/technologies/server/java.mdx:1 MD041/first-line-heading/first-line-h1 First line in a file should be a top-level heading [Context: "import { JavaFeatures } from '..."]
docs/reference/technologies/server/javascript.mdx:1 MD041/first-line-heading/first-line-h1 First line in a file should be a top-level heading [Context: "import {JavascriptFeatures } f..."]
docs/reference/technologies/server/php.mdx:1 MD041/first-line-heading/first-line-h1 First line in a file should be a top-level heading [Context: "import { PhpFeatures } from '@..."]
docs/tutorials/getting-started/go.mdx:10 MD025/single-title/single-h1 Multiple top-level headings in the same document [Context: "# Getting Started with the Ope..."]
docs/tutorials/getting-started/java.mdx:12 MD025/single-title/single-h1 Multiple top-level headings in the same document [Context: "# Getting Started with the Ope..."]
docs/tutorials/getting-started/node.mdx:12 MD025/single-title/single-h1 Multiple top-level headings in the same document [Context: "# Getting Started with the Ope..."]
docs/tutorials/ofo.md:7 MD025/single-title/single-h1 Multiple top-level headings in the same document [Context: "# Cloud native feature-flaggin..."]
external-content/specification/specification/glossary.md:7 MD025/single-title/single-h1 Multiple top-level headings in the same document [Context: "# Glossary"]
external-content/specification/specification/README.md:8 MD025/single-title/single-h1 Multiple top-level headings in the same document [Context: "# OpenFeature Specification"]
external-content/specification/specification/sections/01-flag-evaluation.md:7 MD025/single-title/single-h1 Multiple top-level headings in the same document [Context: "# 1. Flag Evaluation API"]
external-content/specification/specification/sections/02-providers.md:7 MD025/single-title/single-h1 Multiple top-level headings in the same document [Context: "# 2. Provider"]
external-content/specification/specification/sections/02-providers.md:33 MD001/heading-increment/header-increment Heading levels should only increment by one level at a time [Expected: h4; Actual: h5]
external-content/specification/specification/sections/02-providers.md:131 MD040/fenced-code-language Fenced code blocks should have a language specified [Context: "```"]
external-content/specification/specification/sections/03-evaluation-context.md:7 MD025/single-title/single-h1 Multiple top-level headings in the same document [Context: "# 3. Evaluation Context"]
external-content/specification/specification/sections/04-hooks.md:7 MD025/single-title/single-h1 Multiple top-level headings in the same document [Context: "# 4. Hooks"]
external-content/specification/specification/types.md:7 MD025/single-title/single-h1 Multiple top-level headings in the same document [Context: "# Types and Data Structures"]
external-content/specification/tools/specification_parser/test_specification.md:7 MD001/heading-increment/header-increment Heading levels should only increment by one level at a time [Expected: h3; Actual: h5]
src/components/custom/tutorial/flagd-change-content.mdx:1 MD041/first-line-heading/first-line-h1 First line in a file should be a top-level heading [Context: "Let's change the feature flag ..."]
src/components/custom/tutorial/flagd-content.mdx:1 MD041/first-line-heading/first-line-h1 First line in a file should be a top-level heading [Context: "Providers are an important con..."]
src/components/custom/tutorial/why-default-content.mdx:1 MD041/first-line-heading/first-line-h1 First line in a file should be a top-level heading [Context: ""Why I'm I seeing that value?"..."]
beeme1mr commented 1 year ago

Hey @aepfli, we need to use mdx so we should refactor existing pages to make them work with the linter. Having a linter makes sense though. Thanks for this great work!

aepfli commented 1 year ago

The checks are working, but some of the solutions could be better. Markdownlint will lint MDX files but is not 100% ready for this. For example, writing comments can be tricky, as how to enable/disable specific rules via comments. But I think it is a good start, and it should benefit the documentation and the overall structure :)