Discussion: Strip extra dash characters from headings
Issue Description
Kramdown (docs.gitlab.com
) and CommonMark(gitlab.com
) are two different Markdown engines. There are some differences with how things are rendered, but we apply our own things eventually to make them as similar as possible.
Specifically for the anchors, here's what we do:
One edge case where those two are different is when there's a heading like:
## Step 01 - Do this
- On docs.gitlab.com, this is rendered like:
#step-01---do-this
- On GitLab.com, this is rendered like:
#step-01-do-this
Notes:
- You can read more information in the discussion gitlab-environment-toolkit!944 (comment 1264547184)
- GitHub doesn't replace dashes, for example https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md026---trailing-punctuation-in-heading
- This has been in GitLab since the beginning, so there's no question of changing it there.
- Hugo follows the
goldmark
implementation which doesn't strip those, so we'd need to also port this to Hugo :/ (example)
Option 1: Don't do anything
- Pros:
- No change, no additional engineering effort (well, except from this issue
😄 ) - Compliant with the rest of the industry that implements the CommonMark spec
- Linters continue to work.
- No change, no additional engineering effort (well, except from this issue
- Cons:
- Difference of rendered content between GitLab.com and docs.gitlab.com
Option 2: Strip the extra dashes
The pros and cons are actually inverted.
- Pros:
- No difference of rendered content between GitLab.com and docs.gitlab.com.
- Cons:
- Additional engineering effort to implement this in Hugo and fix the affected links (see below).
- Not compliant with the rest of the industry that implements the CommonMark spec.
- For this edge case, linters stop to work.
Links that would need to be fixed:
grep -nRE '^##.*[[:blank:]]-[[:blank:]].*' doc
GitLab
doc/api/vulnerability_findings.md:148:### GraphQL - Project vulnerability findings doc/api/vulnerabilities.md:265:### GraphQL - Single vulnerability doc/api/vulnerabilities.md:321:### GraphQL - Confirm vulnerability doc/api/vulnerabilities.md:351:### GraphQL - Resolve vulnerability doc/api/vulnerabilities.md:381:### GraphQL - Dismiss vulnerability doc/api/vulnerabilities.md:411:### GraphQL - Revert vulnerability to detected state doc/api/epic_issues.md:333:## Update epic - issue association doc/architecture/blueprints/runner_tokens/index.md:339:### Stage 1 - Deprecations doc/architecture/blueprints/runner_tokens/index.md:349:### Stage 2 - Prepare `gitlab-runner` for `system_id` doc/architecture/blueprints/runner_tokens/index.md:358:### Stage 2a - Prepare GitLab Runner Helm Chart and GitLab Runner Operator doc/architecture/blueprints/runner_tokens/index.md:366:### Stage 3 - Database changes doc/architecture/blueprints/runner_tokens/index.md:388:### Stage 4 - Create runners from the UI doc/architecture/blueprints/runner_tokens/index.md:411:### Stage 5 - Optional disabling of registration token doc/architecture/blueprints/runner_tokens/index.md:421:### Stage 6 - Enforcement doc/architecture/blueprints/runner_tokens/index.md:431:### Stage 7 - Removals doc/architecture/blueprints/cells/index.md:279:### Iteration 5..N - starting FY25Q3 doc/architecture/blueprints/cells/deployment-architecture.md:12:## 1. Before Cells - Monolithic architecture doc/architecture/blueprints/cells/deployment-architecture.md:39:## 2. Development Cells - Adapting application to Cellular architecture doc/architecture/blueprints/cells/deployment-architecture.md:55:## 3. Initial Cells deployment - Transforming monolithic architecture to Cells architecture doc/architecture/blueprints/cells/deployment-architecture.md:81:## 4. Hybrid Cells deployment - Initial complete Cells architecture doc/architecture/blueprints/cells/deployment-architecture.md:93:## 5. Target Cells - Fully isolated Cells architecture doc/architecture/blueprints/clickhouse_read_abstraction_layer/index.md:188:#### Open - Source solutions doc/architecture/blueprints/secret_detection/index.md:212:### Phase 1 - Ruby pushcheck pre-receive integration doc/architecture/blueprints/secret_detection/index.md:293:### Phase 2 - Standalone pre-receive service doc/architecture/blueprints/secret_detection/index.md:409:### Phase 3 - Expansion beyond pre-receive service doc/architecture/blueprints/gitlab_steps/index.md:220:### 2023-11-28 - GitLab Steps ADR 001: Bootstrap Step Runner doc/architecture/blueprints/ci_builds_runner_fleet_metrics/index.md:34:### Metrics - MVC doc/architecture/blueprints/clickhouse_ingestion_pipeline/index.md:229:#### Iteration 1 - Develop write abstraction with sync mode enabled doc/architecture/blueprints/clickhouse_ingestion_pipeline/index.md:235:#### Iteration 2 - Add support for schemas & data validation doc/architecture/blueprints/clickhouse_ingestion_pipeline/index.md:239:#### Iteration 3 - Add support for async mode, PoC with one backend doc/architecture/blueprints/database_testing/index.md:110:### Mid-term - Improved feedback, query testing and background migration testing doc/architecture/blueprints/database_testing/index.md:119:### Long-term - incorporate into GitLab product doc/user/markdown.md:550:### Wiki - direct page link doc/user/markdown.md:561:### Wiki - direct file link doc/user/markdown.md:572:### Wiki - hierarchical link doc/user/markdown.md:605:### Wiki - root link doc/user/application_security/dast/browser_based_troubleshooting.md:163:### Example - log crawled paths doc/user/application_security/dast/browser_based_troubleshooting.md:224:### Example - log all DevTools messages doc/user/application_security/dast/browser_based_troubleshooting.md:243:### Example - log HTTP messages doc/user/application_security/dast/browser/troubleshooting.md:160:### Example - log crawled paths doc/user/application_security/dast/browser/troubleshooting.md:221:### Example - log all DevTools messages doc/user/application_security/dast/browser/troubleshooting.md:240:### Example - log HTTP messages doc/user/application_security/coverage_fuzzing/index.md:377:### Error `400 Bad request - Duplicate package is not allowed` doc/user/packages/npm_registry/index.md:445:### `npm publish` returns `npm ERR! 500 Internal Server Error - PUT` doc/user/packages/yarn_repository/index.md:59:### Publishing via the command line - Manual Publish doc/user/packages/yarn_repository/index.md:71:### Publishing via a CI/CD pipeline - Automated Publish doc/development/testing_guide/frontend_testing.md:1295:#### Example #1 - Element visibility doc/development/testing_guide/frontend_testing.md:1339:#### Example #2 - Presence of text doc/development/testing_guide/frontend_testing.md:1376:#### Example #3 - Complex HTML doc/development/fe_guide/style/javascript.md:128:## CSS Selectors - Use `js-` prefix doc/development/fe_guide/vue.md:958:## Appendix - Vue component subject under test doc/development/database/partitioning/list.md:22:### Step 1 - Add partition key doc/development/database/partitioning/list.md:40:### Step 2 - Create required indexes doc/development/database/partitioning/list.md:61:### Step 3 - Enforce unique constraint doc/development/database/partitioning/list.md:90:### Step 4 - Enforce foreign key constraint doc/development/database/partitioning/list.md:141:### Step 5 - Swap primary key doc/development/database/partitioning/list.md:179:### Step 6 - Create parent table and attach existing table as the initial partition doc/development/database/partitioning/list.md:306:### Step 7 - Re-point foreign keys to parent table doc/development/database/partitioning/list.md:322:### Step 8 - Ensure ID uniqueness across partitions doc/development/database/partitioning/list.md:355:### Step 9 - Analyze the partitioned table and create new partitions doc/development/database/partitioning/list.md:365:### Step 10 - Update the application to use the partitioned table doc/administration/package_information/licensing.md:66:### libjpeg-turbo - BSD 3-clause license doc/administration/raketasks/project_import_export.md:92:### `Exception: No such file or directory @ rb_sysopen - (filename)` doc/administration/raketasks/project_import_export.md:96:### `Exception: Permission denied @ rb_sysopen - (filename)` doc/administration/raketasks/project_import_export.md:123:### `Exception: Error importing repository into (namespace) - No space left on device` doc/administration/geo/glossary.md:62:### Geo deployment - Single-node sites doc/administration/geo/glossary.md:78:### Geo deployment - Multi-node sites doc/administration/geo/glossary.md:96:### Geo deployment - Mixed sites doc/administration/geo/replication/troubleshooting.md:738:### Message: `Synchronization failed - Error syncing repository` doc/administration/geo/replication/security_review.md:250:### What encryption requirements have been defined for data in transit - including transmission over WAN, LAN, SecureFTP, or publicly accessible protocols such as http: and https:? doc/administration/geo/setup/external_database.md:105:## - pg_hba.conf doc/administration/geo/setup/external_database.md:116:## - postgresql.conf doc/administration/geo/setup/external_database.md:136:## - pg_hba.conf doc/administration/geo/setup/external_database.md:146:## - postgresql.conf doc/administration/consul.md:200:### Consul does not start - multiple private IPs doc/integration/jenkins.md:174:### Error during GitLab configuration - "Connection failed. Please check your settings" doc/integration/jenkins.md:187:### Error in merge requests - "Could not connect to the CI server"
Omnibus
doc/troubleshooting.md:83:## Reconfigure shows an error: `NoMethodError - undefined method '[]=' for nil:NilClass` doc/troubleshooting.md:749:## Errno::EAFNOSUPPORT: Address family not supported by protocol - socket(2)
Runner
docs/install/windows.md:222:### I can't run Windows BASH scripts; I'm getting `The system cannot find the batch label specified - buildscript`
Edited by Achilleas Pipinellis