Skip to content

docs: fix broken Table of Contents anchors for duplicate headings#6

Open
youngfish42 wants to merge 1 commit into
mathworks:mainfrom
youngfish42:main
Open

docs: fix broken Table of Contents anchors for duplicate headings#6
youngfish42 wants to merge 1 commit into
mathworks:mainfrom
youngfish42:main

Conversation

@youngfish42

Copy link
Copy Markdown

Summary

This PR fixes the broken in-document navigation links in the Table of
Contents of MATLAB-Coding-Guidelines.md, addressing #5.

Problem

GitHub-Flavored Markdown auto-generates heading anchors by slugifying
the heading text (lowercasing, replacing spaces with -, stripping
punctuation). When the same heading text appears multiple times in a
document, GitHub disambiguates the later occurrences by appending
-1, -2, -3, ... to their slugs, in order of appearance.

The current TOC uses the bare slug (e.g. #general, #variables)
for every duplicate, so all six "General" links jump to the same
first section (under "Naming Guidelines"), and both "Variables"
links jump to the first "Variables" section. Users cannot navigate
to the intended subsections via the TOC.

The document contains the following duplicated headings:

  • ## General appears 6 times (Naming, Statements & Expressions,
    Code Comments, Function Authoring, Class Authoring, Error Handling)
  • ## Variables appears 2 times (Naming, Statements & Expressions)

Fix

Append the correct GitHub-generated suffix (-1 .. -5) to the
anchor of every duplicate TOC entry. The visible link text is left
unchanged; only the anchor target is corrected.

TOC entry Old anchor New anchor
Statements and Expressions > General #general #general-1
Statements and Expressions > Variables #variables #variables-1
Code Comments > General #general #general-2
Function Authoring > General #general #general-3
Class Authoring > General #general #general-4
Error Handling > General #general #general-5

All other TOC entries already point to unique headings and are left
untouched.

Scope

  • Files touched: MATLAB-Coding-Guidelines.md (TOC block only,
    lines 18, 19, 30, 33, 37, 41)
  • No content, heading text, or section ordering is changed.
  • No new files are added.

Verification

Rendered the file on GitHub after the change and confirmed that each
TOC link now jumps to its intended section.

Closes #5

Copilot AI review requested due to automatic review settings July 2, 2026 09:53

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This PR fixes broken in-document navigation in MATLAB-Coding-Guidelines.md by updating Table of Contents links for duplicated headings so each TOC entry points to the correct GitHub-generated anchor (e.g., #general-1, #general-2, …).

Changes:

  • Update the “General” TOC entries to use the correct disambiguated anchors (#general-1 through #general-5).
  • Update the second “Variables” TOC entry to use the correct disambiguated anchor (#variables-1).

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

linking issue

2 participants