chore: Switch to doctoc

.cspell.yaml

@@ -99,6 +99,7 @@ words:
   - cumulatives
   - deser
   - inclusivity
+  - notitle
   - oteps
   - representivity
   - relatedly

.github/workflows/checks.yaml

@@ -62,10 +62,7 @@ jobs:
       run: npm install
 
     - name: run markdown-toc
-      run: make markdown-toc
-
-    - name: validate markdown-toc
-      run: git diff --exit-code ':*.md' || (echo 'Generated markdown Table of Contents is out of date, please run "make markdown-toc" and commit the changes in this PR.' && exit 1)
+      run: make markdown-toc-check
 
   compliance-matrix-check:
     runs-on: ubuntu-latest

Makefile

@@ -71,25 +71,15 @@ markdown-link-check:
 		-v \
 		home/repo
 
-# This target runs markdown-toc on all files that contain
-# a comment <!-- tocstop -->.
-#
-# The recommended way to prepate a .md file for markdown-toc is
-# to add these comments:
-#
-#   <!-- toc -->
-#   <!-- tocstop -->
 .PHONY: markdown-toc
 markdown-toc:
-	@if ! npm ls markdown-toc; then npm install; fi
-	@for f in $(ALL_DOCS); do \
-		if grep -q '<!-- tocstop -->' $$f; then \
-			echo markdown-toc: processing $$f; \
-			npx --no -- markdown-toc --no-first-h1 --no-stripHeadingTags -i $$f || exit 1; \
-		else \
-			echo markdown-toc: no TOC markers, skipping $$f; \
-		fi; \
-	done
+	@if ! npm ls doctoc; then npm ci; fi
+	npx --no -- doctoc . --update-only --mintocitems 1 --toc-pragma-style compact --notitle --entryprefix='-,*,+' || exit 1;
+
+.PHONY: markdown-toc-check
+markdown-toc-check:
+	@if ! npm ls doctoc; then npm ci; fi
+	npx --no -- doctoc . --update-only --mintocitems 1 --toc-pragma-style compact --notitle --entryprefix='-,*,+' --dryrun || exit 1;
 
 .PHONY: markdownlint
 markdownlint:

development/metrics/config-service.md

@@ -1,5 +1,7 @@
 # Metric Configuration Service
 
+<!-- START DOCTOC -->
+
 - [Metric Configuration Service](#metric-configuration-service)
   * [Overview](#overview)
   * [Service Protocol](#service-protocol)
@@ -18,7 +20,7 @@
         * [Fingerprint Hashing](#fingerprint-hashing)
       - [Remote Backend](#remote-backend)
 
-<small><i><a href='http://ecotrust-canada.github.io/markdown-toc/'>Table of contents generated with markdown-toc</a></i></small>
+<!-- END DOCTOC -->
 
 ## Overview
 

oteps/4485-extending-attributes-to-support-complex-values.md

@@ -1,6 +1,6 @@
 # Extending attributes to support complex values
 
-<!-- toc -->
+<!-- START DOCTOC -->
 
 - [Glossary](#glossary)
 - [Why?](#why)
@@ -25,7 +25,7 @@
 - [Backend research](#backend-research)
 - [Appendix](#appendix)
 
-<!-- tocstop -->
+<!-- END DOCTOC -->
 
 ## Glossary
 

oteps/4815-semantic-conventions-schema-v2.md

@@ -1,6 +1,6 @@
 # Semantic Convention Schema v2
 
-<!-- toc -->
+<!-- START DOCTOC -->
 
 - [Semantic Convention Schema v2](#semantic-convention-schema-v2)
   - [Motivation](#motivation)
@@ -28,7 +28,7 @@
   - [Prototypes](#prototypes)
   - [Future possibilities](#future-possibilities)
 
-<!-- tocstop -->
+<!-- END DOCTOC -->
 
 In this OTEP, we propose a new telemetry schema format that supports multiple convention registries
 and provides full access to metadata.

oteps/entities/0256-entities-data-model.md

@@ -4,7 +4,7 @@ This is a proposal of a data model to represent entities. The purpose of the dat
 is to have a common understanding of what an entity is, what data needs to be recorded,
 transferred, stored and interpreted by an entity observability system.
 
-<!-- toc -->
+<!-- START DOCTOC -->
 
 - [Motivation](#motivation)
 - [Design Principles](#design-principles)
@@ -37,7 +37,7 @@ transferred, stored and interpreted by an entity observability system.
 - [Future Work](#future-work)
 - [References](#references)
 
-<!-- tocstop -->
+<!-- END DOCTOC -->
 
 ## Motivation
 

oteps/entities/0264-resource-and-entities.md

@@ -6,7 +6,7 @@ current resource specification.
 
 It is an expansion on the [previous entity proposal](0256-entities-data-model.md).
 
-<!-- toc -->
+<!-- START DOCTOC -->
 
 - [Motivation](#motivation)
 - [Design](#design)
@@ -55,7 +55,7 @@ It is an expansion on the [previous entity proposal](0256-entities-data-model.md
   * [Implications](#implications)
   * [What could this mean for choosing entities that belong on resource?](#what-could-this-mean-for-choosing-entities-that-belong-on-resource)
 
-<!-- tocstop -->
+<!-- END DOCTOC -->
 
 ## Motivation
 

oteps/profiles/0239-profiles-data-model.md

@@ -2,7 +2,8 @@
 
 Introduces Data Model for Profiles signal to OpenTelemetry.
 
-<!-- toc -->
+<!-- START DOCTOC -->
+
 * [Motivation](#motivation)
 * [Design Notes](#design-notes)
   * [Design Goals](#design-goals)
@@ -56,7 +57,8 @@ Introduces Data Model for Profiles signal to OpenTelemetry.
   * [Repetition of Attribute Keys](#repetition-of-attribute-keys)
   * [Locations Optimization](#locations-optimization)
 * [Future Possibilities](#future-possibilities)
-<!-- toc -->
+
+<!-- END DOCTOC -->
 
 ## Motivation
 

oteps/trace/0170-sampling-probability.md

@@ -1,6 +1,6 @@
 # Probability sampling of telemetry events
 
-<!-- toc -->
+<!-- START DOCTOC -->
 
 - [Motivation](#motivation)
 - [Examples](#examples)
@@ -35,7 +35,7 @@
 - [Recommended reading](#recommended-reading)
 - [Acknowledgements](#acknowledgements)
 
-<!-- tocstop -->
+<!-- END DOCTOC -->
 
 Objective: Specify a foundation for sampling techniques in OpenTelemetry.
 

package.json

@@ -2,8 +2,8 @@
   "devDependencies": {
     "@cspell/dict-people-names": "1.1.16",
     "cspell": "10.0.1",
+    "doctoc": "2.5.0",
     "markdown-link-check": "3.14.2",
-    "markdown-toc": "1.2.0",
     "markdownlint-cli": "0.49.0",
     "textlint": "15.7.1",
     "textlint-filter-rule-allowlist": "4.0.0",

specification/baggage/api.md

@@ -10,7 +10,7 @@ weight: 1
 <details>
 <summary>Table of Contents</summary>
 
-<!-- toc -->
+<!-- START DOCTOC -->
 
 - [Overview](#overview)
 - [Operations](#operations)
@@ -23,7 +23,7 @@ weight: 1
 - [Propagation](#propagation)
 - [Conflict Resolution](#conflict-resolution)
 
-<!-- tocstop -->
+<!-- END DOCTOC -->
 
 </details>
 

specification/common/README.md

@@ -13,7 +13,7 @@ path_base_for_github_subdir:
 <details>
 <summary>Table of Contents</summary>
 
-<!-- toc -->
+<!-- START DOCTOC -->
 
 - [AnyValue](#anyvalue)
   * [map](#mapstring-anyvalue)
@@ -34,7 +34,7 @@ path_base_for_github_subdir:
   * [Configurable Parameters](#configurable-parameters)
   * [Exempt Entities](#exempt-entities)
 
-<!-- tocstop -->
+<!-- END DOCTOC -->
 
 </details>
 

specification/common/attribute-type-mapping.md

@@ -9,7 +9,7 @@ linkTitle: Mapping to AnyValue
 <details>
 <summary>Table of Contents</summary>
 
-<!-- toc -->
+<!-- START DOCTOC -->
 
 - [Converting to AnyValue](#converting-to-anyvalue)
   * [Primitive Values](#primitive-values)
@@ -26,7 +26,7 @@ linkTitle: Mapping to AnyValue
   * [Other Values](#other-values)
   * [Empty Values](#empty-values)
 
-<!-- tocstop -->
+<!-- END DOCTOC -->
 
 </details>
 

specification/compatibility/logging_trace_context.md

@@ -5,15 +5,15 @@
 <details>
 <summary>Table of Contents</summary>
 
-<!-- toc -->
+<!-- START DOCTOC -->
 
 - [Overview](#overview)
   * [Syslog RFC5424](#syslog-rfc5424)
   * [Plain Text Formats](#plain-text-formats)
   * [JSON Formats](#json-formats)
   * [Other Structured Formats](#other-structured-formats)
 
-<!-- tocstop -->
+<!-- END DOCTOC -->
 
 </details>
 

specification/compatibility/prometheus_and_openmetrics.md

@@ -12,7 +12,7 @@ aliases:
 <details>
 <summary>Table of Contents</summary>
 
-<!-- toc -->
+<!-- START DOCTOC -->
 
 - [Differences between Prometheus formats](#differences-between-prometheus-formats)
 - [Prometheus Metric points to OTLP](#prometheus-metric-points-to-otlp)
@@ -44,7 +44,7 @@ aliases:
   * [Exemplar Conversion](#exemplar-conversion)
   * [Resource Attributes](#resource-attributes-1)
 
-<!-- tocstop -->
+<!-- END DOCTOC -->
 
 </details>
 

specification/configuration/api.md

@@ -7,15 +7,15 @@ weight: 1
 
 **Status**: [Mixed](../document-status.md)
 
-<!-- toc -->
+<!-- START DOCTOC -->
 
 - [Overview](#overview)
   * [ConfigProvider](#configprovider)
     + [ConfigProvider operations](#configprovider-operations)
       - [Get instrumentation config](#get-instrumentation-config)
   * [ConfigProperties](#configproperties)
 
-<!-- tocstop -->
+<!-- END DOCTOC -->
 
 ## Overview
 

specification/configuration/common.md

@@ -13,7 +13,7 @@ aliases:
 <details>
 <summary>Table of Contents</summary>
 
-<!-- toc -->
+<!-- START DOCTOC -->
 
 - [Type-specific guidance](#type-specific-guidance)
   * [Numeric](#numeric)
@@ -23,7 +23,7 @@ aliases:
   * [String](#string)
     + [Enum](#enum)
 
-<!-- tocstop -->
+<!-- END DOCTOC -->
 
 </details>
 

specification/configuration/data-model.md

@@ -7,15 +7,15 @@ weight: 2
 
 **Status**: [Stable](../document-status.md)
 
-<!-- toc -->
+<!-- START DOCTOC -->
 
 - [Overview](#overview)
   * [Versioning policy and stability guarantees](#versioning-policy-and-stability-guarantees)
   * [File-based configuration model](#file-based-configuration-model)
     + [YAML file format](#yaml-file-format)
     + [Environment variable substitution](#environment-variable-substitution)
 
-<!-- tocstop -->
+<!-- END DOCTOC -->
 
 ## Overview
 

specification/configuration/sdk-environment-variables.md

@@ -13,7 +13,7 @@ aliases:
 <details>
 <summary>Table of Contents</summary>
 
-<!-- toc -->
+<!-- START DOCTOC -->
 
 - [Implementation guidelines](#implementation-guidelines)
 - [Parsing empty value](#parsing-empty-value)
@@ -39,7 +39,7 @@ aliases:
 - [Declarative configuration](#declarative-configuration)
 - [Language Specific Environment Variables](#language-specific-environment-variables)
 
-<!-- tocstop -->
+<!-- END DOCTOC -->
 
 </details>
 

specification/configuration/sdk.md

@@ -7,7 +7,7 @@ weight: 3
 
 **Status**: [Stable](../document-status.md) except where otherwise specified
 
-<!-- toc -->
+<!-- START DOCTOC -->
 
 - [Overview](#overview)
   * [In-Memory configuration model](#in-memory-configuration-model)
@@ -26,7 +26,7 @@ weight: 3
     + [Via OTEL_CONFIG_FILE](#via-otel_config_file)
   * [References](#references)
 
-<!-- tocstop -->
+<!-- END DOCTOC -->
 
 ## Overview
 

specification/configuration/supplementary-guidelines.md

@@ -7,13 +7,13 @@ requirements to the existing specifications.
 <details>
 <summary>Table of Contents</summary>
 
-<!-- toc -->
+<!-- START DOCTOC -->
 
 - [Configuration interface prioritization and `create`](#configuration-interface-prioritization-and-create)
 - [Programmatic customization and `create`](#programmatic-customization-and-create)
 - [Strict YAML parsing](#strict-yaml-parsing)
 
-<!-- tocstop -->
+<!-- END DOCTOC -->
 
 </details>