Update style guide with Goldmark, Markdown, Emoji details; and fix NPM scripts (#8523)

Author: chalin

.cspell.yml

@@ -72,6 +72,8 @@ dictionaries:
   - companies
 words: # Valid words across all locales
   - Docsy
+  - errorf
+  - Goldmark
   - htmltest
   - jsonify
   - nvmrc

.markdownlint.yaml

@@ -21,7 +21,7 @@ trim-code-blank-lines: true
 unindent-code-blocks: true
 validate-links:
   patterns:
-    - regex: "https://github\\.(?!com|blog|io)"
+    - regex: "https://github\\.(?!com|blog|io|github.com)"
       message: >-
         GitHub URLs should use `github.(com|blog|io)` domains to avoid
         typosquatting. For details, see

content/en/docs/contributing/style-guide.md

@@ -47,11 +47,29 @@ are properly written and use the original capitalization. For example, write
 [`.textlintrc.yml`](https://github.com/open-telemetry/opentelemetry.io/blob/main/.textlintrc.yml)
 file.
 
-## Markdown standards
+## Markdown
+
+Site pages are written in the Markdown syntax supported by the [Goldmark]
+Markdown renderer. For the full list of supported Markdown extensions, see
+[Goldmark].
+
+You can also use the following extensions:
+
+- [GitHub-flavored Markdown][GFM] (GFM) [alerts][gfm-alerts]
+- [Emojis]. For the complete list of available emojis, see [Emojis] from the
+  Hugo docs.
+
+[Emojis]: https://gohugo.io/quick-reference/emojis/
+[gfm-alerts]:
+  https://docs.github.com/en/contributing/style-guide-and-content-model/style-guide#alerts
+[GFM]: https://github.github.com/gfm/
+[Goldmark]: https://gohugo.io/configuration/markup/#goldmark
+
+### Markdown checks {#markdown-standards}
 
 To enforce standards and consistency for Markdown files, all files should follow
 certain rules, enforced by [markdownlint]. For a full list, check the
-[.markdownlint.yaml] file.
+[.markdownlint.yaml] and [.markdownlint-cli2.yaml] files.
 
 We also enforce Markdown [file format](#file-format) and strip files of trailing
 whitespace. This precludes the [line break syntax] of 2+ spaces; use `<br>`
@@ -107,6 +125,8 @@ To learn how to fix validation issues, see [Pull request checks](../pr-checks).
 
 [.markdownlint.yaml]:
   https://github.com/open-telemetry/opentelemetry.io/blob/main/.markdownlint.yaml
+[.markdownlint-cli2.yaml]:
+  https://github.com/open-telemetry/opentelemetry.io/blob/main/.markdownlint-cli2.yaml
 [line break syntax]: https://www.markdownguide.org/basic-syntax/#line-breaks
 [markdownlint]: https://github.com/DavidAnson/markdownlint
 [Prettier]: https://prettier.io

package.json

@@ -80,7 +80,7 @@
     "fix:i18n:status": "scripts/check-i18n.sh -D",
     "fix:i18n:new": "scripts/check-i18n.sh -n -c HEAD",
     "fix:i18n": "npm run seq -- fix:i18n:new fix:i18n:status",
-    "fix:markdown": "npm run check:markdown -- --fix; echo '\nTrimming trailing whitespace'; npm run _fix:trailing-spaces",
+    "fix:markdown": "npm run check:markdown -- --fix && echo '\nTrimming trailing whitespace' && npm run _fix:trailing-spaces",
     "fix:refcache:refresh": "npm run _refcache:prune -- -n ${PRUNE_N:-128}",
     "fix:refcache": "npm run _refcache:prune; npm run check:links",
     "fix:submodule": "npm run pin:submodule",

static/refcache.json

@@ -1759,6 +1759,10 @@
     "StatusCode": 206,
     "LastSeen": "2025-11-15T09:38:59.707307006Z"
   },
+  "https://docs.github.com/en/contributing/style-guide-and-content-model/style-guide#alerts": {
+    "StatusCode": 206,
+    "LastSeen": "2025-11-26T17:51:15.834945-05:00"
+  },
   "https://docs.github.com/en/get-started/learning-about-github/github-glossary#pull-request": {
     "StatusCode": 206,
     "LastSeen": "2025-11-21T09:40:42.11255134Z"
@@ -12619,6 +12623,10 @@
     "StatusCode": 206,
     "LastSeen": "2025-11-17T14:57:41.126995104Z"
   },
+  "https://github.com/open-telemetry/opentelemetry.io/blob/main/.markdownlint-cli2.yaml": {
+    "StatusCode": 206,
+    "LastSeen": "2025-11-26T17:51:17.325572-05:00"
+  },
   "https://github.com/open-telemetry/opentelemetry.io/blob/main/.markdownlint.yaml": {
     "StatusCode": 206,
     "LastSeen": "2025-11-20T09:40:48.538191812Z"
@@ -14651,6 +14659,10 @@
     "StatusCode": 206,
     "LastSeen": "2025-11-18T09:47:56.758345602Z"
   },
+  "https://github.github.com/gfm/": {
+    "StatusCode": 206,
+    "LastSeen": "2025-11-26T17:51:14.400324-05:00"
+  },
   "https://gitlab.com": {
     "StatusCode": 206,
     "LastSeen": "2025-11-18T09:44:51.977083492Z"
@@ -14755,6 +14767,10 @@
     "StatusCode": 206,
     "LastSeen": "2025-11-14T09:41:08.91819301Z"
   },
+  "https://gohugo.io/configuration/markup/#goldmark": {
+    "StatusCode": 206,
+    "LastSeen": "2025-11-26T17:51:14.205176-05:00"
+  },
   "https://gohugo.io/content-management/front-matter/": {
     "StatusCode": 206,
     "LastSeen": "2025-11-24T00:03:50.700120752Z"
@@ -14771,6 +14787,10 @@
     "StatusCode": 206,
     "LastSeen": "2025-11-21T09:40:39.773052521Z"
   },
+  "https://gohugo.io/quick-reference/emojis/": {
+    "StatusCode": 206,
+    "LastSeen": "2025-11-26T17:51:16.784399-05:00"
+  },
   "https://google.aip.dev/122#full-resource-names": {
     "StatusCode": 206,
     "LastSeen": "2025-11-16T09:42:34.40017975Z"