fixup: lint

Signed-off-by: Todd Baert <[email protected]>

.markdownlint-cli2.yaml

@@ -11,10 +11,14 @@ config:
       - br
   github-admonition: true
   max-one-sentence-per-line: true
+  code-block-style: false         # not compatible with mkdocs "details" panes
 
 ignores:
   - "**/CHANGELOG.md"
   - "docs/specification"
   - "node_modules"
   - "tmp"
-  - "**/protos.md" # auto-generated
+  - "**/protos.md"  # auto-generated
+  - "schemas"       # submodule
+  - "spec"          # submodule
+  - "test-harness"  # submodule

mkdocs.yml

@@ -65,8 +65,8 @@ nav:
       - '"start" Command': 'reference/flagd-cli/flagd_start.md'
       - '"version" Command': 'reference/flagd-cli/flagd/flagd_version.md'
     - 'Sync Configuration': 'reference/sync-configuration.md'
-    - 'Flag Definition':
-      - 'Definition Overview': 'reference/flag-definition.md'
+    - 'Flag Definitions':
+      - 'Definition Overview': 'reference/flag-definitions.md'
       - 'Custom Operations':
         - 'Fractional': 'reference/custom-operations/fractional-operation.md'
         - 'Semantic Version': 'reference/custom-operations/semver-operation.md'

web-docs/architecture.md

@@ -2,7 +2,7 @@
 
 flagd architectures fall into two broad categories: those where the evaluation engine is deployed in a standalone process to which the client application connects ([RPC](#rpc-evaluation)), and those where the evaluation engine is embedded into the client application ([in-process](#in-process-evaluation)).
 
-## RPC vs In-Process Evaluation 
+## RPC vs In-Process Evaluation
 
 ### RPC evaluation
 
@@ -27,7 +27,6 @@ erDiagram
     "client app (+ flagd RPC provider)" ||--|| flagd : "evaluation.proto (gRPC/stream) / HTTP"
 ```
 
-
 ### In-Process evaluation
 
 In-process deployments embed the flagd evaluation engine directly into the client application through the use of an [in-process provider](./deployment.md#in-process).

web-docs/concepts/syncs.md

@@ -1,7 +1,7 @@
 # Syncs
 
 Syncs are a core part of flagd; they are the abstraction that enables different sources for feature flag definitions.
-flagd can connect to one or more sync sources to 
+flagd can connect to one or more sync sources to
 
 ## Available syncs
 

web-docs/deployment.md

@@ -1,4 +1,6 @@
-# Docker
+# Deployment
+
+## Docker
 
 :octicons-terminal-24: Install from the command line:
 
@@ -8,10 +10,11 @@ docker pull ghcr.io/open-feature/flagd:latest
 
 :octicons-code-square-24: Use as base image in Dockerfile:
 
-```
+```dockerfile
 FROM ghcr.io/open-feature/flagd:latest
 ```
-## Kubernetes
+
+### Kubernetes
 
 flagd was designed with cloud-native paradigms in mind.
 You can run it as a sidecar, or as a central service in your cluster.
@@ -21,31 +24,31 @@ If you're interested in a full-featured solution for using flagd in Kubernetes,
 
 ---
 
-# Binary
+## Binary
 
 :fontawesome-brands-linux::fontawesome-brands-windows::fontawesome-brands-apple: Binaries are available in x86/ARM.
 
 [Release](https://github.com/open-feature/flagd/releases)
 
-## systemd
+### systemd
 
 A systemd wrapper is available [here](https://github.com/open-feature/flagd/blob/main/systemd/flagd.service).
 
 ---
 
-# In-Process
+## In-Process
 
-## :fontawesome-brands-golang: Go in-process provider
+### :fontawesome-brands-golang: Go in-process provider
 
 [flagd-in-process/pkg](https://pkg.go.dev/github.com/open-feature/go-sdk-contrib/providers/flagd-in-process/pkg)
 
 ```shell
 go get github.com/open-feature/go-sdk-contrib/providers/flagd-in-process/[email protected]
 ```
 
-## :fontawesome-brands-java: Java in-process provider
+### :fontawesome-brands-java: Java in-process provider
 
-### Maven
+#### Maven
 
 ```xml
 <dependency>
@@ -54,8 +57,8 @@ go get github.com/open-feature/go-sdk-contrib/providers/flagd-in-process/pkg@v0.
 </dependency>
 ```
 
-### Gradle
+#### Gradle
 
-```
+```gradle
 implementation 'dev.openfeature.contrib.providers:flagd'
 ```

web-docs/faq.md

@@ -34,4 +34,4 @@ Please see [architecture](./architecture.md) and [deployment](./deployment.md) f
 Because you haven't opened a PR or created an issue!
 
 We're always adding new functionality to flagd, and welcome additions and ideas from new contributors.
-Don't hesitate to [open an issue](https://github.com/open-feature/flagd/issues)!
+Don't hesitate to [open an issue](https://github.com/open-feature/flagd/issues)!

web-docs/index.md

@@ -1,4 +1,6 @@
-# What is flagd?
+# Introduction
+
+## What is flagd?
 
 _flagd_ is a _feature flag evaluation engine_.
 Think of it as a ready-made, open source, OpenFeature-compliant feature flag backend system.
@@ -16,7 +18,7 @@ It doesn't include a UI, management console or a persistence layer.
 It's configurable entirely via a POSIX-style CLI.
 Thanks to it's minimalism, it's _extremely flexible_; you can leverage flagd as a sidecar alongside your application, an engine running in your application process, or as a central service evaluating thousands of flags per second.
 
-# How do I deploy flagd?
+## How do I deploy flagd?
 
 flagd is designed to fit well into a variety of infrastructures, and can run on various architectures.
 It run as a separate process or directly in your application.
@@ -25,12 +27,12 @@ If you're already leveraging containers in your infrastructure, you can extend t
 You can also run flagd as a service on a VM or a "bare-metal" host.
 If you'd prefer not to run an additional process at all, you can run the flagd evaluation engine directly in your application.
 No matter how you run flagd, you will need to supply it with feature flags.
-The flag definitions supplied to flagd (*sources*) are monitored for changes which will be immediately reflected in flagd's evaluations.
+The flag definitions supplied to flagd (_sources_) are monitored for changes which will be immediately reflected in flagd's evaluations.
 Currently supported sources include files, HTTP endpoints, Kubernetes custom resources, and proto-compliant gRPC services.
 
 <!-- TODO: Link to various deployment sections with grid: https://squidfunk.github.io/mkdocs-material/reference/grids -->
 
-# How do I use flagd?
+## How do I use flagd?
 
 flagd is fully OpenFeature compliant.
 To leverage it in your application you must use the OpenFeature SDK and flagd provider for your language.

web-docs/quick-start.md

@@ -2,6 +2,8 @@
 name: Quick Start
 ---
 
+# Quick Start
+
 Learn the basics of flagd from the comfort of your terminal.
 
 ## What you'll need
@@ -13,7 +15,6 @@ Learn the basics of flagd from the comfort of your terminal.
 
 ### Download the flag definition
 
-
 ```shell
 wget https://raw.githubusercontent.com/open-feature/flagd/main/web-docs/assets/demo.flagd.json
 ```
@@ -37,19 +38,20 @@ docker run \
 ```
 
 ??? "Tips for Windows users"
-
     In Windows, use WSL system for both the file location and Docker runtime.
     Mixed file systems does not work and this is a [limitation of Docker](https://github.com/docker/for-win/issues/8479).
 
 ### Evaluating a feature flag
 
 Test it out
+
 ```shell
 curl -X POST "http://localhost:8013/schema.v1.Service/ResolveBoolean" \
   -d '{"flagKey":"show-welcome-banner","context":{}}' -H "Content-Type: application/json"
 ```
 
 You should see the following result:
+
 ```json
 {
   "value": false,
@@ -71,6 +73,7 @@ curl -X POST "http://localhost:8013/schema.v1.Service/ResolveBoolean" \
 ```
 
 You should see the updated results:
+
 ```json
 {
   "value": true,
@@ -208,4 +211,4 @@ In this guide, we configured flagd to use a local flag configuration.
 We then performed flag evaluation using cURL to see how updating the flag definition affects the output.
 We also explored how evaluation context can be used within a targeting rule to personalize the output.
 This is just scratching the surface of flagd's capabilities.
-Check out the [concepts section](./concepts//feature-flagging.md) to learn about the use cases enabled by flagd.
+Check out the [concepts section](./concepts//feature-flagging.md) to learn about the use cases enabled by flagd.

web-docs/reference/flag-definition.md → web-docs/reference/flag-definitions.md

@@ -1,4 +1,4 @@
-# Flag Definition
+# Flag Definitions
 
 ## Flags
 

web-docs/reference/monitoring.md

@@ -28,7 +28,6 @@ This status changes to HTTP 200 when all sync providers at
 least have one successful data sync.
 The status does not change from there on.
 
-
 ## OpenTelemetry
 
 flagd provides telemetry data out of the box. This telemetry data is compatible with OpenTelemetry.
@@ -44,19 +43,19 @@ Given below is the current implementation overview of flagd telemetry internals,
 
 flagd expose following metrics,
 
-* `http.server.duration`
-* `http.server.response.size`
-* `http.server.active_requests`
-* `feature_flag.flagd.impression`
-* `feature_flag.flagd.evaluation.reason`
+- `http.server.duration`
+- `http.server.response.size`
+- `http.server.active_requests`
+- `feature_flag.flagd.impression`
+- `feature_flag.flagd.evaluation.reason`
 
 ## Traces
 
 flagd expose following traces,
 
-* `flagEvaluationService(resolveX)` - SpanKind server
-  * `jsonEvaluator(resolveX)` - SpanKind internal
-* `jsonEvaluator(setState)` - SpanKind internal
+- `flagEvaluationService(resolveX)` - SpanKind server
+  - `jsonEvaluator(resolveX)` - SpanKind internal
+- `jsonEvaluator(setState)` - SpanKind internal
 
 ## Export to OTEL collector
 

web-docs/reference/naming.md

@@ -3,4 +3,4 @@
 _flagd_ was conceived as a simple program with a POSIX-style CLI that's designed to run as a service or [daemon](https://en.wikipedia.org/wiki/Daemon_(computing)).
 For this reason, its name is stylized as all lower case: "flagd", consistent with other famous Unix/Linux daemons (_crond_, _sshd_, _systemd_, _ntpd_, _httpd_, etc).
 Although the flagd system has expanded beyond the flagd application itself to include libraries which embed flagd's evaluation engine, the "flagd" stylization should be observed for all components relating to flagd.
-Where possible, please treat "flagd" as a single word, including in library names, packages, variable names, etc.
+Where possible, please treat "flagd" as a single word, including in library names, packages, variable names, etc.

web-docs/reference/providers.md

@@ -6,4 +6,4 @@ For more information about Openfeature providers, see the [OpenFeature documenta
 
 Providers for flagd come in two flavors: those that are built to communicate with a flagd instance (over HTTP or gRPC) and those that embed flagd's evaluation engine directly (note that some providers are capable of operating in either mode). For more information on how to deploy and use flagd, see [architecture](../architecture.md) and [deployment](../deployment.md).
 
-For a catalog of available flagd providers, check out the [OpenFeature ecosystem](https://openfeature.dev/ecosystem?instant_search%5Bquery%5D=flagd&instant_search%5BrefinementList%5D%5Btype%5D%5B0%5D=Provider) page.
+For a catalog of available flagd providers, check out the [OpenFeature ecosystem](https://openfeature.dev/ecosystem?instant_search%5Bquery%5D=flagd&instant_search%5BrefinementList%5D%5Btype%5D%5B0%5D=Provider) page.

web-docs/reference/specifications/rpc-providers.md

@@ -18,7 +18,7 @@ If you are unable to use gRPC code generation, you can also use REST (via the [c
 
 ### Protobuf
 
-Protobuf schemas define the contract between the flagd evaluation API and a client. 
+Protobuf schemas define the contract between the flagd evaluation API and a client.
 
 #### Code generation for gRPC sync