docs: documentation overhaul

docs/content/Examples/index.md

@@ -1,6 +1,8 @@
+# Examples
+
 Here you can find some example projects using this library:
 
-1. Basic example using the ktor
+1. Basic example using the Ktor
    plugin: [Official Example](https://github.com/stuebingerb/KGraphQL/tree/main/examples/ktor)
 1. Todo app that allows for nested todos and different scopes: [Todo Tree](https://github.com/MattLangsenkamp/TodoTree)
 1. An article about pairing Kotlin and GraphQL together using

docs/content/Installation/index.md

@@ -1,7 +1,4 @@
----
-title: Getting Started
-weight: 1
----
+# Installation
 
 [![Maven Central](https://img.shields.io/maven-central/v/de.stuebingerb/kgraphql.svg?label=Maven%20Central)](https://search.maven.org/search?q=g:%22de.stuebingerb%22%20AND%20a:%22kgraphql%22)
 
@@ -19,7 +16,7 @@ KGraphQL is available from Maven Central.
     Add dependencies:
 
     ```kotlin
-    implementation("de.stuebingerb:kgraphql:$KGraphQLVersion")
+    implementation("de.stuebingerb:kgraphql:${KGraphQLVersion}")
     ```
 === "Gradle"
     Add Maven Central repository:
@@ -30,7 +27,7 @@ KGraphQL is available from Maven Central.
     }
     ```
 
-    Add dependencies (you can also add other modules that you need):
+    Add dependencies:
 
     ```groovy
     implementation 'de.stuebingerb:kgraphql:${KGraphQLVersion}'
@@ -57,3 +54,7 @@ KGraphQL is available from Maven Central.
       <version>${KGraphQLVersion}</version>
     </dependency>
     ```
+You can also add other artifacts if you need them:
+
+* kgraphql-ktor
+* kgraphql-ktor-stitched

docs/content/Plugins/ktor.md

@@ -1,13 +1,15 @@
-# Ktor
+# Ktor Plugin
 
-If you are running a ktor server, there is a separate package that makes it easy to set up a fully functional GraphQL
+If you are running a Ktor server, there is a separate package that makes it easy to set up a fully functional GraphQL
 server.
 
-You first need to add the KGraphQL-ktor package to your dependency
+## Installation
+
+You first need to add the kgraphql-ktor package to your dependencies:
 
 === "Kotlin Gradle Script"
     ```kotlin
-    implementation("de.stuebingerb:kgraphql-ktor:$KGraphQLVersion")
+    implementation("de.stuebingerb:kgraphql-ktor:${KGraphQLVersion}")
     ```
 === "Gradle"
     ```groovy
@@ -22,10 +24,9 @@ You first need to add the KGraphQL-ktor package to your dependency
     </dependency>
     ```
 
-## Initial setup
+## Initial Setup
 
-To set up KGraphQL you'll need to install the GraphQL feature like you would any
-other [ktor feature](https://ktor.io/servers/features.html).
+To set up KGraphQL you'll need to install the GraphQL feature like you would any other [Ktor feature](https://ktor.io/servers/features.html).
 
 === "Example"
     ```kotlin
@@ -42,15 +43,14 @@ other [ktor feature](https://ktor.io/servers/features.html).
     ```
 
 Now you have a fully working GraphQL server. We have also set `playground = true`, so when running this you will be able
-to open [http://localhost:8080/graphql](http://localhost:8080/graphql) _(your port number may vary)_ in your browser and
-test it out directly within the browser.
+to open [http://localhost:8080/graphql](http://localhost:8080/graphql) _(your port number may vary)_ in your browser and test it out directly within the browser.
 
-## Configuration options
+## Configuration Options
 
 The GraphQL feature is extending the standard [KGraphQL configuration](../Reference/configuration.md) and providing its own
 set of configuration as described in the table below.
 
-| Property     | Description                                                                                                                                                                    | Default value  |
+| Property     | Description                                                                                                                                                                    | Default Value  |
 |--------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------|
 | endpoint     | This specifies what route will be delivering the GraphQL endpoint. When `playground` is enabled, it will use this endpoint also.                                               | `/graphql`     |
 | context      | Allows to add call-specific information to the GraphQL context, see example below.                                                                                             |                |
@@ -129,5 +129,5 @@ representation of a GraphQL schema.
     }
     ```
 
-If schema introspection is enabled, the ktor feature will expose the current schema in Schema Definition
+If schema introspection is enabled, the Ktor feature will expose the current schema in Schema Definition
 Language under [http://localhost:8080/graphql?schema](http://localhost:8080/graphql?schema).

docs/content/Reference/Type System/enums.md

@@ -1,7 +1,10 @@
 # Enums
 
-GraphQL Enums are a variant on the Scalar type, which represents one of a finite set of possible values. They directly
-map to Kotlin enums:
+GraphQL Enums are a variant on the Scalar type, which represents one of a finite set of possible values.
+
+## Schema
+
+Enums in KGraphQL directly map to Kotlin enums:
 
 === "Example"
     ```kotlin
@@ -37,6 +40,8 @@ map to Kotlin enums:
     }
     ```
 
+## Deprecation
+
 Enum values can be [deprecated](../deprecation.md):
 
 === "Example"

docs/content/Reference/Type System/input-objects.md

@@ -1,7 +1,4 @@
----
-title: Input Objects
-weight: 4
----
+# Input Objects
 
 A GraphQL Input Object defines a set of input fields; the input fields are either scalars, enums, or other input
 objects. Like Object and Interface types, Input Object types are inferred from defined operations, but can be explicitly
@@ -145,7 +142,7 @@ This behavior applies recursively to nested types as well. The nested `ChildType
 Input Objects are instantiated via their primary constructor. Kotlin default values are used unless a different value
 is provided explicitly. Due to a limitation in Kotlin, default values are not visible in the generated schema, though.
 
-## inputType {}
+## Configuration
 
 Input types can be configured via the `inputType` DSL.
 

docs/content/Reference/Type System/objects-and-interfaces.md

@@ -1,11 +1,12 @@
-# Overview
+# Objects and Interfaces
 
 GraphQL Objects and Interfaces represent a list of named fields, each of which yield a value of a specific type.
 KGraphQL inspects defined operations to create type system, but schema creator is able to explicitly declare and
 customize types. Besides, only member properties are inspected.
 
-**type { }**
-`type` method is entry point to Type DSL.
+## Schema
+
+The `type` method is the entry point to the Type DSL.
 See [Extension Properties](#extension-properties), [Kotlin Properties](#kotlin-properties), [Union Properties](#union-properties).
 
 === "Example"
@@ -70,7 +71,7 @@ and [deprecation](../deprecation.md) of kotlin properties as well as renaming or
     }
     ```
 
-**KProperty1<T, R>.ignore**
+## Ignoring Properties
 
 The extension function `ignore()` makes KGraphQL ignore its receiver property.
 
@@ -98,10 +99,12 @@ The extension function `ignore()` makes KGraphQL ignore its receiver property.
     }
     ```
 
-**transformation(KProperty1<T, R>) {}**
+## Property Transformation
 
 The `transformation` function allows to attach data transformation on any existing Kotlin property.
 
+### Transforming Returned Data
+
 === "Example"
     ```kotlin
     data class Person(val name: String, val age: Int)
@@ -142,6 +145,8 @@ The `transformation` function allows to attach data transformation on any existi
     }
     ```
 
+### Changing Nullability
+
 Transformations can also be used to change the return type of a property, for example to make nullable
 properties non-nullable:
 
@@ -190,6 +195,8 @@ properties non-nullable:
     }
     ```
 
+### Different Return Type
+
 Transformations can even change the type to a completely different class:
 
 === "Example"
@@ -246,8 +253,6 @@ Transformations can even change the type to a completely different class:
 Extension properties allow schema creator to easily attach additional field to any type. It is separately evaluated
 after main entity is resolved.
 
-## property { }
-
 `property` method accepts [resolver](../resolver.md) and can be subject of [deprecation](../deprecation.md).
 
 === "Example"
@@ -296,7 +301,9 @@ members of union type will fail in runtime.
 
 ## Data Loaded Properties
 
-*This feature is still in experimental state.*
+!!! warning ""
+
+    This feature is still in experimental state.
 
 One issue that you could easily encounter when doing a GraphQL API is the N+1 Problem. You can read more about this
 problem and solution in depth

docs/content/Reference/Type System/overview.md

@@ -9,7 +9,7 @@ KGraphQL is able to inspect operations and partially infer schema type system, s
 explicitly declare every type (but may if needed). Union types and Scalars require explicit definition in Schema DSL.
 Inferred classes are interpreted as GraphQL Object or Interface type.
 
-## Object or Interface?
+## Objects and Interfaces
 
 KGraphQL maps found types (implicit and explicit) to GraphQL simple inheritance model, where every type with fields is
 either Object or Interface. Rules are following:

docs/content/Reference/Type System/scalars.md

@@ -1,11 +1,10 @@
----
-title: Scalars
-weight: 1
----
+# Scalars
 
 As defined by specification, scalar represents a primitive value in GraphQL. In KGraphQL, besides built-in scalar types,
 client code can declare custom scalar types, which can coerce to `String`, `Boolean`, `Int`, `Long`, `Short` or `Float` (`kotlin.Double`).
 
+## Schema
+
 KGraphQL provides a group of DSL methods to define scalars:
 
 * `stringScalar { }`
@@ -36,6 +35,7 @@ correct subtype of `de.stuebingerb.kgraphql.schema.scalar.ScalarCoercion`:
       }
     }
     ```
+## Extended Scalars
 
 In addition to the built-in scalars, KGraphQL provides support for `Long`, `Short`, and `Char` which can be added to
 a schema using `extendedScalars()`.