.markdownlint.yaml

# See
# https://github.com/DavidAnson/markdownlint/blob/main/README.md#rules--aliases
#
# TODO: move the following to the contrib section of the site and link to it
# here.
#
# To disable any rule, including custom rules, use markdownlint disable
# directives, see
# https://github.com/DavidAnson/markdownlint/blob/main/README.md#configuration.
#
# For example:
#
# <!-- markdownlint-disable line-length-->
# ... text ...
# <!-- markdownlint-enable line-length -->
#
# Or:
# <!-- markdownlint-disable-next-line no-http-urls -->

default: true

emphasis-style: false
first-line-h1: false
line-length: false
link-fragments: false
list-marker-space: false
no-emphasis-as-header: false
no-hard-tabs: false
no-inline-html: false
no-trailing-punctuation: false
no-trailing-spaces:
  br_spaces: 0
  strict: true
table-column-style: false # Causes problems in ja and zh pages

# -----------------------------------------------------------------------------
# Custom rules

# We don't apply this rule broadly, only in selected folders such as blog posts;
# see content/en/blog/.markdownlint.yml.

gh-url-hash: false

# Custom rules registered in .markdownlint-cli2.yaml are enabled by default
# (via `default: true` above). Only list custom rules here to disable them or
# to provide configuration. Rules that need no config can be omitted.

no-shortcut-ref-link:
  # Skip:
  # - OTel spec informal footnotes like [1], [2]
  # - SemConf number ranges like [0..1], [0..n-1], [0.0, 1.0]
  # - Ellipsis like [...]
  ignore_pattern: '^([-+,n\d\.\s]+)$|^\.\.\.$'

# -----------------------------------------------------------------------------
# Link-validation rules (from scripts/_md-rules/link-rules.mjs)

# TODO: document the custom rules in the contrib section of the site and link
# to it here and in the rule message for further details.

no-typosquatting-urls:
  pattern: 'https://github\.(?!com|blog|io|github.com)'
  message: >-
    GitHub URLs should use `github.(com|blog|io|github.com)` domains to avoid
    typosquatting. For details, see
    https://github.com/open-telemetry/opentelemetry.io/issues/8085.

no-http-urls:
  pattern: '^http://(?!([\w-]+\.)?localhost\b)(?!127\.0)(?!.*[\?&]http_ok\b)'
  message: >-
    'http' URLs are only permitted for localhost/127.0.0.1. Use 'https' or add
    'http_ok' as a query parameter to the URL, such as:
    https://example.com?http_ok or http://example.com?q=search&http_ok.

no-lang-prefix-in-paths:
  # This rule might cause false positives if pages need to reach across locale
  # sites, but that seems unlikely. What has happened often enough is for locale
  # authors to prefix paths with their locale's language code; but that isn't
  # necessary, since absolute paths resolve to the locale's site root. See
  # https://gohugo.io/quick-reference/glossary/#site-relative
  pattern: '^/..(?:-..)?(/.+)$'
  # Note: ^/../$ is accepted
  message: Don't prefix paths with a language code.
  replace: '$1'

no-otel-io-external-urls:
  pattern: 'https?://(?:www\.)?opentelemetry\.io/'
  message: Use a site-relative path instead of the full opentelemetry.io URL.
  replace: '/'

no-spec-github-urls:
  pattern: 'https://github\.com/open-telemetry/opentelemetry-specification/(?:blob|tree)/main/specification/'
  message: >-
    Use a local path, not a GitHub URL, for references to specification pages
    that are hosted on this site.
  replace: '/docs/specs/otel/'

no-proto-spec-github-urls:
  pattern: 'https://github\.com/open-telemetry/opentelemetry-proto/(?:blob|tree)/main/docs/specification'
  message: >-
    Use a local path, not a GitHub URL, for references to specification pages
    that are hosted on this site.
  replace: '/docs/specs/otlp/'

no-semconv-github-urls:
  pattern: 'https://github\.com/open-telemetry/semantic-conventions/(?:blob|tree)/main/docs'
  message: >-
    Use a local path, not a GitHub URL, for references to semantic conventions
    pages that are hosted on this site.
  replace: '/docs/specs/semconv/'