Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Markdownlint: dashes-in-headings custom rule #28330

Open
wants to merge 7 commits into
base: main
Choose a base branch
from

Conversation

MaoShizhong
Copy link
Contributor

@MaoShizhong MaoShizhong commented Jul 2, 2024

Because

Markdownlint and VSC use GitHub's heading algorithm to generate fragments, which gives different results to Ruby on Rails' #parameterize method when dealing with isolated dashes (a dash group surrounded by spaces, used as a separator).

This leads to the TOP-valid fragment for ### Heading - Subheading triggering the MD051 rule, and the Markdownlint-valid fragment not matching the correct heading ID.

While we can use ### Heading - Subheading {#heading-subheading} for Markdownlint and VSC to pick up, this looks messy and just gives us an extra point of failure if we change the heading but forget to change the custom ID.

The solution is to enforce colons as separators, leaving other dash uses (like hyphens or CLI flags) in headings alone. Markdownlint and our web app will both convert ### Heading: Subheading and hyphenated-word to heading-subheading-and-hyphenated-word.

This PR

  • Adds TOP011 custom rule for dashes in headings
  • Provides test file demonstrating what headings are flagged and not flagged by this custom rule
  • Provides TOP011 doc file
  • Adds TOP011 to the custom rules array in the markdownlint config file
  • Amends TOP001-TOP010 doc files to use colon separators in headings for consistency

Issue

Closes #28328

Additional Information

N/A

Pull Request Requirements

  • I have thoroughly read and understand The Odin Project curriculum contributing guide
  • The title of this PR follows the location of change: brief description of change format, e.g. Intro to HTML and CSS lesson: Fix link text
  • The Because section summarizes the reason for this PR
  • The This PR section has a bullet point list describing the changes in this PR
  • If this PR addresses an open issue, it is linked in the Issue section
  • If any lesson files are included in this PR, they have been previewed with the Markdown preview tool to ensure it is formatted correctly
  • If any lesson files are included in this PR, they follow the Layout Style Guide

@MaoShizhong MaoShizhong added the Content: Markdownlint Involves anything related to the curriculum repo linter label Jul 2, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Content: Markdownlint Involves anything related to the curriculum repo linter
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Markdownlint: Markdownlint and TOP web app generate different heading IDs/fragments
1 participant