Housekeeping: Markdownlint (#905)

* markdownlint config

* run markdownlint-cli2-fix

* ignore line length in tables

* fix linter issues in docs markdown files

* markdown-cli2-fix

* fix linter issues in ui readme

* add markdown linter CI action

* wrap filenames in code block

* run markdownlint-cli2-fix (forgot some files)

* fix remaining documents

* add some files to ignore list in markdownlint ci action

* fix formatting

* fix indentations

* fix markdownlint globs

* remove rule that requires uppercase Go

* make target markdown-lint

* update pre-push git hook to lint markdown files

.github/workflows/markdown-lint.yml

@@ -0,0 +1,21 @@
+name: markdown-lint
+
+on:
+  pull_request:
+    paths:
+      - '**.md'
+
+jobs:
+  markdownlint-cli2:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: DavidAnson/markdownlint-cli2-action@v9
+        with:
+          globs: |
+            **/*.md
+            !ui/node_modules
+            !LICENSE.md
+            !pkg/web/openapi/**
+            !.github/*.md
+

.markdownlint.yml

@@ -0,0 +1,45 @@
+code-block-style:
+  style: fenced
+
+code-fence-style:
+  style: backtick
+
+emphasis-style:
+  style: underscore
+
+strong-style:
+  style: asterisk
+
+fenced-code-language:
+  language_only: true
+
+heading-style:
+  style: atx
+
+hr-style:
+  style: "---"
+
+line-length:
+  line_length: 120
+  code_blocks: false
+  tables: false
+
+no-duplicate-heading:
+  siblings_only: true
+
+ol-prefix:
+  style: ordered
+
+ul-style:
+  style: dash
+
+no-hard-tabs:
+  # allow hard tabs in Go code blocks
+  ignore_code_languages: [go]
+  spaces_per_tab: 2
+
+proper-names:
+  code_blocks: false
+  names:
+    - JavaScript
+    - Conduit

CONTRIBUTING.md

@@ -4,6 +4,7 @@ Thank you so much for contributing to Conduit. We appreciate your time and help!
 As a contributor, here are the guidelines we would like you to follow.
 
 ## Asking questions
+
 If you have a question or you are not sure how to do something, please
 [open a discussion](https://github.com/ConduitIO/conduit/discussions) or hit us up
 on [Discord](https://discord.meroxa.com)!
@@ -14,41 +15,44 @@ on [Discord](https://discord.meroxa.com)!
    [issues](https://github.com/ConduitIO/conduit/issues) to see if a
    similar one was already opened. If there is one already opened, feel free
    to comment on it.
-1. Otherwise, please [open an issue](https://github.com/ConduitIO/conduit/issues/new) 
+2. Otherwise, please [open an issue](https://github.com/ConduitIO/conduit/issues/new)
    and let us know, and make sure to include the following:
-   * If it's a bug, please include: 
-     * Steps to reproduce
-     * Copy of the logs.
-     * Your Conduit version.
-   * If it's a feature request, let us know the motivation behind that feature,
+   - If it's a bug, please include:
+     - Steps to reproduce
+     - Copy of the logs.
+     - Your Conduit version.
+   - If it's a feature request, let us know the motivation behind that feature,
       and the expected behavior of it.
 
 ## Submitting changes
+
 We also value contributions in form of pull requests. When opening a PR please ensure:
+
 - You have followed the [Code Guidelines](https://github.com/ConduitIO/conduit/blob/main/docs/code_guidelines.md).
 - There is no other [pull request](https://github.com/ConduitIO/conduit/pulls) for the same update/change.
 - You have written unit tests.
 - You have made sure that the PR is of reasonable size and can be easily reviewed.
 
 Also, if you are submitting code, please ensure you have adequate tests for the feature,
 and that all the tests still run successfully.
-   * Unit tests can be run via `make test`.
-   * Integration tests can be run via `make test-integration`, they require
-     [Docker](https://www.docker.com/) to be installed and running. The tests will
-     spin up required docker containers, run the integration tests and stop the
-     containers afterwards.
+
+- Unit tests can be run via `make test`.
+- Integration tests can be run via `make test-integration`, they require
+  [Docker](https://www.docker.com/) to be installed and running. The tests will
+  spin up required docker containers, run the integration tests and stop the
+  containers afterwards.
 
 We would like to ask you to use the provided Git hooks (by running `git config core.hooksPath githooks`),
 which automatically run the tests and the linter when pushing code.
 
 ### Quick steps to contribute
 
 1. Fork the project
-2. Download your fork to your machine 
+2. Download your fork to your machine
 3. Create your feature branch (`git checkout -b my-new-feature`)
-4. Make changes and run tests 
-5. Commit your changes 
-6. Push to the branch 
+4. Make changes and run tests
+5. Commit your changes
+6. Push to the branch
 7. Create new pull request
 
 ## License
@@ -60,4 +64,4 @@ Apache 2.0, see [LICENSE](LICENSE.md).
 Conduit has adopted [Contributor Covenant](https://www.contributor-covenant.org/)
 as its [Code of Conduct](https://github.com/ConduitIO/.github/blob/main/CODE_OF_CONDUCT.md).
 We highly encourage contributors to familiarize themselves with the standards we want our
-community to follow and help us enforce them.
+community to follow and help us enforce them.

Makefile

@@ -1,4 +1,4 @@
-.PHONY: test test-integration build run proto-update proto-lint clean download install-tools generate check-go-version
+.PHONY: test test-integration build run proto-update proto-lint clean download install-tools generate check-go-version markdown-lint
 
 # Version will extract the current version of Conduit based on
 # the latest git tag and commit. If the repository contains any
@@ -72,3 +72,6 @@ check-go-version:
 		echo "${GO_VERSION_CHECK}";\
 		exit 1;\
 	fi
+
+markdown-lint:
+	markdownlint-cli2 "**/*.md" "#ui/node_modules" "#LICENSE.md" "#pkg/web/openapi/**" "#.github/*.md"

README.md

@@ -39,7 +39,6 @@ Conduit was created and open-sourced by [Meroxa](https://meroxa.io).
 - [API](#api)
 - [UI](#ui)
 - [Documentation](#documentation)
-- [Known limitations](#known-limitations)
 - [Contributing](#contributing)
 
 ## Quick start
@@ -50,23 +49,29 @@ Conduit was created and open-sourced by [Meroxa](https://meroxa.io).
    the [example pipeline](/examples/pipelines/file-to-file.yml)
    and put it in the directory named `pipelines` in the same directory as the
    Conduit binary.
-3. Run conduit (`./conduit`). The example pipeline will start automatically.
+3. Run Conduit (`./conduit`). The example pipeline will start automatically.
 4. Write something to file `example.in` in the same directory as the Conduit
    binary.
+
+   ```sh
+   echo "hello conduit" >> example.in`
    ```
-   $ echo "hello conduit" >> example.in`
-   ```
+
 5. Read the contents of `example.out` and notice an OpenCDC record:
-   ```
+
+   ```sh
    $ cat example.out
    {"position":"MTQ=","operation":"create","metadata":{"file.path":"./example.in","opencdc.readAt":"1663858188836816000","opencdc.version":"v1"},"key":"MQ==","payload":{"before":null,"after":"aGVsbG8gY29uZHVpdA=="}}
    ```
+
 6. The string `hello conduit` is a base64 encoded string stored in the field
    `payload.after`, let's decode it:
-   ```
+
+   ```sh
    $ cat example.out | jq ".payload.after | @base64d"
    "hello conduit"
    ```
+
 7. Explore the UI by opening `http://localhost:8080` and build your own
    pipeline!
 
@@ -78,7 +83,7 @@ Download a pre-built binary from
 the [latest release](https://github.com/conduitio/conduit/releases/latest) and
 simply run it!
 
-```
+```sh
 ./conduit
 ```
 
@@ -95,11 +100,11 @@ of available options, run `./conduit --help`.
 
 Requirements:
 
-* [Go](https://golang.org/) (1.20 or later)
-* [Node.js](https://nodejs.org/) (16.x)
-* [Yarn](https://yarnpkg.com/) (latest 1.x)
-* [Ember CLI](https://ember-cli.com/)
-* [Make](https://www.gnu.org/software/make/)
+- [Go](https://golang.org/) (1.20 or later)
+- [Node.js](https://nodejs.org/) (16.x)
+- [Yarn](https://yarnpkg.com/) (latest 1.x)
+- [Ember CLI](https://ember-cli.com/)
+- [Make](https://www.gnu.org/software/make/)
 
 ```shell
 git clone git@github.com:ConduitIO/conduit.git
@@ -118,7 +123,7 @@ running Conduit as a simple backend service.
 Our Docker images are hosted on GitHub's Container Registry. To run the latest
 Conduit version, you should run the following command:
 
-```
+```sh
 docker run -p 8080:8080 ghcr.io/conduitio/conduit:latest
 ```
 
@@ -211,20 +216,20 @@ For more information about the UI refer to the [Readme](ui/README.md) in `/ui`.
 ## Documentation
 
 To learn more about how to use Conduit
-visit [docs.conduit.io](https://docs.conduit.io).
+visit [docs.Conduit.io](https://docs.conduit.io).
 
 If you are interested in internals of Conduit we have prepared some technical
 documentation:
 
-* [Pipeline Semantics](docs/pipeline_semantics.md) explains the internals of how
+- [Pipeline Semantics](docs/pipeline_semantics.md) explains the internals of how
   a Conduit pipeline works.
-* [Pipeline Configuration Files](docs/pipeline_configuration_files.md)
+- [Pipeline Configuration Files](docs/pipeline_configuration_files.md)
   explains how you can define pipelines using YAML files.
-* [Processors](docs/processors.md) contains examples and more information about
+- [Processors](docs/processors.md) contains examples and more information about
   Conduit processors.
-* [Conduit Architecture](docs/architecture.md)
+- [Conduit Architecture](docs/architecture.md)
   will give you a high-level overview of Conduit.
-* [Conduit Metrics](docs/metrics.md)
+- [Conduit Metrics](docs/metrics.md)
   provides more information about how Conduit exposes metrics.
 
 ## Contributing

docs/architecture-decision-records/20220121-conduit-plugin-architecture.md

@@ -36,7 +36,7 @@ The decision can be broken up into 4 parts, these are explained in detail later
 ### Conduit plugin interface (gRPC)
 
 The Conduit plugin interface is defined in gRPC, is standalone (does not depend on Conduit or the SDK) and lives
-in https://github.com/conduitio/connector-plugin. This repository is the only common thing between Conduit and a plugin,
+in <https://github.com/conduitio/connector-plugin>. This repository is the only common thing between Conduit and a plugin,
 meaning that Conduit uses the interface to interact with plugins and plugins implement the interface.
 
 The proto files define the messages and gRPC interface that needs to be implemented by the connector plugin. The
@@ -68,10 +68,10 @@ Functions will be called in the order in which they are defined.
 
 - `Configure` - the plugin needs to validate the configuration it receives and either store the configuration and return
   no error or discard it and return an error explaining why the configuration is invalid. This function serves two purposes:
-    - Config validation - Conduit calls `Configure` when the connector is first created or when the configuration is
-      updated to validate the configuration. In this case the next call is `Teardown` and the plugin is stopped.
-    - Configuring the plugin - Conduit calls `Configure` when the pipeline is started to provide the plugin with its
-      config. The next call after a successful response is `Start`.
+  - Config validation - Conduit calls `Configure` when the connector is first created or when the configuration is
+    updated to validate the configuration. In this case the next call is `Teardown` and the plugin is stopped.
+  - Configuring the plugin - Conduit calls `Configure` when the pipeline is started to provide the plugin with its
+    config. The next call after a successful response is `Start`.
 - `Start` - with a call to this function Conduit signals to the plugin that it wants it to start running. The request
   will contain the position at which the plugin should start running (the position might be empty in case the pipeline
   is started for the first time). The plugin is expected to open any connections needed to fetch records. In case of a
@@ -113,7 +113,7 @@ Functions will be called in the order in which they are defined.
   independent and are able to transmit data concurrently. The plugin is expected to send an acknowledgment back to
   Conduit for every record it received, even if the record was not processed successfully (in that case the
   acknowledgment should contain the error). The stream should stay open until either an error occurs or the `Stop`
-  function is called *and* all remaining acknowledgments are sent (this is handled by the SDK).
+  function is called _and_ all remaining acknowledgments are sent (this is handled by the SDK).
 - `Stop` - Conduit signals to the plugin that there be no more records written to the request stream in `Run`. The
   plugin needs to flush any records that are cached in memory, send back the acknowledgments and stop the `Run`
   function.
@@ -166,11 +166,11 @@ things to point out
 - The bidirectional stream method `Run` is broken down into two separate methods, one for receiving messages from the
   stream and one to send messages. Those methods can only be called after a call to `Start` since that is the method in
   which the stream actually gets opened.
-    - In `SourcePlugin` we can read records from the stream by calling `Read`. This method will block until either an
-      error occurs or a new record is produced by the plugin. Successfully processed records can be acknowledged by
-      calling `Ack` with the corresponding record position.
-    - In `DestinationPlugin` we can write records to the stream by calling `Write`. To receive acknowledgments we can
-      call `Ack` which will block until either an error occurs or an acknowledgment is produced by the plugin.
+  - In `SourcePlugin` we can read records from the stream by calling `Read`. This method will block until either an
+    error occurs or a new record is produced by the plugin. Successfully processed records can be acknowledged by
+    calling `Ack` with the corresponding record position.
+  - In `DestinationPlugin` we can write records to the stream by calling `Write`. To receive acknowledgments we can
+    call `Ack` which will block until either an error occurs or an acknowledgment is produced by the plugin.
 
 ### Plugin registries
 
@@ -207,7 +207,7 @@ The plugin registry is the last missing piece that contains information about th
 ```protobuf
 type registry interface {
   New(logger log.CtxLogger, name string) (Dispenser, error)
-    }
+}
 ```
 
 Behind this interface, there are again two registries that contain either built-in or standalone dispensers. To