Fix Markdown issues and add markdownlint configuration

Author: glen-84

.markdownlint.yml

@@ -0,0 +1,7 @@
+# https://github.com/DavidAnson/markdownlint
+
+# Multiple headings with the same content.
+MD024:
+  siblings_only: true
+# Emphasis used instead of a heading.
+MD036: false

README.md

@@ -1,18 +1,16 @@
+# GraphQL Composite Schema Spec
+
 > **Stage 0: Preliminary**
 >
 > This spec is in the proposal stage of active development, and can change
 > before reaching `Draft` stage. For more information, please see the
 > [Roadmap](ROADMAP.md).
 
----
-
-# GraphQL Composite Schema Spec
-
 The GraphQL Composite Schema specification is edited in the markdown files found
 in [`/spec`](./spec) the latest release of which is published at
-https://graphql.github.io/composite-schemas-spec/.
+<https://graphql.github.io/composite-schemas-spec/>.
 
-### Contributing to this repo
+## Contributing to this repo
 
 See more in [CONTRIBUTING.md](CONTRIBUTING.md) about contributing spec changes.
 If you want to start a general discussion or concern, please
@@ -27,10 +25,8 @@ separate
 
 ---
 
-Copyright Joint Development Foundation Projects, LLC, GraphQL Series.<br>
-[graphql.org](https://graphql.org) | [Spec](https://spec.graphql.org) |
-[GitHub](https://github.com/graphql/composite-schemas-spec) |
-[GraphQL Foundation](https://foundation.graphql.org) |
-[Code of Conduct](https://code-of-conduct.graphql.org) |
-[Discord](https://discord.com/channels/625400653321076807/863141924126588958) |
+Copyright Joint Development Foundation Projects, LLC, GraphQL Series. \
+[graphql.org](https://graphql.org) | [Spec](https://spec.graphql.org) | [GitHub](https://github.com/graphql/composite-schemas-spec)
+| [GraphQL Foundation](https://foundation.graphql.org) | [Code of Conduct](https://code-of-conduct.graphql.org)
+| [Discord](https://discord.com/channels/625400653321076807/863141924126588958) |
 [Store](https://store.graphql.org)

spec/Section 2 -- Source Schema.md

@@ -236,7 +236,18 @@ type Product {
 ## @inaccessible
 
 ```graphql
-directive @inaccessible on FIELD_DEFINITION | OBJECT | INTERFACE | UNION | ARGUMENT_DEFINITION | SCALAR | ENUM | ENUM_VALUE | INPUT_OBJECT | INPUT_FIELD_DEFINITION
+# prettier-ignore
+directive @inaccessible on
+  | FIELD_DEFINITION
+  | OBJECT
+  | INTERFACE
+  | UNION
+  | ARGUMENT_DEFINITION
+  | SCALAR
+  | ENUM
+  | ENUM_VALUE
+  | INPUT_OBJECT
+  | INPUT_FIELD_DEFINITION
 ```
 
 The `@inaccessible` directive is used to prevent specific type system members

spec/Section 4 -- Composition.md

@@ -3637,7 +3637,7 @@ MergeTypes(types):
 - If {kind} is `OBJECT`:
   - Return the result of {MergeObjectTypes(types)}.
 
-#### Merge Scalar Types
+### Merge Scalar Types
 
 **Formal Specification**
 
@@ -3693,7 +3693,7 @@ scalar Date
 scalar Date
 ```
 
-#### Merge Interface Types
+### Merge Interface Types
 
 **Formal Specification**
 
@@ -3812,7 +3812,7 @@ interface Product {
 }
 ```
 
-#### Merge Enum Types
+### Merge Enum Types
 
 **Formal Specification**
 
@@ -3930,7 +3930,7 @@ enum Status {
 }
 ```
 
-#### Merge Union Types
+### Merge Union Types
 
 **Formal Specification**
 
@@ -4027,7 +4027,7 @@ In this case, the `Product` type is marked with `@inaccessible` in the first
 schema. As a result, the `Product` type is excluded from the composed
 `SearchResult`
 
-#### Merge Input Types
+### Merge Input Types
 
 **Formal Specification**
 
@@ -4160,7 +4160,7 @@ input OrderInput {
 In this case, the description from the first schema is retained, while the
 fields are merged from both schemas to create the final `OrderInput` type.
 
-#### Merge Object Types
+### Merge Object Types
 
 **Formal Specification**
 
@@ -4317,7 +4317,7 @@ type Product {
 }
 ```
 
-#### Merge Output Fields
+### Merge Output Fields
 
 **Formal Specification**
 
@@ -4497,7 +4497,7 @@ type Product {
 }
 ```
 
-#### Merge Input Fields
+### Merge Input Fields
 
 **Formal Specification**
 
@@ -4594,7 +4594,7 @@ In the final schema, `minTotal` is defined using the most restrictive type
 (`Int!`), has a default value of `0`, and includes the description from the
 original field in `Schema A`.
 
-#### Merge Argument Definitions
+### Merge Argument Definitions
 
 **Formal Specification**
 
@@ -4690,7 +4690,7 @@ In the merged schema, the `filter` argument is defined with the most restrictive
 type (`ProductFilter!`), includes the description from the original field in
 `Schema A`, and is marked as required.
 
-#### Merge Arguments
+### Merge Arguments
 
 **Formal Specification**
 

spec/Spec.md

@@ -21,7 +21,7 @@ ecosystem.
 The GraphQL Specification Project has evolved and may continue to evolve in
 future editions of this specification. Previous editions of the GraphQL
 specification can be found at permalinks that match their release tag. The
-latest working draft release can be found at https://spec.graphql.org/draft.
+latest working draft release can be found at <https://spec.graphql.org/draft>.
 
 **Copyright notice**
 
@@ -82,9 +82,11 @@ explicitly in prose (e.g. "Note: ") or are set apart in a note block, like this:
 
 Note: This is an example of a non-normative note.
 
+<!-- markdownlint-disable MD025 -->
+
 # [Overview](Section%201%20--%20Overview.md)
 
-# [Subgraph](Section%202%20--%20Source%20Schema.md)
+# [Source Schema](Section%202%20--%20Source%20Schema.md)
 
 # [Composition](Section%204%20--%20Composition.md)
 
@@ -93,3 +95,5 @@ Note: This is an example of a non-normative note.
 # [Shared Types](Section%206%20--%20Shared%20Types.md)
 
 # [Appendix A -- Field Selection](Appendix%20A%20--%20Field%20Selection.md)
+
+<!-- markdownlint-enable MD025 -->