docs: fixed typos and linting issues

.markdownlint-cli2.yaml

@@ -15,7 +15,6 @@ config:
 
 ignores:
   - "**/CHANGELOG.md"
-  - "docs/specification"
   - "node_modules"
   - "tmp"
   - "**/protos.md"  # auto-generated

docs/architecture.md

@@ -42,4 +42,4 @@ erDiagram
 ```
 
 <!-- TODO: add link to sync protocol reference entry -->
-<!-- TODO: we might want a dedicated Kubernets section here eventually to talk about the specifics of the K8s implementation -->
+<!-- TODO: we might want a dedicated Kubernetes section here eventually to talk about the specifics of the K8s implementation -->

docs/concepts/syncs.md

@@ -42,7 +42,7 @@ This stream connection is defined by the [sync service protobuf definition](http
 flagd start --uri grpc://grpc-sync-source
 ```
 
-In this example, `grpc-sync-source` is a grpc target implementing [sync.proto](../reference/flag-sync-protocol.md) definition.
+In this example, `grpc-sync-source` is a grpc target implementing [sync.proto](../reference/specifications/protos.md#syncv1sync_serviceproto) definition.
 See [sync source](../reference/sync-configuration.md#source-configuration) configuration for details.
 
 ---

docs/reference/custom-operations/fractional-operation.md

@@ -25,7 +25,7 @@ OpenFeature allows clients to pass contextual information which can then be used
 ```
 
 See the [headerColor](https://github.com/open-feature/flagd/blob/main/samples/example_flags.flagd.json#L88-#L133) flag.
-The `defaultVariant` is `red`, but it contains a [targeting rule](reusable_targeting_rules.md), meaning a fractional evaluation occurs for flag evaluation with a `context` object containing `email` and where that `email` value contains `@faas.com`.
+The `defaultVariant` is `red`, but it contains a [targeting rule](../flag-definitions.md#targeting-rules), meaning a fractional evaluation occurs for flag evaluation with a `context` object containing `email` and where that `email` value contains `@faas.com`.
 
 In this case, `25%` of the evaluations will receive `red`, `25%` will receive `blue`, and so on.
 

docs/reference/flag-definitions.md

@@ -145,7 +145,7 @@ 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 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 flag values to be cached, this behavior is described [here](../other_resources/caching.md).
+If no targeting rules are defined, the response reason will always be `STATIC`, this allows for the flag values to be cached, this behavior is described [here](specifications/rpc-providers.md#caching).
 
 #### Evaluation Context
 

docs/reference/flagd-cli/flagd.md

@@ -1,4 +1,5 @@
 <!-- markdownlint-disable-file -->
+<!-- WARNING: THIS DOC IS AUTO-GENERATED. DO NOT EDIT! -->
 ## flagd
 
 Flagd is a simple command line tool for fetching and presenting feature flags to services. It is designed to conform to Open Feature schema for flag definitions.
@@ -13,6 +14,6 @@ Flagd is a simple command line tool for fetching and presenting feature flags to
 
 ### SEE ALSO
 
-* [flagd start](flagd_start)	 - Start flagd
-* [flagd version](flagd_version)	 - Print the version number of flagd
+* [flagd start](flagd_start.md)	 - Start flagd
+* [flagd version](flagd_version.md)	 - Print the version number of flagd
 

docs/reference/flagd-cli/flagd_start.md

@@ -1,4 +1,5 @@
 <!-- markdownlint-disable-file -->
+<!-- WARNING: THIS DOC IS AUTO-GENERATED. DO NOT EDIT! -->
 ## flagd start
 
 Start flagd
@@ -37,5 +38,5 @@ flagd start [flags]
 
 ### SEE ALSO
 
-* [flagd](flagd)	 - Flagd is a simple command line tool for fetching and presenting feature flags to services. It is designed to conform to Open Feature schema for flag definitions.
+* [flagd](flagd.md)	 - Flagd is a simple command line tool for fetching and presenting feature flags to services. It is designed to conform to Open Feature schema for flag definitions.
 

docs/reference/flagd-cli/flagd_version.md

@@ -1,4 +1,5 @@
 <!-- markdownlint-disable-file -->
+<!-- WARNING: THIS DOC IS AUTO-GENERATED. DO NOT EDIT! -->
 ## flagd version
 
 Print the version number of flagd
@@ -22,5 +23,5 @@ flagd version [flags]
 
 ### SEE ALSO
 
-* [flagd](flagd)	 - Flagd is a simple command line tool for fetching and presenting feature flags to services. It is designed to conform to Open Feature schema for flag definitions.
+* [flagd](flagd.md)	 - Flagd is a simple command line tool for fetching and presenting feature flags to services. It is designed to conform to Open Feature schema for flag definitions.
 

docs/reference/specifications/custom-operations/fractional-operation-spec.md

@@ -13,7 +13,7 @@ hash function should be used. This is to ensure that flag resolution requests yi
 regardless of which implementation of the in-process flagd provider is being used.
 
 The supplied array must contain at least two items, with the first item being an optional [json logic variable declaration](https://jsonlogic.com/operations.html#var)
-specifying the bucketing property to base the distribution of values on. If not supplied, a concatination of the
+specifying the bucketing property to base the distribution of values on. If not supplied, a concatenation of the
 `flagKey` and `targetingKey` are used: `{"cat": [{"var":"$flagd.flagKey"}, {"var":"targetingKey"}]}`.
 The remaining items are `arrays`, each with two values, with the first being `string` item representing the name of the variant, and the
 second being a `float` item representing the percentage for that variant. The percentages of all items must add up to

docs/reference/specifications/rpc-providers.md

@@ -8,13 +8,13 @@ as it is done in the [OpenFeature Operator](https://github.com/open-feature/open
 Prerequisites:
 
 - Understanding of [general provider concepts](https://openfeature.dev/docs/reference/concepts/provider/)
-- Proficiency in the chosen programming language (check the language isn't already covered by the [existing providers](../usage/flagd_providers.md))
+- Proficiency in the chosen programming language (check the language isn't already covered by the [existing providers](../providers.md))
 
 ## flagd Evaluation API
 
 Fundamentally, RPC providers use the [evaluation schema](./protos.md#schemav1schemaproto) to connect to flagd, initiate evaluation RPCs, and listen for changes in the flag definitions.
 In order to do this, you must generate the gRPC primitives (message types and client) using the protobuf code generation mechanisms available in your language.
-If you are unable to use gRPC code generation, you can also use REST (via the [connect protocol](https://buf.build/blog/connect-a-better-grpc)) to communivate with flagd, though in this case, you will not be able to open a stream to listen for changes.
+If you are unable to use gRPC code generation, you can also use REST (via the [connect protocol](https://buf.build/blog/connect-a-better-grpc)) to communicate with flagd, though in this case, you will not be able to open a stream to listen for changes.
 
 ### Protobuf
 
@@ -39,7 +39,7 @@ cd schemas/protobuf
 buf generate --template buf.gen.{chosen language}.yaml
 ```
 
-As an alternative to buf, use the .proto file directly along with whatever protoc-related tools or plugins avaialble for your language.
+As an alternative to buf, use the .proto file directly along with whatever protoc-related tools or plugins available for your language.
 
 Move the generated code (following convention for the chosen language) and add its location to .gitignore
 
@@ -56,7 +56,7 @@ In-process flagd providers should do the following to make use of OpenFeature v0
   - note that the SDK will automatically emit `PROVIDER_READY`/`PROVIDER_ERROR` according to the termination of the `initialization` function
 - throw an exception or terminate abnormally if a connection cannot be established during `initialization`
 - For gRPC based sources (i.e. flagd-proxy), attempt to restore the streaming connection to flagd-proxy (if the connection cannot be established or is broken):
-  - If flag definition have been retrieved previously, go into `STALE` state to indicate that flag resolution responsees are based on potentially outdated Flag definition.
+  - If flag definition have been retrieved previously, go into `STALE` state to indicate that flag resolution responses are based on potentially outdated Flag definition.
   - reconnection should be attempted with an exponential back-off, with a max-delay of `maxSyncRetryInterval` (see [configuration](#configuration))
   - reconnection should be attempted up to `maxSyncRetryDelay` times (see [configuration](#configuration))
   - `PROVIDER_READY` and `PROVIDER_CONFIGURATION_CHANGED` should be emitted, in that order, after successful reconnection

docs/troubleshooting.md

@@ -5,7 +5,7 @@
 If a flag or targeting rule isn't proceeding the way you'd expect, you may want to enable more verbose logging.
 
 flagd and flagd providers typically have debug or verbose logging modes that you can use for this sort of troubleshooting.
-You can do this in the standalone version of flagd by starting it with the `--debug` flag (see [CLI](./reference/flagd-cli/flagd/flagd.md) for more information).
+You can do this in the standalone version of flagd by starting it with the `--debug` flag (see [CLI](./reference/flagd-cli/flagd.md) for more information).
 
 _In-process_ providers which embed the flag evaluation engine use a logging consistent with their implementation language and SDK.
 See your provider's documentation for details on how to enable verbose logging.

flagd/cmd/doc.go

@@ -2,20 +2,20 @@ package cmd
 
 import (
 	"fmt"
-	"strings"
 
 	"github.com/spf13/cobra/doc"
 )
 
 // GenerateDoc generates cobra docs of the cmd
 func GenerateDoc(path string) error {
 	linkHandler := func(name string) string {
-		return strings.ReplaceAll(name, ".md", "")
+		return name
 	}
 
 	filePrepender := func(filename string) string {
-		return "<!-- markdownlint-disable-file -->\n"
+		return "<!-- markdownlint-disable-file -->\n<!-- WARNING: THIS DOC IS AUTO-GENERATED. DO NOT EDIT! -->\n"
 	}
+
 	if err := doc.GenMarkdownTreeCustom(rootCmd, path, filePrepender, linkHandler); err != nil {
 		return fmt.Errorf("error generating docs: %w", err)
 	}

mkdocs.yml

@@ -70,9 +70,9 @@ nav:
   - 'Architecture': 'architecture.md'
   - 'Reference':
     - 'CLI':
-      - 'Commands': 'reference/flagd-cli/flagd.md'
-      - '"start" Command': 'reference/flagd-cli/flagd_start.md'
-      - '"version" Command': 'reference/flagd-cli/flagd/flagd_version.md'
+      - 'Overview': 'reference/flagd-cli/flagd.md'
+      - 'Start': 'reference/flagd-cli/flagd_start.md'
+      - 'Version': 'reference/flagd-cli/flagd_version.md'
     - 'Sync Configuration': 'reference/sync-configuration.md'
     - 'Flag Definitions':
       - 'Definition Overview': 'reference/flag-definitions.md'