add explicit anchors to docs (other basic docs)

Author: gregsdennis

json-everything.net/Services/AnchorRegistry.cs

@@ -14,6 +14,7 @@ public static async Task RegisterDocs(HttpClient client)
 		{
 			await Task.WhenAll(
 				RegisterAnchors(client, "json-more"),
+				RegisterAnchors(client, "examples/more/enums"),
 
 				RegisterAnchors(client, "json-patch"),
 
@@ -23,16 +24,22 @@ await Task.WhenAll(
 
 				RegisterAnchors(client, "json-logic"),
 
-				RegisterAnchors(client, "playground/schema"),
 				RegisterAnchors(client, "schema-basics"),
+				RegisterAnchors(client, "examples/schema/external-schemas"),
+				RegisterAnchors(client, "examples/schema/managing-options"),
+				RegisterAnchors(client, "examples/schema/version-selection"),
 				RegisterAnchors(client, "schema-datagen"),
 				RegisterAnchors(client, "schema-generation"),
+				RegisterAnchors(client, "examples/schemagen/attribute"),
+				RegisterAnchors(client, "examples/schemagen/generator"),
+				RegisterAnchors(client, "examples/schemagen/intent"),
+				RegisterAnchors(client, "examples/schemagen/refiner"),
 				RegisterAnchors(client, "schema-vocabs"),
 				RegisterAnchors(client, "vocabs-data-2022"),
-				RegisterAnchors(client, "vocabs-unique-keys"),
-				RegisterAnchors(client, "examples/schema/external-schemas"),
-				RegisterAnchors(client, "examples/schema/managing-options"),
-				RegisterAnchors(client, "examples/schema/version-selection")
+				RegisterAnchors(client, "examples/schemadata/data-ref"),
+				RegisterAnchors(client, "examples/schemadata/external-ref"),
+				//RegisterAnchors(client, "examples/schemadata/schema-ref"),
+				RegisterAnchors(client, "vocabs-unique-keys")
 			);
 		}
 

json-everything.net/wwwroot/md/json-logic.md

@@ -1,8 +1,8 @@
-*(Not Json<nsp>_Something_<nsp>.Net, sadly.  "JsonLogic<nsp>.Net" was already registered on Nuget.  It breaks the pattern, I know.  _C'est la vie_.)*
+#  Overview {#logic}
 
 [JsonLogic](https://jsonlogic.com) is a mechanism that can be used to apply logical transformations to JSON values and that is also itself expressed in JSON.
 
-## The syntax
+# The syntax {#logic-syntax}
 
 JsonLogic is expressed using single-keyed objects called _rules_.  The key is the operator and the value is (usually) an array containing the parameters for the operation.  Here are a few examples:
 
@@ -19,7 +19,7 @@ So if we want to ensure a value in the input data is less than 2, we could use `
 
 There are many operators that work on different data types, ranging from string and array manipulation to arithmetic to boolean logic.  The full list is [on their website](https://jsonlogic.com/operations.html), and their docs are pretty good, so I won't repeat the list here.
 
-## In code
+# In code {#logic-in-code}
 
 The library defines an object model for rules, starting with the `Rule` base class.  This type is fully serializeable, so if you have rules in a text format, just deserialize them to get a `Rule` instance.
 
@@ -52,11 +52,11 @@ or via `JsonNode.Parse()`.
 
 \* _JSON null literals need to either be cast to `string`, use `JsonNull.Node` from Json.More.Net, or use the provided `LiteralRule.Null`.  All of these result in the same semantic value._
 
-## Gotchas for .Net developers
+# Gotchas for .Net developers {#logic-gotchas}
 
 In developing this library, I found that many of the operations don't align with similar operations in .Net.  Instead they tend to mimic the behavior of Javascript.  In this section, I'll try to list some of the more significant ones.
 
-### `==` vs `===`
+## `==` vs `===` {#logic-equality}
 
 `===` defines a "strict" equality.  This is the equality we're all familiar with in .Net.
 
@@ -81,7 +81,7 @@ That _should_ cover everything, but in case something's missed, it'll just retur
 
 \*\* _These cases effectively mean that the array must have a single element that is loosely equal to the number, though perhaps something like `[1,234]` might pass.  Again, the equality is **very** loose._
 
-### Type conversion
+## Type conversion {#logic-conversions}
 
 Some operations operate on specific types: sometimes strings, sometimes numbers.  To ensure maximum support, an attempt will be made to convert values to the type that the operation prefers.  If the value cannot be converted, a `JsonLogicException` will be thrown.
 
@@ -93,13 +93,13 @@ Because `+` supports both numbers (addition) and strings (concatenation); it wil
 
 Objects are never converted.
 
-### Automatic array flattening
+## Automatic array flattening {#logic-array-flattening}
 
 Nested arrays are flattened before being operated upon.  As an example of this, `[["a"]]` is flattened to `["a"]` and `["a",["b"]]` is flattened to `["a","b"]`. 
 
 That's it.  Not much to it; just be aware that it happens.
 
-## Creating new operators
+# Creating new operators {#logic-new-operators}
 
 JSON Logic also supports [adding custom operations](https://jsonlogic.com/add_operation.html).
 
@@ -120,7 +120,7 @@ It's definitely recommended to go through the [code for the built-in ruleset](ht
 
 Once your rule is defined, it needs to be registered using the `RuleRegistry.Register<T>()` method.  This will allow the rule to be automatically deserialized.
 
-## Overriding existing operators
+# Overriding existing operators {#logic-overriding}
 
 While this library allows you to inherit from, and therefore override, the default behavior of a `Rule`, you need to be aware of the implications.
 

json-everything.net/wwwroot/md/json-more.md

@@ -1,6 +1,8 @@
+#  Overview {#more}
+
 Json.More<nsp>.Net aims to fill gaps left by `System.Text.Json`.  To this end, it supplies four additional functions.
 
-# Equality comparison
+# Equality comparison {#more-equality}
 
 Sadly, it seems equality was considered unnecessary.  To remedy that, the `.IsEquivalentTo()` extension method is supplied for `JsonDocument`, `JsonElement`, and `JsonNode`.
 
@@ -18,7 +20,7 @@ Additionally, an `IEqualityComparer<JsonElement>` is supplied (`JsonElementEqual
 
 ***NOTE** Comparers are also supplied for `JsonDocument` and `JsonNode`.*
 
-# Explicitly specifying JSON null with `JsonNode`.
+# Explicitly specifying JSON null with `JsonNode` {#more-null}
 
 Because `JsonNode` was designed to unify .Net null with JSON null, it's difficult (and sometimes impossible) to determine when a JSON null is explicitly provided vs when it is merely the result of a missing property.  Ordinarily (e.g. during deserialization) this isn't much of a problem.
 
@@ -28,7 +30,7 @@ Under the covers, it's just a singleton `JsonValue<JsonNull>`.  Use `ReferenceEq
 
 ***IMPORTANT** This is provided exclusively as a signal.  It is not intended to be saved.  Best practice is to continue to save null.  [See the code](https://github.com/gregsdennis/json-everything/blob/595045ec8258f4073ee5666c721609a9c0886490/JsonSchema/ValidationContext.cs#L146-L149) for an example of proper usage.*
 
-# Enum serialization
+# Enum serialization {#more-enums}
 
 The `EnumStringConverter<T>` class enables string encoding of enum values.  `T` is the enum.
 
@@ -57,9 +59,9 @@ public enum MyFlagsEnum
 
 To use this converter, apply the `[JsonConverter(typeof(EnumStringConverter<T>))]` to either the enum or an enum-valued property.
 
-# Data conversions
+# Data conversions {#more-conversion}
 
-## `.AsNode()` extension
+## `.AsNode()` extension {#more-asnode}
 
 Previous versions of the libraries in the `json-everything` suite were built on `JsonElement`.  They have since been migrated to support `JsonNode` directly.
 
@@ -71,15 +73,15 @@ JsonNode? node = element.AsNode();
 
 Note that this does potentially return null to handle the JSON null case.
 
-## `.ToJsonArray()` extension
+## `.ToJsonArray()` extension {#more-toarray}
 
 .Net provided `JsonArray` with a constructor that takes an array of `JsonNode?`, however they don't support converting _any_ enumerable of nodes into an array.  This extension will handle that for you.
 
 ```c#
 JsonArray array = new List<JsonNode?>{ 1, null, false }.ToJsonArray();
 ```
 
-## `.AsJsonElement()` extension
+## `.AsJsonElement()` extension {#more-aselement}
 
 Sometimes you just want a `JsonElement` that represents a simple value, like a string, boolean, or number.  This library exposes several overloads of the `.AsJsonElement()` extension that can do this for you.
 
@@ -105,7 +107,7 @@ var obj = new Dictionary<string, JsonElement>{
 }
 ```
 
-## Making methods that require `JsonElement` easier to call
+## Making methods that require `JsonElement` easier to call {#more-proxy}
 
 ***NOTE** If you're using `JsonNode`, you shouldn't need this as it already defines implicit casts from the appropriate types.*
 
@@ -149,7 +151,7 @@ myObject.SomeMethod("string");
 
 To achieve this without `JsonElementProxy`, you could also create overloads for `short`, `int`, `long`, `float`, `double`, `decimal`, `string`, and `bool`.
 
-# JSON model serialization
+# JSON model serialization {#more-serialization}
 
 The .Net team did a great job of supporting fast serialization, but for whatever reason they didn't implement serializing their data model.  The `Utf8JsonWriterExtensions` class fills that gap.
 

json-everything.net/wwwroot/md/json-patch.md

@@ -1,6 +1,8 @@
+#  Overview {#patch}
+
 [JSON Patch](https://tools.ietf.org/html/rfc6902) is a language for modifying JSON documents.  Like JSON Schema, it is also expressed in JSON.
 
-## Syntax
+## Syntax {#patch-syntax}
 
 A patch consists of an array containing one or more operations.  Each operation may also contain one or more arguments.
 
@@ -20,7 +22,7 @@ The arguments vary among them, though all must contain at least an `op` and a `p
 - `from` specifies a source location within the JSON document from which to pull a value.
 - `value` specifies an explicit value.
 
-## Applying Patches
+## Applying Patches {#patch-apply}
 
 In JsonPatch<nsp>.Net, a `JsonPatch` object can be deserialized directly from the JSON document string.
 
@@ -44,7 +46,7 @@ var myPatchedObject = patch.Apply(myObject);
 var myDifferentTypeObject = patch.Apply<MyObject, MyDifferentObject>(myObject);
 ```
 
-## Inline Patching
+## Inline Patching {#patch-inline}
 
 The `JsonPatch` class can also be built in code using by creating a series of `PatchOperation`s through its static constructor methods.  There's one for each operation.
 
@@ -55,7 +57,7 @@ var patch = new JsonPatch(PatchOperation.Add("/foo/bar", "baz"),
 
 That's it!
 
-## Generating Patches
+## Generating Patches {#patch-generation}
 
 If you know what your start and end states are, but you want to find the differences, you can do that by generating a patch.
 

json-everything.net/wwwroot/md/json-path.md

@@ -1,8 +1,10 @@
+#  Overview {#path}
+
 JSON Path is a query language for JSON documents inspired by what XPath provides for XML documents.  It was [originally proposed](https://goessner.net/articles/JsonPath/) by Matt Goessner, and now a [specification](https://github.com/jsonpath-standard/internet-draft) is in progress.
 
 Version 0.4.x is aligned with the specification as of the end of Feb 2023, including support for functions (recently merged) and arithmetic operations in expressions (not part of the spec yet).
 
-## Syntax
+# Syntax {#path-syntax}
 
 A path consists of start indicator followed by a series of segments, chained one after another.  Each segment contains one or more selectors.  Each selector takes in a collection of JSON nodes and produces a collection of JSON nodes (called a "nodelist") based on their function.  The output of the segment is the collective output of all of that segment's selectors.  Each segment takes as input the output of the previous selector.
 
@@ -24,7 +26,7 @@ In addition to the above, there are a few shorthand options for some special cas
 - `..['foo']` may be rewritten as `..foo`
 - `..[*]` may be rewritten as `..*`
 
-### Query Expressions
+## Query Expressions {#path-expressions}
 
 Filter selectors take an expression.  This expression uses a single variable, which is a JSON node as described above.  The node is denoted by `@` and any valid JSON Path can follow it.  The `@` is a stand-in for the `$` from above and acts as the root of the local value.
 
@@ -55,7 +57,7 @@ Expressions support the following operations:
 
 _**NOTE** Arithmetic operations are not part of the specification (yet), and cannot be expected to work in other JSON Path implementations._
 
-#### Functions
+### Functions {#path-functions}
 
 There is also support for functions within query expressions, which works as an extension point to add your own custom logic.
 
@@ -70,7 +72,7 @@ The specification defines the following functions:
 
 \* _I-Regexp is designed to be an interoperable subset of most popular regular expression specifications and implementations.  One difference that [could not be resolved](https://github.com/ietf-wg-jsonpath/iregexp/issues/15) was implicit anchoring.  As such, two methods were developed to handle both cases.  `match` uses implicit anchoring, while `search` does not._
 
-## In Code
+# In Code {#path-in-code}
 
 To obtain an instance of a JSON Path, you'll need to parse it from a string.
 
@@ -98,7 +100,7 @@ This will return a results object that contains the resulting nodelist or an err
 
 A node contains both the value that was found and the location in the instance _where_ it was found.  The location is always represented using the "canonical," bracketed format.
 
-## Adherence to the Proposed Specification
+# Adherence to the Proposed Specification {#path-spec}
 
 As the specification is still under authorship, there are features present in traditional JSON Path that haven't been properly described yet.  For these features, this library has been configured to mimic the consensus behaviors of other libraries as determined by the [JSON Path Comparison](https://cburgmer.github.io/json-path-comparison/) project.
 

json-everything.net/wwwroot/md/json-pointer.md

@@ -1,8 +1,10 @@
+#  Overview {#pointer}
+
 ***NOTE** This documentation is based on the the latest non-beta version.  Updated documentation is in progress and will be available soon.*
 
 [JSON Pointer](https://tools.ietf.org/html/rfc6901) is a syntax that allows you to isolate a single element within a JSON document by navigating down a series of object properties and array indices.
 
-## The syntax
+## Syntax {#pointer-syntax}
 
 The syntax is really simple:
 
@@ -41,7 +43,7 @@ If a property contains a `/`, it must be escaped by replacing it with `~1`.  Add
 
 It also supports a URL format, which is essentially the same thing, except that it starts with a `#`, then followed by the standard pointer.  This format also will `%`-encode any URL-reserved characters, like `=` and `?`.
 
-## In code
+## In code {#pointer-in-code}
 
 The `JsonPointer` class is the model for JSON Pointer.
 
@@ -78,7 +80,7 @@ var success = pointer.TryEvaluate(element, out var result);
 
 ***ASIDE** The designers of the `JsonNode` API have elected (for [reasons](https://github.com/dotnet/designs/blob/40794be63ecd8b35e9596412050a84dedd575b99/accepted/2020/serializer/WriteableDomAndDynamic.md#missing-vs-null) I [disagree](https://github.com/dotnet/runtime/issues/66948#issuecomment-1080148457) with) to consider JSON null and .Net null to be equivalent.  This goes against both my personal experience building Manatee.Json and the `JsonElement` API, in which these are distinct concepts.  Because of this, it is impossible to determine whether a returned `JsonNode` value of `null` represents a value that is present but null or it is merely absent from the data.  To accomodate this, the evaluation method can only support the familiar `TryParse()` signature.  A return of `true` indicates the value was found, and `false` indicates it was not.  In the case of a `true` return, `result` may still be null, indicating the value was found and was a JSON null.*
 
-## Relative JSON Pointers
+## Relative JSON Pointers {#pointer-relative}
 
 [JSON Hyperschema](https://datatracker.ietf.org/doc/draft-handrews-json-schema-hyperschema/) relies on a variation of JSON Pointers called [Relative JSON Pointers](https://tools.ietf.org/id/draft-handrews-relative-json-pointer-00.html) that also includes the number of parent navigations.  This allows the system to start at an internal node in the JSON document and navigate to another node potentially on another subtree.
 

json-everything.net/wwwroot/md/schema-datagen.md

@@ -1,4 +1,4 @@
-# Generation Sample JSON Data from a Schema {#schema-datagen}
+# Generating Sample JSON Data from a Schema {#schema-datagen}
 
 JsonSchema.Net.DataGeneration is a tool that can create JSON data instances using a JSON schema as a framework.