Refine heading capitalization logic

[colleenmcginnis]

Context: I've been testing these rules against existing docs to identify problematic patterns that we might be able to fix before a larger rollout.

I see a few opportunities to refine the logic in the Capitalization.yml configuration (raw data).

Custom anchor links

We shouldn't include the custom anchor links in the string that is checked. This is particularly a problem when the entire title is formatted as inline code.

Example

elastic/beats: docs/reference/metricbeat/ilm.md file (line 33)

### `setup.ilm.enabled` [setup-ilm-option]

docs/reference/metricbeat/ilm.md
 33:25  suggestion  '[setup-ilm-option]'               ElasticTest.Capitalization 
                    should use sentence-style                                     
                    capitalization.                                               

Numbers

We should allow numbers in headings including version number headings, which are used across all release notes.

Example

elastic/docs-content: release-notes/elastic-observability/index.md file (line 24)

## 9.2.2 [elastic-observability-9.2.2-release-notes]

release-notes/elastic-observability/index.md
 24:4   suggestion  '9.2.2                                        ElasticTest.Capitalization 
                    [elastic-observability-9.2.2-release-notes]'                             
                    should use sentence-style capitalization.                                                                            

Acronyms

Acronyms should be allowed in headings.

Example

elastic/docs-content: solutions/search/ranking/learning-to-rank-search-usage.md (line 14)

# Search using LTR [learning-to-rank-search-usage]

solutions/search/ranking/learning-to-rank-search-usage.md
 14:3  suggestion  'Search using LTR                 ElasticTest.Capitalization 
                   [learning-to-rank-search-usage]'                             
                   should use sentence-style                                    
                   capitalization.                                              

Colons

Headings that have colons where the character after the colon is capitalized are being flagged for not complying. This is in direct conflict with the logic in HeadingColons.yml so there's no way to satisfy both rules.

Example

elastic/ecs-logging-nodejs: docs/reference/morgan.md (line 13)

### Step 1: Install [morgan-setup-step-1]

docs/reference/morgan.md
 13:5    suggestion  'Step 1: Install                ElasticTest.Capitalization 
                     [morgan-setup-step-1]'                                     
                     should use sentence-style                                  
                     capitalization.                                            

Code references

In some cases a heading references an option or method straight from the code, but it's not formatted as inline code. It doesn't really make sense to tell them to use sentence case. Instead they should format as code. However, I'm not sure if this is feasible.

Example

elastic/ecs: docs/reference/ecs-allowed-values-entity-type.md (line 34)

## application [ecs-entity-type-application]

docs/reference/ecs-allowed-values-entity-type.md
 32:4  suggestion  'application                    ElasticTest.Capitalization 
                   [ecs-entity-type-application]'                             
                   should use sentence-style                                  
                   capitalization.     

[theletterf]

Thanks @colleenmcginnis!

I've made changes in v1.0.18 which you can see here: 70070e9

• Added the : indicator to tell Vale to ignore capitalized words after a colon (this fixed the HeadingColons conflict).
• Used the threshold option to provide flexibility for edge cases. We can adjust that if needed.
• Updated the TokenIgnores global option to ignore anchor links.
• Added a list of acronyms exceptions taken from your acronyms spreadsheet.

The only case that still fails is:

## application [ecs-entity-type-application]

We can either accept it as a known limitation or create a new custom rule like this:

extends: existence
message: "Consider formatting '%s' as inline code if it's a code reference."
level: suggestion
scope: heading
nonword: true
tokens:
  - '^[a-z][a-zA-Z0-9_.-]*(?:\s|$)'

Could you test and let me know? We might also want to define a cutoff for the acronyms you collected, in case adding them all seems excessive.