Lint markdown format and links (#777)

Author: kevmoo

.github/workflows/markdown_linter.yml

@@ -0,0 +1,30 @@
+name: markdown_linter
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+  schedule:
+    - cron: "0 0 * * 0"
+
+jobs:
+  markdown-link-check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@master
+      - uses: gaurav-nelson/github-action-markdown-link-check@v1
+  markdown_lint:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: [ 14.x ]
+    steps:
+      - uses: actions/checkout@master
+      - name: Use Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v1
+        with:
+          node-version: ${{ matrix.node-version }}
+      - name: Install dependencies
+        run: npm install --global markdownlint-cli2
+      - name: Run lint check
+        run: markdownlint-cli2-fix "**/*.md"

.markdownlint.yaml

@@ -0,0 +1,15 @@
+# Rules for markdownlint-cli2 (https://github.com/DavidAnson/markdownlint-cli2)
+# Based on markdownlint library (https://github.com/DavidAnson/markdownlint)
+# (same linter as vscode-markdownlint).
+# See rules descriptions here:
+# https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md
+#
+first-line-heading: false
+line_length:                # MD013 max line length
+  tables: false             # don't break tables
+  code_blocks: false        # don't break on code blocks
+  line_length: 80
+html:                       # MD033 no html
+  allowed_elements: [br]
+images: false               # MD045: image alt text
+no-blanks-blockquote: false # MD028

README.md

@@ -5,26 +5,26 @@ deserialization.
 
 ## json_serializable [![Pub Package](https://img.shields.io/pub/v/json_serializable.svg)](https://pub.dev/packages/json_serializable)
 
-* Package: https://pub.dev/packages/json_serializable
-* [Source code](json_serializable)
+- Package: <https://pub.dev/packages/json_serializable>
+- [Source code](json_serializable)
 
 The core package providing Generators for JSON-specific tasks.
 
 Import it into your pubspec `dev_dependencies:` section.
 
 ## json_annotation [![Pub Package](https://img.shields.io/pub/v/json_annotation.svg)](https://pub.dev/packages/json_annotation)
 
-* Package: https://pub.dev/packages/json_annotation
-* [Source code](json_annotation)
+- Package: <https://pub.dev/packages/json_annotation>
+- [Source code](json_annotation)
 
 The annotation package which has no dependencies.
 
 Import it into your pubspec `dependencies:` section.
 
 ## checked_yaml [![Pub Package](https://img.shields.io/pub/v/checked_yaml.svg)](https://pub.dev/packages/checked_yaml)
 
-* Package: https://pub.dev/packages/checked_yaml
-* [Source code](checked_yaml)
+- Package: <https://pub.dev/packages/checked_yaml>
+- [Source code](checked_yaml)
 
 Generate more helpful exceptions when decoding YAML documents using
 `package:json_serializable` and `package:yaml`.
@@ -33,7 +33,7 @@ Import it into your pubspec `dependencies:` section.
 
 ## example
 
-* [Source code](example)
+- [Source code](example)
 
 An example showing how to setup and use `json_serializable` and
 `json_annotation`.

checked_yaml/README.md

@@ -7,7 +7,7 @@ the target type.
 
 [`package:json_serializable`] can generate classes that can parse the
 [`YamlMap`] type provided by [`package:yaml`] when `anyMap: true` is specified
-for the class annotation. 
+for the class annotation.
 
 ```dart
 @JsonSerializable(

example/README.md

@@ -1,4 +1,4 @@
-*This example assumes you're using a recent version of the Dart or Flutter SDK.*
+_This example assumes you're using a recent version of the Dart or Flutter SDK._
 
 To use [package:json_serializable][json_serializable] in your package, add these
 dependencies to your `pubspec.yaml`.
@@ -15,10 +15,10 @@ dev_dependencies:
 Annotate your code with classes defined in
 [package:json_annotation][json_annotation].
 
-* See [`lib/example.dart`][example] for an example of a file using these
+- See [`lib/example.dart`][example] for an example of a file using these
   annotations.
 
-* See [`lib/example.g.dart`][example_g] for the generated file.
+- See [`lib/example.g.dart`][example_g] for the generated file.
 
 Run `pub run build_runner build` to generate files into your source directory.
 
@@ -32,7 +32,8 @@ Run `pub run build_runner build` to generate files into your source directory.
 [INFO] Build: Succeeded after 4687ms with 1 outputs
 ```
 
-*NOTE*: If you're using Flutter, replace `pub run` with `flutter packages pub run`.
+_NOTE_: If you're using Flutter, replace `pub run` with
+`flutter packages pub run`.
 
 [example]: lib/example.dart
 [example_g]: lib/example.g.dart

json_annotation/CHANGELOG.md

@@ -7,14 +7,14 @@
 
 ## 3.1.1
 
-- Avoid `null` values for `CheckedFromJsonException.message` by using 
+- Avoid `null` values for `CheckedFromJsonException.message` by using
   `toString()` with unrecognized error types.
 - Added a helpful `UnrecognizedKeysException.toString()`.
 - Fixed doc comments for `JsonSerializable.genericArgumentFactories`.
 
 ## 3.1.0
 
-- Added `JsonSerializable.genericArgumentFactories` field. 
+- Added `JsonSerializable.genericArgumentFactories` field.
 - Require at least Dart `2.7.0`.
 
 ## 3.0.1
@@ -48,134 +48,134 @@
 
 ## 2.2.0
 
-* Add an optional (named) `badKey` parameter and field to
+- Add an optional (named) `badKey` parameter and field to
   `CheckedFromJsonException`.
 
 ## 2.1.0
 
-* Require at least Dart `2.1.1`.
+- Require at least Dart `2.1.1`.
 
-* Added to `encodeEmptyCollection` to `JsonKey` and `JsonSerializable`.
+- Added to `encodeEmptyCollection` to `JsonKey` and `JsonSerializable`.
 
-* `JsonSerializable.fromJson` now throws `CheckedFromJsonException` on errors.
-  This is potentially a breaking change. 
+- `JsonSerializable.fromJson` now throws `CheckedFromJsonException` on errors.
+  This is potentially a breaking change.
 
-* Added a more helpful `toString` to `CheckedFromJsonException`.
+- Added a more helpful `toString` to `CheckedFromJsonException`.
 
 ## 2.0.0
 
-* **Potentially Breaking** `JsonSerializable` no longer sets default values for
+- **Potentially Breaking** `JsonSerializable` no longer sets default values for
   fields when constructor arguments are unset or `null`. This is not likely an
   issue for developers using this class as an annotation with a compatible
   version of `package:json_serializable`, but it may cause issues if class is
   used in other contexts.
 
-* Support all `build.yaml` configuration options on classes by adding a number
+- Support all `build.yaml` configuration options on classes by adding a number
   of fields to `JsonSerializable`: `anyMap`, `checked`, `explicitToJson`,
   `generateToJsonFunction`, and `useWrappers`.
 
 ## 1.2.0
 
-* Added `JsonConverter` class to support custom conversion of types.
+- Added `JsonConverter` class to support custom conversion of types.
 
 ## 1.1.0
 
-* Added the `fieldRename` option to `JsonSerializable` and the associated
+- Added the `fieldRename` option to `JsonSerializable` and the associated
   `FieldRename` enum.
 
 ## 1.0.0
 
-* Added `JsonValue` class for annotating `enum` fields with a custom
+- Added `JsonValue` class for annotating `enum` fields with a custom
   serialization value.
 
-* Removed `$checkAllowedKeys`, `$enumDecode` and `$enumDecodeNullable` which are
+- Removed `$checkAllowedKeys`, `$enumDecode` and `$enumDecodeNullable` which are
   no longer needed by the latest release of `package:json_serializable`.
 
 ## 0.2.9+1
 
-* Support the Dart 2.0 stable release.
+- Support the Dart 2.0 stable release.
 
 ## 0.2.9
 
-* When `FormatException` is caught in "checked mode", use the `message`
-  property when creating `CheckedFromJsonException`.
+- When `FormatException` is caught in "checked mode", use the `message` property
+  when creating `CheckedFromJsonException`.
 
 ## 0.2.8
 
-* Added `$checkKeys` helper function and deprecated `$checkAllowedKeys`.
+- Added `$checkKeys` helper function and deprecated `$checkAllowedKeys`.
   Upgrading to the latest `json_serializable` and re-running your build will
   eliminate any `@deprecated` hints you see.
 
-* Added `BadKeyException` exception which is the abstract super class for
+- Added `BadKeyException` exception which is the abstract super class for
   `MissingRequiredKeysException`, `UnrecognizedKeysException`, and
   `DisallowedNullValueException`.
 
-* Added `JsonKey.required` field and an associated
+- Added `JsonKey.required` field and an associated
   `MissingRequiredKeysException` that is thrown when `required` fields don't
   have corresponding keys in a source JSON map.
 
-* Added `JsonKey.disallowNullValue`  field and an associated
+- Added `JsonKey.disallowNullValue` field and an associated
   `DisallowedNullValueException` that is thrown when corresponding keys exist in
   a source JSON map, but their values are `null`.
 
-* Updated documentation of `JsonSerializable.createToJson` to include details
-  of the new `generate_to_json_function` configuration option.
+- Updated documentation of `JsonSerializable.createToJson` to include details of
+  the new `generate_to_json_function` configuration option.
 
 ## 0.2.7+1
 
-* Small improvement to `UnrecognizedKeysException.message` output and
+- Small improvement to `UnrecognizedKeysException.message` output and
   documentation comments.
 
 ## 0.2.7
 
-* Added `JsonSerializable.disallowUnrecognizedKeys`.
-  * Added a helper function to support this option. This function starts with a
+- Added `JsonSerializable.disallowUnrecognizedKeys`.
+  - Added a helper function to support this option. This function starts with a
     `$` and should only be referenced by generated code. It is not meant for
     direct use.
-  * Added `UnrecognizedKeysException` for reporting errors.
+  - Added `UnrecognizedKeysException` for reporting errors.
 
 ## 0.2.6
 
-* `CheckedFromJsonException`
-  * Added a public constructor to support hand-written JSON decoding logic.
-  * The `message` property is now `String` (instead of `Object`).
+- `CheckedFromJsonException`
 
-* Added `JsonKey.defaultValue`.
+  - Added a public constructor to support hand-written JSON decoding logic.
+  - The `message` property is now `String` (instead of `Object`).
 
-* Added helpers for deserialization of `enum` values.
-  These functions starting with `$` are  referenced by generated code.
-  They are not meant for direct use.
+- Added `JsonKey.defaultValue`.
+
+- Added helpers for deserialization of `enum` values. These functions starting
+  with `$` are referenced by generated code. They are not meant for direct use.
 
 ## 0.2.5
 
-* Added `CheckedFromJsonException` which is thrown by code generated when
- `checked` is enabled in `json_serializable`.
+- Added `CheckedFromJsonException` which is thrown by code generated when
+  `checked` is enabled in `json_serializable`.
 
-* Added functions to support the `checked` generation option.
-  These functions starting with `$` are referenced by generated code.
-  They are not meant for direct use.
+- Added functions to support the `checked` generation option. These functions
+  starting with `$` are referenced by generated code. They are not meant for
+  direct use.
 
 ## 0.2.4
 
-* Added `fromJson` and `toJson` fields to `JsonKey` class.
+- Added `fromJson` and `toJson` fields to `JsonKey` class.
 
 ## 0.2.3
 
-* Added `ignore` field to `JsonKey` class annotation
+- Added `ignore` field to `JsonKey` class annotation
 
 ## 0.2.2
 
-* Added a helper class – `$JsonMapWrapper` – and helper functions – `$wrapMap`,
-  `$wrapMapHandleNull`, `$wrapList`, and `$wrapListHandleNull` – to support
-  the `useWrappers` option added to `JsonSerializableGenerator` in `v0.3.0` of
+- Added a helper class – `$JsonMapWrapper` – and helper functions – `$wrapMap`,
+  `$wrapMapHandleNull`, `$wrapList`, and `$wrapListHandleNull` – to support the
+  `useWrappers` option added to `JsonSerializableGenerator` in `v0.3.0` of
   `package:json_serializable`.
 
 ## 0.2.1
 
-* `JsonSerializable` class annotation
-  * Added `nullable` field.
-  * Fixed doc comment.
+- `JsonSerializable` class annotation
+  - Added `nullable` field.
+  - Fixed doc comment.
 
 ## 0.2.0
 
-* Moved annotation classes for `JsonSerializable` and `JsonLiteral`.
+- Moved annotation classes for `JsonSerializable` and `JsonLiteral`.