lint: use markdownlint-cli2 instead of ruby markdownlint

Use Node.js-based github.com/DavidAnson/markdownlint-cli2,
replacing the ruby-based github.com/markdownlint/markdownlint.
This tool has a cleaner configuration file and that is well
supported in vs code and other editors.

Adapted from scionproto#4328.

Co-authored-by: Dominik Roos <roos@anapaya.net>

.github/ISSUE_TEMPLATE/01-proposal.md

@@ -8,4 +8,3 @@ labels: i/proposal
 Our proposal process is documented here:
 https://docs.scion.org/en/latest/dev/contribute.html#change-proposal-process
 -->
-

.markdownlint-cli2.jsonc

@@ -0,0 +1,27 @@
+{
+ "globs": ["**/*.md"],
+ "ignores": [
+ "**/venv/**",
+ "**/_build/**",
+ "**/node_modules/**",
+ "licenses/data/**",
+ "tools/coremark/LICENSE.md"
+ ],
+ "config": {
+ "default": true,
+ "MD007": {
+ "indent": 4
+ },
+ "MD013": {
+ "line_length": 100,
+ "code_blocks": false,
+ "tables": false
+ },
+ "MD024": {
+ "siblings_only": true
+ }
+ },
+ "outputFormatters": [
+ [ "markdownlint-cli2-formatter-pretty", { "appendLink": true } ]
+ ]
+}

Makefile

@@ -153,5 +153,5 @@ lint-doc: lint-doc-mdlint
 
 lint-doc-mdlint:
  $(info ==> $@)
- @FILES=$$(find -type f -iname '*.md' -not -path "./private/mgmtapi/tools/node_modules/*" -not -path "./.github/**/*" | grep -vf tools/md/skipped); \
- docker run --rm -v ${PWD}:/data -v ${PWD}/tools/md/mdlintstyle.rb:/style.rb $$(docker build -q tools/md) $${FILES} -s /style.rb
+ @if [ -t 1 ]; then tty=true; else tty=false; fi; \
+ tools/quiet docker run --tty=$$tty --rm -v ${PWD}:/workdir davidanson/markdownlint-cli2:v0.12.1

doc/.markdownlint-cli2.jsonc

@@ -0,0 +1,11 @@
+{
+ "extends": "../.markdownlint-cli2.jsonc",
+ "config": {
+ "MD033": {
+ "allowed_elements": [
+ "a",
+ "sub"
+ ]
+ }
+ }
+}

doc/dev/design/BeaconService.md

@@ -4,7 +4,8 @@
 * Status: **outdated**
 
 ---
-⚠️ **NOTE** ⚠️<br/>
+⚠️ **NOTE** ⚠️
+
 Outdated contents! This document is kept for historical purpose.
 
 ---

doc/dev/design/ColibriService.md

@@ -9,7 +9,8 @@
 * Discussion at: [#3653](https://github.com/scionproto/scion/issues/3653), [#3794](https://github.com/scionproto/scion/issues/3794)
 
 ---
-⚠️ **NOTE** ⚠️<br/>
+⚠️ **NOTE** ⚠️
+
 Outdated contents! This document is kept for historical purpose.
 
 ---
@@ -91,7 +92,7 @@ next AS after AS<sub>i</sub> in the path of the reservation.
 
 1. The *COS* store is queried to admit the segment reservation.
 1. The store decides the admission for the reservation (how much bandwidth). It uses the
- _traffic_matrix_ from the configuration package.
+ *traffic_matrix* from the configuration package.
 1. The store saves an intermediate reservation entry in the DB.
 1. If this AS is the last one in the path, the *COS* store saves the reservation as final
  and notifies the previous AS in the path with a reservation response.
@@ -105,7 +106,7 @@ ASes. Whenever that configuration changes, the service should be notified.
 1. The service triggers the creation of a new segment reservation at boot time and whenever
  the segment reservation configuration file changes.
 1. The service reads the configuration file and creates a segment reservation request per each entry.
- * The path used in the request must be obtained using the _path predicate_ in the configuration.
+ * The path used in the request must be obtained using the *path predicate* in the configuration.
 1. The store in the *COS* saves the intermediate request and sends the request to the next AS
  in the path.
 1. If there is a timeout, this store will send a cleanup request to the next AS in the path.

doc/dev/design/EPIC.md

@@ -102,7 +102,7 @@ meaningful level of security:
 
 ### Example
 
-![](fig/EPIC/path-type-filtering-small.png).
+![path type filtering figure](fig/EPIC/path-type-filtering-small.png).
 
 Here, AS 6 is the AS protected by the hidden path (blue lines). The
 hidden path terminates at AS 6 (represented by black dot), so AS 6
@@ -182,8 +182,7 @@ not apply any filtering for traffic from interface 2 to interface 1.
 
 There are two main applications for EPIC-HP:
 
-<a id="HighlySecureHiddenPaths"></a>
-### Highly Secure Hidden Paths
+### <a id="HighlySecureHiddenPaths"></a> Highly Secure Hidden Paths
 
 The last and penultimate ASes on the hidden path only allow EPIC-HP
 traffic on the interface pairs that affect the hidden path.
@@ -203,8 +202,7 @@ packets towards hosts in other ASes, but that those hosts can not
 send a response back if they do not have the necessary
 authenticators.
 
-<a id="DOSSecureHiddenPaths"></a>
-### DoS-Secure Hidden Paths
+### <a id="DOSSecureHiddenPaths"></a> DoS-Secure Hidden Paths
 
 The last and penultimate ASes on the hidden path allow EPIC-HP and
 other path types simultaneously, but prioritize traffic using the
@@ -222,9 +220,9 @@ authenticators to send back EPIC-HP traffic.
 
 ## References
 
-<a id="1">[1]</a>
-M. Legner, T. Klenze, M. Wyss, C. Sprenger, A. Perrig. (2020) <br>
-EPIC: Every Packet Is Checked in the Data Plane of a Path-Aware Internet <br>
+[^1]
+M. Legner, T. Klenze, M. Wyss, C. Sprenger, A. Perrig. (2020)\
+EPIC: Every Packet Is Checked in the Data Plane of a Path-Aware Internet\
 Proceedings of the USENIX Security Symposium
 [[Link]](https://netsec.ethz.ch/publications/papers/Legner_Usenix2020_EPIC.pdf)
 
@@ -233,7 +231,7 @@ Design Document for the Hidden Path Infrastructure
 [[Link]](/hidden-paths)
 
 <a id="3">[3]</a>
-T. Lee, C. Pappas, A. Perrig, V. Gligor, and Y. Hu. (2017) <br>
-The Case for In-Network Replay Suppression <br>
+T. Lee, C. Pappas, A. Perrig, V. Gligor, and Y. Hu. (2017)\
+The Case for In-Network Replay Suppression\
 Proceedings of the ACM Asia Conference on Computer and Communications Security
 [[Link]](https://netsec.ethz.ch/publications/papers/replay2017.pdf)

doc/dev/design/PathPolicy.md

@@ -42,10 +42,10 @@ Examples:
 
 A policy is defined by a policy object. It can have the following attributes:
 
-- [`extends`](#Extends) (list of extended policies)
-- [`acl`](#ACL) (list of HPs, preceded by `+` or `-`)
-- [`sequence`](#Sequence) (space separated list of HPs, may contain operators)
-- [`options`](#Options) (list of option policies)
+- [`extends`](#extends) (list of extended policies)
+- [`acl`](#acl) (list of HPs, preceded by `+` or `-`)
+- [`sequence`](#sequence) (space separated list of HPs, may contain operators)
+- [`options`](#options) (list of option policies)
  - `weight` (importance level, only valid under `options`)
  - `policy` (a policy object)
 
@@ -75,8 +75,8 @@ Planned:
 - `-` (deny predicate)
 
 The ACL can be used to deny (blacklist) or allow (whitelist) ISDs, ASes and IFs. A deny entry is of
-the following form `- ISD-AS#IF`, where the second part is a [HP](#HP). If a deny entry matches any
-hop on a path, the path is not allowed.
+the following form `- ISD-AS#IF`, where the second part is a [Hop Predicate](#hop-predicate-hp).
+If a deny entry matches any hop on a path, the path is not allowed.
 
 An allow entry uses `+` with a HP, ie. `+ ISD-AS#IF`. For a path to be allowed, every hop of the
 path must be allowed by the ACL. When using allow and deny entries in the same ACL, the first
@@ -113,7 +113,7 @@ Planned:
 - `!` (logical NOT)
 - `&` (logical AND)
 
-The sequence is a string of space separated HPs. The [operators](#Operators) can be used for
+The sequence is a string of space separated HPs. The [operators](#operators) can be used for
 advanced interface sequences.
 
 The following example specifies a path from any interface in AS _1-ff00:0:133_ to two subsequent
@@ -215,7 +215,8 @@ third option which denies only hops in AS _1-ff00:0:133_, is used.
 
 ## Path policies in path lookup
 
-⚠️ **NOTE** ⚠️<br/>
+⚠️ **NOTE** ⚠️
+
 Outdated contents! This section is kept for historical purpose.
 
 ---

doc/dev/design/PathService.md

@@ -4,7 +4,8 @@
 * Status: **outdated**
 
 ---
-⚠️ **NOTE** ⚠️<br/>
+⚠️ **NOTE** ⚠️
+
 Outdated contents! This document is kept for historical purpose.
 
 ---
@@ -15,11 +16,11 @@ The path service is implemented as part of the control server.
 
 We use the messenger to register request handlers. The following requests are handled:
 
-* __Path Registration:__ A handler for the path-registration request, only in core ASes.
-* __Path Requests:__ Two different types of `SegReq` are handled by separate handlers:
+* **Path Registration:** A handler for the path-registration request, only in core ASes.
+* **Path Requests:** Two different types of `SegReq` are handled by separate handlers:
  * local requests, coming over TCP.
  * requests from other path servers, over SCION/QUIC, only in core ASes.
-* __Path Revocation:__ A handler for the path-revocation message
+* **Path Revocation:** A handler for the path-revocation message
 
 ## Deletion of Expired Path Segments and Revocations
 

doc/manuals/control.rst

@@ -252,7 +252,7 @@ considers the following options.
  - use the `netsys-lab/scion-ca <https://github.com/netsys-lab/scion-ca>`_ SCION CA
  based on `smallstep's step-ca <https://github.com/smallstep/certificates>`_,
  - ask SCION vendors for proprietary CA implementations and offerings,
- - plug in your own CA service implementing the :file-ref:`spec/ca.gen.yaml` API.
+ - plug in your own CA service implementing the :file-ref:`spec/ca.gen.yml` API.
 
  .. option:: ca.service.address = <string>