[editorial] markdownlint in less then 1.5 sec (#193)

.github/workflows/checks.yml

@@ -20,7 +20,7 @@ jobs:
       run: make check-file-and-folder-names-in-docs
 
     - name: run markdownlint
-      run: make markdownlint
+      run: npx gulp lint-md
 
   yamllint:
     runs-on: ubuntu-latest

CONTRIBUTING.md

@@ -137,3 +137,5 @@ make misspell-correction
     - Add `## v{version} ({date})` under `## Unreleased`
   - Send staging tag as PR for review.
 - Create a tag `v{version}` on the merged PR and push remote.
+
+[nvm]: https://github.com/nvm-sh/nvm/blob/master/README.md#installing-and-updating

Makefile

@@ -65,6 +65,11 @@ markdown-toc:
 
 .PHONY: markdownlint
 markdownlint:
+	@if ! npm ls markdownlint; then npm install; fi
+	@npx gulp lint-md
+
+.PHONY: markdownlint-old
+markdownlint-old:
 	@if ! npm ls markdownlint; then npm install; fi
 	@for f in $(ALL_DOCS); do \
 		echo $$f; \

docs/general/general-attributes.md

@@ -326,8 +326,6 @@ Examples of where the `enduser.id` value is extracted from:
 | [JavaEE/JakartaEE Servlet] | `javax.servlet.http.HttpServletRequest.getUserPrincipal()` |
 | [Windows Communication Foundation] | `ServiceSecurityContext.Current.PrimaryIdentity` |
 
-[Authorization]: https://tools.ietf.org/html/rfc7235#section-4.2
-[OAuth 2.0 Access Token]: https://tools.ietf.org/html/rfc6749#section-3.3
 [SAML 2.0 Assertion]: http://docs.oasis-open.org/security/saml/Post2.0/sstc-saml-tech-overview-2.0.html
 [HTTP Basic/Digest Authentication]: https://tools.ietf.org/html/rfc2617
 [OAuth 2.0 Bearer Token]: https://tools.ietf.org/html/rfc6750

docs/general/trace-general.md

@@ -35,3 +35,5 @@ The following semantic conventions for spans are defined:
 Apart from semantic conventions for traces, [metrics](metrics-general.md), [logs](logs-general.md), and [events](events-general.md),
 OpenTelemetry also defines the concept of overarching [Resources](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/resource/sdk.md) with their own
 [Resource Semantic Conventions](/docs/resource/README.md).
+
+[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md

docs/rpc/rpc-metrics.md

@@ -131,8 +131,6 @@ To avoid high cardinality, implementations should prefer the most stable of `ser
 For client-side metrics `server.port` is required if the connection is IP-based and the port is available (it describes the server port they are connecting to).
 For server-side spans `server.port` is optional (it describes the port the client is connecting from).
 
-[network.transport]: /docs/general/general-attributes.md#network-attributes
-
 ### Service name
 
 On the server process receiving and handling the remote procedure call, the service name provided in `rpc.service` does not necessarily have to match the [`service.name`][] resource attribute.

docs/rpc/rpc-spans.md

@@ -131,7 +131,6 @@ This process could expose two RPC endpoints, one called `CurrencyQuotes` (= `rpc
 In this example, spans representing client request should have their `peer.service` attribute set to `QuoteService` as well to match the server's `service.name` resource attribute.
 Generally, a user SHOULD NOT set `peer.service` to a fully qualified RPC service name.
 
-[network attributes]: /docs/general/general-attributes.md#server-and-client-attributes
 [`service.name`]: /docs/resource/README.md#service
 [`peer.service`]: /docs/general/general-attributes.md#general-remote-service-attributes
 

gulpfile.js

@@ -0,0 +1,60 @@
+const gulp = require("gulp");
+const through2 = require("through2");
+const markdownlint = require("markdownlint");
+const yaml = require("js-yaml");
+const fs = require("fs");
+
+let fileCount = 0,
+  issueCount = 0;
+
+function markdownLintFile(file, encoding, callback) {
+  const config = yaml.load(fs.readFileSync("./.markdownlint.yaml", "utf8"));
+  const options = {
+    files: [file.path],
+    config: config,
+  };
+
+  markdownlint(options, function (err, result) {
+    if (err) {
+      console.error("ERROR occurred while running markdownlint: ", err);
+      return callback(err);
+    }
+
+    const _resultString = (result || "").toString();
+    // Result is a string with lines of the form:
+    //
+    //   <file-path>:\s*<line-number>: <ID-and-message>
+    //
+    // Strip out any whitespace between the filepath and line number
+    // so that tools can jump directly to the line.
+    const resultString = _resultString
+      .split("\n")
+      .map((line) => line.replace(/^([^:]+):\s*(\d+):(.*)/, "$1:$2:$3"))
+      .join("\n");
+    if (resultString) {
+      console.log(resultString);
+      issueCount++;
+    }
+    fileCount++;
+    callback(null, file);
+  });
+}
+
+function lintMarkdown() {
+  const markdownFiles = ["**/*.md", "!**/node_modules/**", "!**/.github/**"];
+
+  return gulp
+    .src(markdownFiles)
+    .pipe(through2.obj(markdownLintFile))
+    .on("end", () => {
+      console.log(
+        `Processed ${fileCount} file${
+          fileCount == 1 ? "" : "s"
+        }, ${issueCount} had issues.`,
+      );
+    });
+}
+
+lintMarkdown.description = `Run markdownlint on all '*.md' files.`;
+
+gulp.task("lint-md", lintMarkdown);

package.json

@@ -1,7 +1,15 @@
 {
   "devDependencies": {
+    "gulp": "^4.0.2",
+    "js-yaml": "^4.1.0",
     "markdown-link-check": "3.10.3",
     "markdown-toc": "^1.2.0",
-    "markdownlint-cli": "0.31.0"
+    "markdownlint": "^0.29.0",
+    "markdownlint-cli": "0.31.0",
+    "prettier": "^3.0.0",
+    "through2": "^4.0.2"
+  },
+  "prettier": {
+    "proseWrap": "preserve"
   }
 }