docs: improve markdown quality (#498)

Signed-off-by: Simon Schrottner <simon.schrottner@dynatrace.com>

.github/workflows/markdown-checks.yaml

@@ -0,0 +1,19 @@
+name: Markdown checks
+
+on:
+  push:
+    paths:
+      - '**.md'
+  pull_request:
+    paths:
+      - '**.md'
+
+jobs:
+  markdown-lint:
+    runs-on: ubuntu-22.04
+    steps:
+      - name: Check out code
+        uses: actions/checkout@v3
+
+      - name: Lint Markdown files
+        run: make markdownlint

.markdownlint-cli2.yaml

@@ -0,0 +1,18 @@
+config:
+  line-length:
+    line_length: 500
+    tables: false
+    code_blocks: false
+  no-inline-html:
+    allowed_elements:
+      - details
+      - summary
+      - img
+  github-admonition: true
+  max-one-sentence-per-line: true
+
+ignores:
+  - "**/CHANGELOG.md"
+  - "docs/specification"
+  - "node_modules"
+  - "tmp"

CONTRIBUTING.md

@@ -1,22 +1,26 @@
-Welcome!
+# Welcome
 
 There are a few things to consider before contributing to flagd.
 
 Firstly, there's [a code of conduct](https://github.com/open-feature/.github/blob/main/CODE_OF_CONDUCT.md).
 TLDR: be respectful.
 
-Any contributions are expected to include unit tests. These can be validated with `make test` or the automated github workflow will run them on PR creation.
+Any contributions are expected to include unit tests.
+These can be validated with `make test` or the automated github workflow will run them on PR creation.
 
 This project uses a go workspace, to setup the project run
+
 ```shell
 make workspace-init
 ```
 
 The go version in the `go.work` is the currently supported version of go.
 
 The project uses remote buf packages, changing the remote generation source will require a one-time registry configuration:
+
 ```shell
 export GOPRIVATE=buf.build/gen/go
 ```
 
-Thanks! Issues and pull requests following these guidelines are welcome.
+Thanks!
+Issues and pull requests following these guidelines are welcome.

Makefile

@@ -60,3 +60,18 @@ mockgen: install-mockgen
 	mockgen -source=core/pkg/eval/ievaluator.go -destination=core/pkg/eval/mock/ievaluator.go -package=evalmock
 generate-docs:
 	cd flagd; go run ./cmd/doc/main.go
+
+# Markdown lint configuration
+#
+# - .markdownlintignore holds the configuration for files to be ignored
+# - .markdownlint.yaml contains the rules for markdownfiles
+MDL_DOCKER_VERSION := next
+ROOT_DIR := $(dir $(realpath $(lastword $(MAKEFILE_LIST))))
+MDL_CMD := docker run -v $(ROOT_DIR):/workdir --rm 
+
+.PHONY: markdownlint markdownlint-fix
+markdownlint:
+	$(MDL_CMD) davidanson/markdownlint-cli2-rules:$(MDL_DOCKER_VERSION) "**/*.md" 
+
+markdownlint-fix:
+	$(MDL_CMD) --entrypoint="markdownlint-cli2-fix" davidanson/markdownlint-cli2-rules:$(MDL_DOCKER_VERSION) "**/*.md" 

README.md

@@ -1,3 +1,4 @@
+<!-- markdownlint-disable MD033 -->
 <h1 align="center">
   <img src="images/flagD.png" width="350px;" >
 </h1>
@@ -13,6 +14,7 @@
   </a>
 </a>
 </p>
+<!-- markdownlint-enable MD033 -->
 
 ## Features
 
@@ -26,19 +28,24 @@
 
 ## Get started
 
-Flagd is a simple command line tool for fetching and evaluating feature flags for services. It is designed to conform with the OpenFeature specification. To get started, follow the installation instructions in the [docs](https://github.com/open-feature/flagd/blob/main/docs/README.md).
+Flagd is a simple command line tool for fetching and evaluating feature flags for services.
+It is designed to conform with the OpenFeature specification.
+To get started, follow the installation instructions in the [docs](https://github.com/open-feature/flagd/blob/main/docs/README.md).
 
 ## Contributing
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for details on how to contribute to the OpenFeature project.
 
-Our community meetings are held regularly and open to everyone. Check the [OpenFeature community calendar](https://calendar.google.com/calendar/u/0?cid=MHVhN2kxaGl2NWRoMThiMjd0b2FoNjM2NDRAZ3JvdXAuY2FsZW5kYXIuZ29vZ2xlLmNvbQ) for specific dates and for the Zoom meeting links.
+Our community meetings are held regularly and open to everyone.
+Check the [OpenFeature community calendar](https://calendar.google.com/calendar/u/0?cid=MHVhN2kxaGl2NWRoMThiMjd0b2FoNjM2NDRAZ3JvdXAuY2FsZW5kYXIuZ29vZ2xlLmNvbQ) for specific dates and for the Zoom meeting links.
 
 Thanks so much to our contributors.
 
+<!-- markdownlint-disable MD033 -->
 <a href="https://github.com/open-feature/flagd/graphs/contributors">
   <img src="https://contrib.rocks/image?repo=open-feature/flagd" />
 </a>
+<!-- markdownlint-enable MD033 -->
 
 Made with [contrib.rocks](https://contrib.rocks).
 

docs/README.md

@@ -4,15 +4,17 @@ This directory contains all flagd documentation, see table of contents below:
 
 ## Usage
 
-There are many ways to get started with flagd, the sections below run through some simple deployment options. Once the flagd service is running flag evaluation requests can either be made via one of the language specific flagd providers, or, directly via curl.
+There are many ways to get started with flagd, the sections below run through some simple deployment options.
+Once the flagd service is running flag evaluation requests can either be made via one of the language specific flagd providers, or, directly via curl.
 
 - [Getting started](./usage/getting_started.md)
 - [Flagd providers](./usage/flagd_providers.md)
 - [Evaluation examples](./usage/evaluation_examples.md)
 
 ## Flag Configuration
 
-Flagd is configured via CLI arguments on startup, these configuration options can be found in the flagd configuration section. The remaining sections cover the flag configurations themselves, which are JSON representations of the flag variants and targeting rules.
+Flagd is configured via CLI arguments on startup, these configuration options can be found in the flagd configuration section.
+The remaining sections cover the flag configurations themselves, which are JSON representations of the flag variants and targeting rules.
 
 - [Flagd Configuration](./configuration/configuration.md)
 - [Flag configuration](./configuration/flag_configuration.md)
@@ -34,5 +36,3 @@ This section documents any behavior of flagd which may seem unexpected, currentl
 - [Caching](./other_resources/caching.md)
 - [Snap](./other_resources/snap.md)
 - [Systemd service](./other_resources/systemd_service.md)
-
-

docs/configuration/configuration.md

@@ -1,32 +1,33 @@
 # Configuration
 
-`flagd` supports configuration via config file, environment variables and flags. In cases of conflict, flags have the
+`flagd` supports configuration via config file, environment variables and flags.
+In cases of conflict, flags have the
 highest priority, followed by environment variables and finally config file.
 
 Supported flags are documented (auto-generated) [here](./flagd_start.md).
 
-Environment variable keys are uppercased, prefixed with `FLAGD_` and all `-` are replaced with `_`. For example,
+Environment variable keys are uppercased, prefixed with `FLAGD_` and all `-` are replaced with `_`.
+For example,
 `sync-provider-args` in environment variable form is `FLAGD_SYNC_PROVIDER_ARGS`.
 
 Config file expects the keys to have the exact naming as the flags.
 
-### <a name="uri-patterns"></a> URI patterns
+## URI patterns
 
-Any URI passed to flagd via the `--uri` flag must follow one of the 4 following patterns to ensure that it is passed to the correct implementation: 
+Any URI passed to flagd via the `--uri` flag must follow one of the 4 following patterns to ensure that it is passed to the correct implementation:
 
 | Sync       | Pattern                               | Example                               |
 |------------|---------------------------------------|---------------------------------------|
 | Kubernetes | `core.openfeature.dev/namespace/name` | `core.openfeature.dev/default/my-crd` |
 | Filepath   | `file:path/to/my/flag`                | `file:etc/flagd/my-flags.json`        |
 | Remote     | `http(s)://flag-source-url`           | `https://my-flags.com/flags`          |
-| Grpc       | `grpc(s)://flag-source-url`           | `grpc://my-flags-server`              | 
+| Grpc       | `grpc(s)://flag-source-url`           | `grpc://my-flags-server`              |
 
-
-### Customising sync providers
+## Customising sync providers
 
 Custom sync providers can be used to provide flag evaluation logic.
 
-#### Kubernetes provider 
+### Kubernetes provider
 
 The Kubernetes provider allows flagD to connect to a Kubernetes cluster and evaluate flags against a specified FeatureFlagConfiguration resource as defined within the [open-feature-operator](https://github.com/open-feature/open-feature-operator/blob/main/apis/core/v1alpha1/featureflagconfiguration_types.go) spec.
 
@@ -36,22 +37,26 @@ To use an existing FeatureFlagConfiguration custom resource, start flagD with th
 flagd start --uri core.openfeature.dev/default/my_example
 ```
 
-### Source Configuration
+## Source Configuration
 
-While a URI may be passed to flagd via the `--uri` flag, some implementations may require further configurations. In these cases the `--sources` flag should be used.
-The flag takes a string argument, which should be a JSON representation of an array of `SourceConfig` objects. Alternatively, these configurations should be passed to
+While a URI may be passed to flagd via the `--uri` flag, some implementations may require further configurations.
+In these cases the `--sources` flag should be used.
+The flag takes a string argument, which should be a JSON representation of an array of `SourceConfig` objects.
+Alternatively, these configurations should be passed to
 flagd via config file, specified using the `--config` flag.
 
-| Field       | Type                                                       | Note                                               | 
+| Field       | Type                                                       | Note                                               |
 |-------------|------------------------------------------------------------|----------------------------------------------------|
 | uri         | required `string`                                          |                                                    |
 | provider    | required `string` (`file`, `kubernetes`, `http` or `grpc`) |                                                    |
 | bearerToken | optional `string`                                          | Used for http sync                                 |
 | certPath    | optional `string`                                          | Used for grpcs sync when TLS certificate is needed |
 
-The `uri` field values do not need to follow the [URI patterns](#uri-patterns), the provider type is instead derived from the provider field. If the prefix is supplied, it will be removed on startup without error.
+The `uri` field values do not need to follow the [URI patterns](#uri-patterns), the provider type is instead derived from the provider field.
+If the prefix is supplied, it will be removed on startup without error.
 
 Example start command using a filepath sync provider and the equivalent config file definition:
+
 ```sh
 ./bin/flagd start --sources='[{"uri":"config/samples/example_flags.json","provider":"file"},{"uri":"http://my-flag-source.json","provider":"http","bearerToken":"bearer-dji34ld2l"}]{"uri":"default/my-flag-config","provider":"kubernetes"},{"uri":"grpc://my-flag-source:8080","provider":"grpc"}'
 ```

docs/configuration/flag_configuration.md

@@ -1,28 +1,36 @@
 # Flag Configuration
 
-A flagd configuration is represented as a JSON object. Feature flag configurations can be found under `flags` and each item within `flags` represents a flag key (the unique identifier for a flag) and its corresponding configuration.
+A flagd configuration is represented as a JSON object.
+Feature flag configurations can be found under `flags` and each item within `flags` represents a flag key (the unique identifier for a flag) and its corresponding configuration.
 
-Sample configurations can be found at https://github.com/open-feature/flagd/tree/main/config/samples.
+Sample configurations can be found at <https://github.com/open-feature/flagd/tree/main/config/samples>.
 
 ## Flag configuration properties
 
 ### State
 
-`state` is **required** property. Validate states are "ENABLED" or "DISABLED". When the state is set to "DISABLED", flagd will behave like the flag doesn't exist.
+`state` is **required** property.
+Validate states are "ENABLED" or "DISABLED".
+When the state is set to "DISABLED", flagd will behave like the flag doesn't exist.
 
 Example:
 
-```
+```json
 "state": "ENABLED"
 ```
 
 ### Variants
 
-`variants` is a **required** property. It is an object containing the possible variations supported by the flag. All the values of the object **must** be the same type (e.g. boolean, numbers, string, JSON). The type used as the variant value will correspond directly affects how the flag is accessed. For example, to use a flag configured with boolean values the `/schema.v1.Service/ResolveBoolean` path should be used. If another path such as `/schema.v1.Service/ResolveString` is called, a type mismatch occurred and an error is returned.
+`variants` is a **required** property.
+It is an object containing the possible variations supported by the flag.
+All the values of the object **must** be the same type (e.g. boolean, numbers, string, JSON).
+The type used as the variant value will correspond directly affects how the flag is accessed.
+For example, to use a flag configured with boolean values the `/schema.v1.Service/ResolveBoolean` path should be used.
+If another path such as `/schema.v1.Service/ResolveString` is called, a type mismatch occurred and an error is returned.
 
 Example:
 
-```
+```json
 "variants": {
   "red": "c05543",
   "green": "2f5230",
@@ -32,7 +40,7 @@ Example:
 
 Example:
 
-```
+```json
 "variants": {
   "on": true,
   "off": false
@@ -41,7 +49,7 @@ Example:
 
 Example of an invalid configuration:
 
-```
+```json
 "variants": {
   "on": true,
   "off": "false"
@@ -50,11 +58,13 @@ Example of an invalid configuration:
 
 ### Default Variant
 
-`defaultVariant` is a **required** property. The value **must** match the name of one of the variants defined above. The default variant is always used unless a targeting rule explicitly overrides it.
+`defaultVariant` is a **required** property.
+The value **must** match the name of one of the variants defined above.
+The default variant is always used unless a targeting rule explicitly overrides it.
 
 Example:
 
-```
+```json
 "variants": {
   "on": true,
   "off": false
@@ -64,7 +74,7 @@ Example:
 
 Example:
 
-```
+```json
 "variants": {
   "red": "c05543",
   "green": "2f5230",
@@ -75,7 +85,7 @@ Example:
 
 Example of an invalid configuration:
 
-```
+```json
 "variants": {
   "red": "c05543",
   "green": "2f5230",
@@ -86,9 +96,16 @@ Example of an invalid configuration:
 
 ### Targeting Rules
 
-`targeting` is an **optional** property. A targeting rule **must** be valid JSON. Flagd uses a modified version of [JSON Logic](https://jsonlogic.com/), as well as some custom pre-processing, to evaluate these rules. The output of the targeting rule **must** match the name of one of the variants defined above. If an invalid or null value is is returned by the targeting rule, the `defaultVariant` value is used. If no targeting rules are defined, the response reason will always be `STATIC`, this allows for the client side caching of these flag values, this behavior is described [here](../other_resources/caching.md).
+`targeting` is an **optional** property.
+A targeting rule **must** be valid JSON.
+Flagd uses a modified version of [JSON Logic](https://jsonlogic.com/), as well as some custom pre-processing, to evaluate these rules.
+The output of the targeting rule **must** match the name of one of the variants defined above.
+If an invalid or null value is is returned by the targeting rule, the `defaultVariant` value is used.
+If no targeting rules are defined, the response reason will always be `STATIC`, this allows for the client side caching of these flag values, this behavior is described [here](../other_resources/caching.md).
 
-The [JSON Logic playground](https://jsonlogic.com/play.html) is a great way to experiment with new targeting rules. The following example shows how a rule could be configured to return `binet` when the email (which comes from evaluation context) contains `@faas.com`. If the email wasn't included in the evaluation context or doesn't contain `@faas.com`, null is returned and the `defaultVariant` is used instead.
+The [JSON Logic playground](https://jsonlogic.com/play.html) is a great way to experiment with new targeting rules.
+The following example shows how a rule could be configured to return `binet` when the email (which comes from evaluation context) contains `@faas.com`.
+If the email wasn't included in the evaluation context or doesn't contain `@faas.com`, null is returned and the `defaultVariant` is used instead.
 
 <details>
   <summary>Click here to see how this targeting rule would look in the JSON Logic playground.</summary>
@@ -124,3 +141,5 @@ The [JSON Logic playground](https://jsonlogic.com/play.html) is a great way to e
 1. Click `Compute`
 1. confirm the output show `"binet"`
 1. Optionally, experiment with different rules and data
+
+</details>