Merge pull request #73 from ctasada/ctasada/markdown-linting

chore: Fixed MarkDown Linting

Author: ctasada

.github/workflows/build.yml

@@ -37,6 +37,18 @@ jobs:
           files: docs
           fail_on_error: true
 
+      - name: Lint md files
+        uses: DavidAnson/markdownlint-cli2-action@v16
+        with:
+          config: './conf/.markdownlint.json'
+          globs: './docs/**/*.md'
+
+      - name: Lint mdx files
+        uses: DavidAnson/markdownlint-cli2-action@v16
+        with:
+          config: './conf/.mdx.markdownlint.json'
+          globs: './docs/**/*.mdx'
+
       - name: Deploy to GitHub Pages
         if: github.ref == 'refs/heads/master'
         uses: peaceiris/actions-gh-pages@v3

README.md

@@ -37,3 +37,10 @@ vale docs/
 ```
 
 Words not part of the dictionary yet are added in [accept.txt](.github/styles/config/vocabularies/Springwolf/accept.txt).
+
+## Run Markdown Linter
+
+To validate that the created Markdown follows the rules:
+```bash
+npm run lint:md
+```

conf/.markdownlint.json

@@ -0,0 +1,4 @@
+{
+  "default": true,
+  "MD013": false
+}

conf/.mdx.markdownlint.json

@@ -0,0 +1,7 @@
+{
+  "extends": ".markdownlint.json",
+
+  "first-line-heading": false,
+  "no-bare-urls": false,
+  "no-inline-html": false
+}

docs/behind-the-scenes.md

@@ -7,6 +7,7 @@ sidebar_position: 70
 The following paragraphs describe how Springwolf works internally.
 
 ## Big Picture
+
 When the Spring Boot application is started, Springwolf uses its scanners to find defined consumers and producers within the application.
 Based on the results, the channels/topics are extracted including payload type and merged together into an [AsyncAPI conform document](https://www.asyncapi.com/docs/reference/specification/v3.0.0).
 
@@ -17,19 +18,22 @@ When publishing is enabled, the user can publish a message through the UI to ano
 From there, Springwolf forwards the message to the protocol specific producer.
 
 ## Plugins
+
 `springwolf-core` provides the base functionality to orchestrate the scanning and building of the AsyncAPI document.
 The different protocol (AMQP, Cloud-Stream, JMS, Kafka, SNS, SQS) are supported through plugins.
 These plugins are found through the Spring dependency injection functionality.
 When building own scanner plugins, your plugin will need to implement the `ChannelsScanner` interface.
 
 ## Scanners
+
 `springwolf-core` runs all scanners and merges the found results together into one AsyncAPI document.
 When the same channel/topic is found multiple times, it's merged as well.
 
 The result is a [`ChannelItem`](https://www.asyncapi.com/docs/reference/specification/v3.0.0#channelObject).
 The `ChannelObject` contains the `Message` for the receive and/or send operation.
 
 ## Building an example payload
+
 When the scanners scan and build the result, they also extract the payload type.
 The payload is registered in the `ComponentsService`, which allows to split the `Message` from the schema definition - within the AsyncAPI doc a `$ref` references is used.
 
@@ -40,9 +44,11 @@ Additionally, Springwolf generates an example based on the provided schema.
 By using `swagger-parser`, all the `@Schema` and other swagger annotations are supported as well as `@JsonProperty` through the use of the ObjectMapper.
 
 ### ModelConverters
+
 ModelConverters provide a way to improve documentation for classes, which can't be modified, for example because they're part of an external library.
 They follow the same plugin model.
 
 ## Putting it all together
+
 The `AsyncApiService` collects all the channels, schemas and general info and builds the AsyncApi document.
 The controller access this services to serve the document to the UI.

docs/configuration/configuration.mdx

@@ -80,15 +80,14 @@ The following table contains additional properties that can be specified in the
 | `springwolf.plugin.sqs.publishing.enabled`               | `false`            | Allow (anyone) to produce SQS messages from the UI. *Note that this has security implications*                                                                                                                                                                                                                                                                                                                                                                                              |
 | `springwolf.plugin.sqs.scanner.sqs-listener.enabled`     | `true`             | Enable scanner to find methods annotated with `@SqsListener`.                                                                                                                                                                                                                                                                                                                                                                                                                               |
 
-
-
 ## Actuator support
 
 Springwolf supports exposing the AsyncAPI document as part of Spring Boot’s actuator endpoint.
 The AsyncAPI document will then be moved underneath actuators base path, that's `/actuator/springwolf/docs.json` or `/actuator/springwolf/docs.yaml` respectively.
 
 To enable it, add the `spring-boot-actuator` dependency first.
 Second, enable the actuator endpoint in the `application.properties` file:
+
 ```properties
 # Move Springwolf endpoint to actuator
 springwolf.endpoint.actuator.enabled=true

docs/configuration/customizing.md

@@ -3,6 +3,7 @@ sidebar_position: 80
 ---
 
 # Customizing
+
 Adding and changing functionality of Springwolf is easy.
 The [configuration](../configuration/configuration.mdx) page mentions the existing ones.
 
@@ -26,6 +27,7 @@ By implementing the `AsyncApiCustomizer`, the AsyncAPI document can be modified
 It's the final interception point before the document is available to the user.
 
 For example, the title can be adjusted - although this should be done through the configuration:
+
 ```java
 @Component
 public class AsyncApiTitleCustomizer implements AsyncApiCustomizer {

docs/configuration/documenting-bindings.md

@@ -40,6 +40,7 @@ Associate this operation with JMS, see [operation-binding] for details.
 ### `@SnsAsyncOperationBinding`
 
 Associate this operation with SNS, see [operation-binding] for details.
+
 ```java
 @SnsAsyncOperationBinding
 ```
@@ -71,9 +72,11 @@ You can define anything and there is no validation.
 ```
 
 ## Binding properties
+
 Explanation of the different binding properties.
 
 ### General
+
 The following properties are the same for all bindings.
 
 #### Queue Name (Channel Name)
@@ -94,7 +97,7 @@ The Kafka headers describing the metadata of the payload, more details in the ge
 
 The Springwolf comes with a special `AsyncHeadersCloudEventConstants` to document CloudEvents.
 
-The `kafka` header `__TypeId__` (constant from ` AbstractJavaTypeMapper.DEFAULT_CLASSID_FIELD_NAME`) can be documented as well.
+The `kafka` header `__TypeId__` (constant from `AbstractJavaTypeMapper.DEFAULT_CLASSID_FIELD_NAME`) can be documented as well.
 
 ### AMQP
 
@@ -106,18 +109,22 @@ The exchange name that will be used to bind queues to.
 
 The routing key used when publishing a message.
 
-
 ### Kafka
 
 #### Group Id
+
 The group id that will be used during message consumption
 
 #### Client Id
+
 The client id to identify the consumer
 
 ### Google PubSub binding annotations
+
 #### Channel Binding Object
+
 The Channel Bindings Object is used to describe the Google Cloud Pub/Sub Topic details.
+
 ```java
 @GooglePubSubAsyncChannelBinding(
             messageRetentionDuration = "messageRetentionDuration",
@@ -130,27 +137,34 @@ The Channel Bindings Object is used to describe the Google Cloud Pub/Sub Topic d
                             lastRevisionId = "lastRevisionId",
                             name = "projects/{project}/schemas/{schema}"))
 ```
-`MessageRetentionDuration`: Indicates the minimum duration to retain a message after it's published to the topic 
+
+`MessageRetentionDuration`: Indicates the minimum duration to retain a message after it's published to the topic
 
 `Message Storage Policy`: The Message Storage Policy Object is used to describe the Google Cloud Pub/Sub MessageStoragePolicy.
-- A list of IDs of GCP regions where messages that are published to the topic may be persisted in storage 
+
+- A list of IDs of GCP regions where messages that are published to the topic may be persisted in storage
 
 `Schema Settings`:The Schema Settings Object is used to describe the Google Cloud Pub/Sub SchemaSettings.
+
 - encoding: The encoding of the message
 - firstRevisionId: The minimum (inclusive) revision allowed for validating messages
 - lastRevisionId: The maximum (inclusive) revision allowed for validating messages
 - name: The name of the schema that messages published should be validated against (The format is `projects/{project}/schemas/{schema}`.)
+
 #### Message Binding Object
+
 The Message Binding Object is used to describe the Google Cloud Pub/Sub PubsubMessage details, alongside with pertinent parts of the Google Cloud Pub/Sub Schema Object.
+
 ```java
 @GooglePubSubAsyncMessageBinding(
             orderingKey = "key",
             schema = @GooglePubSubAsyncMessageSchema(name = "projects/{project}/schemas/{schema}"))
 ```
+
 `OrderingKey`: If non-empty, identifies related messages for which publish order should be respected
 
 `Schema Definition`: The Schema Definition Object is used to describe the Google Cloud Pub/Sub Schema Object with AsyncAPI. While some of this information could be, or is, described using native AsyncAPI, for consistency it makes sense to provide this information here at all times, especially for cases where AsyncAPI doesn't natively support describing payloads using a supported Google Cloud Pub/Sub schema format like Protobuf
-- name: The name of the schema
 
+- name: The name of the schema
 
 [operation-binding]: https://www.asyncapi.com/docs/reference/specification/v3.0.0#operationBindingsObject

docs/configuration/documenting-consumers.md

@@ -10,6 +10,7 @@ Sometimes projects are configured in a way that makes Springwolf unable to autom
 For these use-cases, Springwolf provides additional ways to explicitly add them to the generated document.
 
 To document consumers, either:
+
 - add the `@AsyncListener` annotation or
 - rely on the auto-detection of `@JmsListener`, `@KafkaListener`, `@RabbitListener`, `@SqsListener`
 
@@ -23,6 +24,7 @@ Additional fields can be documented.
 On the same method, the protocol binding is defined. More details can be found in the [bindings](documenting-bindings.md) section.
 
 Below is an example to demonstrate the annotation:
+
 ```java
 @KafkaListener
 @AsyncListener(operation = @AsyncOperation(
@@ -74,6 +76,7 @@ Optional. Useful when an application is connect to multiple brokers and wants to
 The server needs to exist in [configuration > Servers](configuration.mdx) as well.
 
 ## `@JmsListener`, `@KafkaListener`, `@RabbitListener`, `@SqsListener`
+
 The `@JmsListener`, `@KafkaListener`, `@RabbitListener`, `@SqsListener` annotations are detected automatically.
 There is nothing more to do.
 Use the other option if the provided documentation is insufficient.

docs/configuration/documenting-messages.mdx

@@ -17,6 +17,7 @@ Springwolf provides different ways to document the messages. The `message` is pa
 A message can be defined as part of the `@AsyncOperation` annotation, using `message = @AsyncMessage()` field.
 
 For example:
+
 ```java
 @AsyncPublisher(operation = @AsyncOperation(
         channelName = "example-producer-topic",
@@ -39,6 +40,7 @@ public void sendMessage(ExamplePayloadDto msg) {
 Springwolf tries to auto-detect the payload type based on the method signature.
 
 When the method has multiple arguments, the payload can be indicated via `@Payload`, that's
+
 ```java
 public void sendMessage(@Payload ExamplePayloadDto msg, String traceId, Object loggingContext) {}
 ```
@@ -62,7 +64,6 @@ First, the base property `springwolf.payload.extractable-classes`.
 Second, the canonical class name, `java.util.function.Function` in this case.
 And third, the generic parameter index (`1`).
 
-
 ## Schema
 
 Under the hood Springwolf relies on swagger-core `ModelConverters` to define the message schema.