docs: align markdown with repository policy and enforce it

.github/workflows/dev.yml

@@ -288,6 +288,13 @@ jobs:
         with:
           recipe: "actionlint"
 
+      - name: "markdownlint"
+        id: "markdownlint"
+        continue-on-error: true
+        uses: *just
+        with:
+          recipe: "markdownlint"
+
       - name: "license-headers"
         id: "license-headers"
         continue-on-error: true
@@ -305,6 +312,7 @@ jobs:
             zizmor=${{ steps.zizmor.outcome }}
             pinact=${{ steps.pinact.outcome }}
             actionlint=${{ steps.actionlint.outcome }}
+            markdownlint=${{ steps.markdownlint.outcome }}
             license-headers=${{ steps.license-headers.outcome }}
         run: |
           set -euo pipefail

.markdownlint.json

@@ -6,12 +6,11 @@
     "style": "backtick"
   },
   "emphasis-style": {
-    "allow_asterisk": true,
-    "allow_underscore": true
+    "style": "underscore"
   },
   "line-length": {
     "strict": false,
-    "line_length": 120,
+    "line_length": 160,
     "code_blocks": false
   },
   "link-image-style": {

README.md

@@ -21,9 +21,10 @@ of the Fabric.
 [nix]: https://nixos.org/download/#nix-install-linux
 [just]: https://github.com/casey/just
 
-
 > [!NOTE]
-> Ensure flakes are enabled (e.g. `experimental-features = nix-command flakes` in `~/.config/nix/nix.conf` for single-user installs, or `/etc/nix/nix.conf` for multi-user installs), or some commands will fail.
+> Ensure flakes are enabled
+> (e.g. `experimental-features = nix-command flakes` in `~/.config/nix/nix.conf` for single-user installs,
+> or `/etc/nix/nix.conf` for multi-user installs), or some commands will fail.
 
 ### Step 0. Clone the repository
 

default.nix

@@ -170,6 +170,7 @@ let
       kopium
       llvmPackages'.clang # you need the host compiler in order to link proc macros
       llvmPackages'.llvm # needed for coverage
+      markdownlint-cli2
       npins
       opengrep
       openssl

development/documentation/README.md

@@ -11,14 +11,18 @@ Design your documentation to be maintainable.
   If your code is incomprehensible then documentation won't fix it.
 - **Line breaks in between sentences** - This makes diffs easier to understand and discuss.
 - **Try to satisfy linting rules** - Ensure documentation is free of linting errors.
+  - Run `just markdownlint` to check, or `just markdownlint --fix` to repair the mechanical violations.
+    CI runs the same recipe.
   - The `.markdownlint.json` file may be adjusted if the rules proves overly restrictive, but try to avoid
     deactivating too many lints.
+  - The line length limit is deliberately loose (160) because it is a backstop, not the primary rule:
+    break lines between sentences first and let the limit catch only the rare over-long one.
 - **Prefer markdown shortcut links to inline links** - Use markdown shortcut syntax for links and images to make the
   documentation more readable and maintainable for humans.
   Inline links are disruptive to humans reading or editing the documentation as raw text.
   It is also easier to maintain the links when external resources change.
 
-  *Example*:
+  _Example_:
 
   ```markdown
   - This is an [inline markdown link example](https://www.markdownguide.org/basic-syntax/#links)

flow-filter/README.md

@@ -62,15 +62,15 @@ Rules are protocol-aware by encoding the packet's L4 protocol as the first ACL k
 - TCP/UDP rules match exactly (`mask 0xff`).
 - `L4Protocol::Any` wildcards the proto (`mask 0x00`), so non-TCP/UDP packets only match `Any` rules.
 
-Stateful-NAT exposes get special treatment while building, because only the *forward*
+Stateful-NAT exposes get special treatment while building, because only the _forward_
 direction of their sessions can be answered from config alone:
 
 - **local end** excludes port-forwarding exposes (`can_init_connection()`): a
   port-forwarding source cannot initiate, and a covering expose (e.g. masquerade) must
-  answer for connection initiation from that range. Reply traffic *from* a
+  answer for connection initiation from that range. Reply traffic _from_ a
   port-forwarding-only source surfaces as a distinct stage-2 miss (`SourceMiss`), which
   the NF resolves against the packet's established flow.
-- **remote end** keeps masquerade exposes, but only as *markers*: a masquerade
+- **remote end** keeps masquerade exposes, but only as _markers_: a masquerade
   destination cannot accept new connections, so the NF lets a masquerade verdict through
   only when the packet rides an established masquerade flow (reply traffic); otherwise it
   drops. The marker is what distinguishes that reply traffic from a destination no

interface-manager/src/tc/README.md

@@ -22,10 +22,12 @@ erDiagram
 ### qdisc
 
 **A `qdisc` is short for queuing discipline**.
-There are many different algorithms for queueing packets, but the non-trivial case pretty much exclusively focuses on _the order in which packets **egress**_ a network card.
+There are many different algorithms for queueing packets,
+but the non-trivial case pretty much exclusively focuses on _the order in which packets **egress**_ a network card.
 
 `qdisc` also applies to ingress traffic, but in a much more trivial sense.
-You can't really control the order or timing in which packets arrive, so the ingress `qdisc` is mostly just a place to attach [filters], [chains], and (optionally) [block]s.
+You can't really control the order or timing in which packets arrive,
+so the ingress `qdisc` is mostly just a place to attach [filters], [chains], and (optionally) [block]s.
 
 In general, `qdisc`s are quite complex and powerful, but we only need the "trivial" case (ingress) for our current design.
 Our ingress qdisc of choice is called clsact; basically FIFO but with the ability to attach (potentially offloaded) [filter]s rules.
@@ -48,24 +50,36 @@ In such cases, a packet must match all listed criteria to trigger the [action]s.
 
 An action is some type of manipulation or event that may occur when a packet matches on a [filter] criteria.
 
-Examples of action include 
+Examples of actions include
 
-* dropping packets, 
-* editing source or destination ip addresses, 
-* pushing or popping VLAN headers, 
-* redirecting the packet to the ingress or egress pipeline of another network device,
-* encapsulating the packet in a VXLAN packet,
-* or mirroring (copying) the packet to another network device.
+- dropping packets,
+- editing source or destination ip addresses,
+- pushing or popping VLAN headers,
+- redirecting the packet to the ingress or egress pipeline of another network device,
+- encapsulating the packet in a VXLAN packet,
+- or mirroring (copying) the packet to another network device.
 
 Actions are reference counted and **may be attached to more than one filter.**
 More specifically, each action has four important variables associated with it
 
-1. The action `kind`.  `kind` is a static string which identifies the family of the action.  Examples include `mirred`, which covers packet redirect and mirroring; `gact`, which includes actions like `drop` or `jump`; and `tunnel_key`, which includes encapsulation and decapsulation actions.  Many other families of actions exist in the linux `tc` subsystem.
-2. The action `index`.  `index`, is a unique (_per `kind`_) identifier to track the specific incidence of a given action.  For example, if you might create a `gact` dro action with index 17.  You may then attach that drop command to several different filters by referencing that index on filter creation.  If you recycle an action in this way then all the filters associated with that action will update the hit counters for that action.  Reuse of actions in this way may also save resources in the network card (assuming the matches and action can be offloaded).
-3. The action `bindcnt`.  This is the number of active filters which reference this action.
-4. The action `refcnt`.  This is the reference count of the action.  This number is either equal to the `bindcnt` or is equal to the `bindcnt` plus one.
-
-If you create an action as part of a filter creation command, then you the `refcnt` and the `bindcnt` numbers will be equal.
+1. The action `kind`.
+   `kind` is a static string which identifies the family of the action.
+   Examples include `mirred`, which covers packet redirect and mirroring; `gact`, which includes actions like `drop` or `jump`;
+   and `tunnel_key`, which includes encapsulation and decapsulation actions.
+   Many other families of actions exist in the linux `tc` subsystem.
+2. The action `index`.
+   `index`, is a unique (_per `kind`_) identifier to track the specific incidence of a given action.
+   For example, if you might create a `gact` drop action with index 17.
+   You may then attach that drop command to several different filters by referencing that index on filter creation.
+   If you recycle an action in this way then all the filters associated with that action will update the hit counters for that action.
+   Reuse of actions in this way may also save resources in the network card (assuming the matches and action can be offloaded).
+3. The action `bindcnt`.
+   This is the number of active filters which reference this action.
+4. The action `refcnt`.
+   This is the reference count of the action.
+   This number is either equal to the `bindcnt` or is equal to the `bindcnt` plus one.
+
+If you create an action as part of a filter creation command, then the `refcnt` and the `bindcnt` numbers will be equal.
 If you create an action without attaching it to a filter, you need to set the `refcnt` to one (in which case the `bindcnt` will be zero automatically).
 
 Linux will automatically remove any action if and only if the `bindcnt` _and_ `refcnt` are equal to zero.
@@ -93,9 +107,13 @@ If you configure `tc` [filter]s in the most basic way, you may need to install t
 
 This is bad for a few major reasons:
 
-1. It is pointlessly complex.  You would need to keep track of all 10 rules.  You need to create it 10 times, delete it 10 times, update it 10 times, track the counters 10 times, and so on.
-2. It is wasteful of resources in the ASIC.  Installing the rule into the hardware once saves TCAM or SRAM in the ASIC (both of which are in limited supply).
-3. It is more prone to race conditions.  Updating the rule in one place is usually much easier to sequence when transitioning between rule sets.
+1. It is pointlessly complex.
+   You would need to keep track of all 10 rules.
+   You need to create it 10 times, delete it 10 times, update it 10 times, track the counters 10 times, and so on.
+2. It is wasteful of resources in the ASIC.
+   Installing the rule into the hardware once saves TCAM or SRAM in the ASIC (both of which are in limited supply).
+3. It is more prone to race conditions.
+   Updating the rule in one place is usually much easier to sequence when transitioning between rule sets.
 
 [action]: #action
 [block]: #block

justfile

@@ -415,6 +415,12 @@ actionlint:
     {{ _just_debuggable_ }}
     actionlint
 
+# Limit linting to tracked Markdown so generated files cannot affect CI.
+[script]
+markdownlint *args:
+    {{ _just_debuggable_ }}
+    git ls-files -z '*.md' | xargs -0 markdownlint-cli2 {{ args }}
+
 [script]
 license-headers:
     {{ _just_debuggable_ }}
@@ -461,6 +467,7 @@ lint: \
     (zizmor) \
     (pinact "--fix=false" "--no-api") \
     (actionlint) \
+    (markdownlint) \
     (license-headers)
     {{ _just_debuggable_ }}