.github: Add markdownlint

This adds a linter to catch common markdown formatting errors.
The linter used is markdownlint-cli2 which is available on all platforms
and has an associated Github Action to automate these checks in CI.

Configuration is checked in at .markdownlint-cli2.yaml.

You may run the check locally using `markdownlint-cli2`.
Or you may install the extension for VSCode:
DavidAnson.vscode-markdownlint

Signed-off-by: Dave Tucker <dave@dtucker.co.uk>

.github/workflows/ci.yml

@@ -35,8 +35,12 @@ jobs:
 
       - name: Check C formatting
         run: git ls-files -- '*.c' '*.h' | xargs clang-format --dry-run --Werror
+      
+      - name: Check Markdown
+        uses: DavidAnson/markdownlint-cli2-action@v9
 
-      - run: taplo fmt --check
+      - name: Check TOML formatting
+        run: taplo fmt --check
 
       - name: Check formatting
         run: cargo fmt --all -- --check

.markdownlint-cli2.yaml

@@ -0,0 +1,8 @@
+config:
+  no-duplicate-heading: false
+
+globs:
+  - "**/*.md"
+ignores:
+  - "target/**/*"
+  - "xtask/libbpf/**/*"

CODE_OF_CONDUCT.md

@@ -115,14 +115,14 @@ the community.
 ## Attribution
 
 This Code of Conduct is adapted from the [Contributor Covenant][homepage],
-version 2.0, available at
+version 2.0, available [here][covenant-2-0].
-https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
 
 Community Impact Guidelines were inspired by [Mozilla's code of conduct
 enforcement ladder](https://github.com/mozilla/diversity).
 
 [homepage]: https://www.contributor-covenant.org
+[covenant-2-0]: https://www.contributor-covenant.org/version/2/0/code_of_conduct
 
-For answers to common questions about this code of conduct, see the FAQ at
+For answers to common questions about this code of conduct, see the
-https://www.contributor-covenant.org/faq. Translations are available at
+[FAQ](https://www.contributor-covenant.org/faq). Translations are available
-https://www.contributor-covenant.org/translations.
+[here](https://www.contributor-covenant.org/translations).

CONTRIBUTING.md

@@ -17,12 +17,16 @@ version of aya you're using and which version of the linux kernel.
 
 If you find an API that is not documented, unclear or missing examples, please
 file an issue. If you make changes to the documentation, please read
-https://doc.rust-lang.org/rustdoc/how-to-write-documentation.html and make sure
+[How To Write Documentation] and make sure your changes conform to the
-your changes conform to the format outlined here
+format outlined in [Documenting Components].
-https://doc.rust-lang.org/rustdoc/how-to-write-documentation.html#documenting-components.
 
-If you want to make changes to the Aya Book, see the readme in the book repo
+[How To Write Documentation]: https://doc.rust-lang.org/rustdoc/how-to-write-documentation.html
-https://github.com/aya-rs/book.
+[Documenting Components]: https://doc.rust-lang.org/rustdoc/how-to-write-documentation.html#documenting-components
+
+If you want to make changes to the Aya Book, see the readme in the
+[book repository].
+
+[book repository]: https://github.com/aya-rs/book
 
 ## Fixing bugs and implementing new features
 
@@ -31,7 +35,11 @@ helps us avoid duplicating work. If your work includes publicly visible changes,
 make sure those are properly documented as explained in the section above.
 
 ### Running tests
-Run the unit tests with `cargo test`. See [Aya Integration Tests](https://github.com/aya-rs/aya/blob/main/test/README.md) regarding running the integration tests.
+
+Run the unit tests with `cargo test`. See [Aya Integration Tests] regarding
+running the integration tests.
+
+[Aya Integration Tests]: https://github.com/aya-rs/aya/blob/main/test/README.md
 
 ### Commits
 
@@ -45,21 +53,19 @@ change, please squash those together before asking for a review.
 A good commit message should describe what changed and why.
 
 1. The first line should:
-
+    - Contain a short description of the change (preferably 50 characters or less,
-  * contain a short description of the change (preferably 50 characters or less,
+      and no more than 72 characters)
-    and no more than 72 characters)
+    - Be entirely in lowercase with the exception of proper nouns, acronyms, and
-  * be entirely in lowercase with the exception of proper nouns, acronyms, and
+      the words that refer to code, like function/variable names
-    the words that refer to code, like function/variable names
+    - Be prefixed with the name of the sub crate being changed
-  * be prefixed with the name of the sub crate being changed
+
-
+    Examples:
-  Examples:
+    - `aya: handle reordered functions`
-
+    - `aya-bpf: SkSkbContext: add ::l3_csum_replace`
-  * aya: handle reordered functions
+
-  * aya-bpf: SkSkbContext: add ::l3_csum_replace
+1. Keep the second line blank.
-
+1. Wrap all other lines at 72 columns (except for long URLs).
-2. Keep the second line blank.
+1. If your patch fixes an open issue, you can add a reference to it at the end
-3. Wrap all other lines at 72 columns (except for long URLs).
-4. If your patch fixes an open issue, you can add a reference to it at the end
    of the log. Use the `Fixes: #` prefix and the issue number. For other
    references use `Refs: #`. `Refs` may include multiple issues, separated by a
    comma.

README.md

@@ -5,7 +5,6 @@
 [![Build status][build-badge]][build-url]
 [![Book][book-badge]][book-url]
 
-
 [crates-badge]: https://img.shields.io/crates/v/aya.svg?style=for-the-badge&logo=rust
 [crates-url]: https://crates.io/crates/aya
 [license-badge]: https://img.shields.io/badge/license-MIT%2FApache--2.0-blue?style=for-the-badge
@@ -27,8 +26,8 @@
 
 [![Discord][discord-badge]][chat-url] [![Awesome][awesome-badge]][awesome-aya]
 
-Join [the conversation on Discord][chat-url] to discuss anything related to Aya, or discover
+Join [the conversation on Discord][chat-url] to discuss anything related to Aya
-and contribute to a list of [Awesome Aya][awesome-aya] projects.
+or discover and contribute to a list of [Awesome Aya][awesome-aya] projects.
 
 [discord-badge]: https://img.shields.io/badge/Discord-chat-5865F2?style=for-the-badge&logo=discord
 [chat-url]: https://discord.gg/xHW2cb2N6G
@@ -38,7 +37,7 @@ and contribute to a list of [Awesome Aya][awesome-aya] projects.
 ## Overview
 
 eBPF is a technology that allows running user-supplied programs inside the Linux
-kernel. For more info see https://ebpf.io/what-is-ebpf.
+kernel. For more info see [What is eBBF](https://ebpf.io/what-is-ebpf).
 
 Aya is an eBPF library built with a focus on operability and developer
 experience. It does not rely on [libbpf] nor [bcc] - it's built from the ground
@@ -70,9 +69,8 @@ Some of the major features provided include:
 
 ### Example
 
-Aya supports a large chunk of the eBPF API. The following example shows how to use a
+Aya supports a large chunk of the eBPF API. The following example shows how to
-`BPF_PROG_TYPE_CGROUP_SKB` program with aya:
+use a `BPF_PROG_TYPE_CGROUP_SKB` program with aya:
-
 
 ```rust
 use std::fs::File;
@@ -97,12 +95,15 @@ ingress.attach(cgroup, CgroupSkbAttachType::Ingress)?;
 ## Contributing
 
 Please see the [contributing guide](https://github.com/aya-rs/aya/blob/main/CONTRIBUTING.md).
+
 ## License
 
-Aya is distributed under the terms of either the [MIT license] or the [Apache License] (version
+Aya is distributed under the terms of either the [MIT license] or the
-2.0), at your option.
+[Apache License] (version 2.0), at your option.
 
-Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this crate by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.
+Unless you explicitly state otherwise, any contribution intentionally submitted
+for inclusion in this crate by you, as defined in the Apache-2.0 license, shall
+be dual licensed as above, without any additional terms or conditions.
 
 [MIT license]: https://github.com/aya-rs/aya/blob/main/LICENSE-MIT
 [Apache license]: https://github.com/aya-rs/aya/blob/main/LICENSE-APACHE

aya/README.md

@@ -5,11 +5,10 @@
 ![Build status][build-badge]
 [![Book][book-badge]][book-url]
 
-
 [crates-badge]: https://img.shields.io/crates/v/aya.svg?style=for-the-badge&logo=rust
 [crates-url]: https://crates.io/crates/aya
 [license-badge]: https://img.shields.io/badge/license-MIT%2FApache--2.0-blue?style=for-the-badge
-[build-badge]: https://img.shields.io/github/workflow/status/aya-rs/aya/build-aya?style=for-the-badge&logo=github
+[build-badge]: https://img.shields.io/github/actions/workflow/status/aya-rs/aya/build-aya.yml?branch=main&style=for-the-badge
 [book-badge]: https://img.shields.io/badge/read%20the-book-9cf.svg?style=for-the-badge&logo=mdbook
 [book-url]: https://aya-rs.dev/book
 
@@ -26,8 +25,8 @@
 
 [![Discord][discord-badge]][chat-url] [![Awesome][awesome-badge]][awesome-aya]
 
-Join [the conversation on Discord][chat-url] to discuss anything related to Aya, or discover
+Join [the conversation on Discord][chat-url] to discuss anything related to Aya
-and contribute to a list of [Awesome Aya][awesome-aya] projects.
+or discover and contribute to a list of [Awesome Aya][awesome-aya] projects.
 
 [discord-badge]: https://img.shields.io/badge/Discord-chat-5865F2?style=for-the-badge&logo=discord
 [chat-url]: https://discord.gg/xHW2cb2N6G
@@ -37,7 +36,7 @@ and contribute to a list of [Awesome Aya][awesome-aya] projects.
 ## Overview
 
 eBPF is a technology that allows running user-supplied programs inside the Linux
-kernel. For more info see https://ebpf.io/what-is-ebpf.
+kernel. For more info see [What is eBBF](https://ebpf.io/what-is-ebpf).
 
 Aya is an eBPF library built with a focus on operability and developer
 experience. It does not rely on [libbpf] nor [bcc] - it's built from the ground
@@ -69,9 +68,8 @@ Some of the major features provided include:
 
 ### Example
 
-Aya supports a large chunk of the eBPF API. The following example shows how to use a
+Aya supports a large chunk of the eBPF API. The following example shows how to
-`BPF_PROG_TYPE_CGROUP_SKB` program with aya:
+use a `BPF_PROG_TYPE_CGROUP_SKB` program with aya:
-
 
 ```rust
 use std::fs::File;
@@ -96,12 +94,15 @@ ingress.attach(cgroup, CgroupSkbAttachType::Ingress)?;
 ## Contributing
 
 Please see the [contributing guide](https://github.com/aya-rs/aya/blob/main/CONTRIBUTING.md).
+
 ## License
 
-Aya is distributed under the terms of either the [MIT license] or the [Apache License] (version
+Aya is distributed under the terms of either the [MIT license] or the
-2.0), at your option.
+[Apache License] (version 2.0), at your option.
 
-Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this crate by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.
+Unless you explicitly state otherwise, any contribution intentionally submitted
+for inclusion in this crate by you, as defined in the Apache-2.0 license, shall
+be dual licensed as above, without any additional terms or conditions.
 
 [MIT license]: https://github.com/aya-rs/aya/blob/main/LICENSE-MIT
 [Apache license]: https://github.com/aya-rs/aya/blob/main/LICENSE-APACHE

bpf/aya-bpf-cty/README.md

@@ -1,17 +1,16 @@
+# `cty`
+
 [![crates.io](https://img.shields.io/crates/v/cty.svg)](https://crates.io/crates/cty)
 [![crates.io](https://img.shields.io/crates/d/cty.svg)](https://crates.io/crates/cty)
 
-# `cty`
-
 > Type aliases to C types like c_int for use with bindgen
 
 ## License
 
 Licensed under either of
 
-- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or
+- Apache License, Version 2.0 [LICENSE-APACHE](./LICENSE-APACHE) or
-  http://www.apache.org/licenses/LICENSE-2.0)
+- MIT license [LICENSE-MIT](./LICENSE-MIT)
-- MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)
 
 at your option.
 

test/README.md

@@ -1,5 +1,4 @@
-Aya Integration Tests
+# Aya Integration Tests
-=====================
 
 The aya integration test suite is a set of tests to ensure that
 common usage behaviours work on real Linux distros
@@ -19,13 +18,13 @@ From the root of this repository:
 
 ### Native
 
-```
+```bash
 cargo xtask integration-test local
 ```
 
 ### Virtualized
 
-```
+```bash
 cargo xtask integration-test vm
 ```
 
@@ -41,5 +40,5 @@ Tests should follow these guidelines:
   constants in `integration-test/src/lib.rs` using `include_bytes_aligned!`.
 - Tests should be added to `integration-test/tests`.
 - You may add a new module, or use an existing one.
-- Test functions should not return `anyhow::Result<()>` since this produces errors without stack
+- Test functions should not return `anyhow::Result<()>` since this produces
-  traces. Prefer to `panic!` instead.
+  errors without stack traces. Prefer to `panic!` instead.