Fix markdownlint violations (#16222)

straight-shoota · web-flow · commit a1a8e8647877 · 2025-10-20T12:45:34.000+02:00
diff --git a/.github/ISSUE_TEMPLATE/bug-report.md b/.github/ISSUE_TEMPLATE/bug-report.md
@@ -5,7 +5,7 @@ labels: kind:bug
 type: Bug
 ---
 
-## Bug Report
+# Bug Report
 
 Make sure to review these points before submitting issues - thank you!
 
diff --git a/.github/ISSUE_TEMPLATE/discussion.md b/.github/ISSUE_TEMPLATE/discussion.md
@@ -4,7 +4,7 @@ about: I want to start a new discussion about improving the language.
 labels: status:discussion
 ---
 
-## Discussion
+# Discussion
 
 - What aspect of the language would you like to see improved?
 - What are the reasons?
diff --git a/.github/ISSUE_TEMPLATE/feature-request.md b/.github/ISSUE_TEMPLATE/feature-request.md
@@ -5,7 +5,7 @@ labels: kind:feature
 type: Feature
 ---
 
-## Feature Request
+# Feature Request
 
 - Is your feature request related to a problem? Please describe clearly and concisely what is it.
 - Describe the feature you would like, optionally illustrated by examples, and how it will solve the above problem.
diff --git a/.github/PULL_REQUEST_TEMPLATE/pull_request_template.md b/.github/PULL_REQUEST_TEMPLATE/pull_request_template.md
@@ -1,3 +1,5 @@
+# Pull Request
+
 We thank you for helping improve Crystal. In order to ease the reviewing process, we invite you to read the [guidelines](https://github.com/crystal-lang/crystal/blob/master/CONTRIBUTING.md#making-good-pull-requests) and ask you to consider the following points before submitting a PR:
 
 1. We prefer to discuss the underlying issue _prior_ to discussing the code. Therefore, we kindly ask you to refer to an existing issue, or an existing discussion in a public space with members of the Core Team (forum, Gitter, Discord, ...). In few cases, we acknowledge that this might not be necessary, for instance when refactoring code or small bug fixes. In this case, the PR must include the same information an issue would have: a clear explanation of the issue, reproducible code, etc.
diff --git a/.markdownlint.yaml b/.markdownlint.yaml
@@ -0,0 +1,37 @@
+default: true
+
+heading-style: "setext"
+
+no-inline-html: false
+line-length: false
+
+ol-prefix:
+  style: "ordered"
+ul-style:
+  style: "dash"
+ul-indent:
+  indent: 2
+
+no-blanks-blockquote: false
+
+emphasis-style:
+  style: "underscore"
+strong-style:
+  style: "asterisk"
+
+no-duplicate-heading:
+  siblings_only: true
+no-bare-urls: false
+
+fenced-code-language: false
+commands-show-output: false
+
+first-line-h1:
+  front_matter_title: "^\\s*(page_)?title\\s*[:=]"
+  exclude:
+    .github/PULL_REQUEST_TEMPLATE/pull_request_template.md
+
+no-alt-text: false
+
+hard_tab:
+  code_blocks: false
diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md
@@ -14,21 +14,21 @@ orientation.
 Examples of behavior that contributes to creating a positive environment
 include:
 
-* Using welcoming and inclusive language
-* Being respectful of differing viewpoints and experiences
-* Gracefully accepting constructive criticism
-* Focusing on what is best for the community
-* Showing empathy towards other community members
+- Using welcoming and inclusive language
+- Being respectful of differing viewpoints and experiences
+- Gracefully accepting constructive criticism
+- Focusing on what is best for the community
+- Showing empathy towards other community members
 
 Examples of unacceptable behavior by participants include:
 
-* The use of sexualized language or imagery and unwelcome sexual attention or
+- The use of sexualized language or imagery and unwelcome sexual attention or
 advances
-* Trolling, insulting/derogatory comments, and personal or political attacks
-* Public or private harassment
-* Publishing others' private information, such as a physical or electronic
+- Trolling, insulting/derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information, such as a physical or electronic
   address, without explicit permission
-* Other conduct which could reasonably be considered inappropriate in a
+- Other conduct which could reasonably be considered inappropriate in a
   professional setting
 
 ## Our Responsibilities
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -25,16 +25,17 @@ You can find a list of tasks that we consider suitable for a first time contribu
 the [good first issue label](https://github.com/crystal-lang/crystal/contribute).
 
 As you feel more confident, you can keep an eye out for open issues with the following labels:
-* [`community:to-research`](https://github.com/crystal-lang/crystal/issues?utf8=%E2%9C%93&q=is%3Aissue%20is%3Aopen%20label%3Acommunity%3Ato-research): Help needed on **researching and investigating** the issue at hand; could be from going through an RFC to figure out how something _should_ be working, to go through details on a C-library we'd like to bind.
-* [`community:to-design`](https://github.com/crystal-lang/crystal/issues?utf8=%E2%9C%93&q=is%3Aissue%20is%3Aopen%20label%3Acommunity%3Ato-design): As an issue has been accepted, we are looking for **ideas on how it could be implemented**, this is, a high-level design for the feature at hand.
-* [`community:to-implement`](https://github.com/crystal-lang/crystal/issues?utf8=%E2%9C%93&q=is%3Aissue%20is%3Aopen%20label%3Acommunity%3Ato-implement): After a design has been agreed upon, the remaining task is to actually **code** it and send a PR!
-* [`community:to-document`](https://github.com/crystal-lang/crystal/issues?utf8=%E2%9C%93&q=is%3Aissue%20is%3Aopen%20label%3Acommunity%3Ato-document): Similar to the one above, but this one is for those awesome devs that are happy to **contribute with documentation** instead of just code.
+
+- [`community:to-research`](https://github.com/crystal-lang/crystal/issues?utf8=%E2%9C%93&q=is%3Aissue%20is%3Aopen%20label%3Acommunity%3Ato-research): Help needed on **researching and investigating** the issue at hand; could be from going through an RFC to figure out how something _should_ be working, to go through details on a C-library we'd like to bind.
+- [`community:to-design`](https://github.com/crystal-lang/crystal/issues?utf8=%E2%9C%93&q=is%3Aissue%20is%3Aopen%20label%3Acommunity%3Ato-design): As an issue has been accepted, we are looking for **ideas on how it could be implemented**, this is, a high-level design for the feature at hand.
+- [`community:to-implement`](https://github.com/crystal-lang/crystal/issues?utf8=%E2%9C%93&q=is%3Aissue%20is%3Aopen%20label%3Acommunity%3Ato-implement): After a design has been agreed upon, the remaining task is to actually **code** it and send a PR!
+- [`community:to-document`](https://github.com/crystal-lang/crystal/issues?utf8=%E2%9C%93&q=is%3Aissue%20is%3Aopen%20label%3Acommunity%3Ato-document): Similar to the one above, but this one is for those awesome devs that are happy to **contribute with documentation** instead of just code.
 
 Furthermore, these are the most important general topics in need right now, so if you are interested open an issue to start working on it:
 
-* Documenting the language
-* Documenting the standard library
-* Adding missing bits of the standard library, and/or improving its performance
+- Documenting the language
+- Documenting the standard library
+- Adding missing bits of the standard library, and/or improving its performance
 
 ### Labels
 
@@ -64,25 +65,25 @@ Topic encompasses the broad aspect of the language that the issue refers to: cou
 
 Status labels attempt to capture the lifecycle of an issue:
 
-* A detailed proposal on a feature is marked as `draft`, while a more general argument is usually labelled as `discussion` until a consensus is achieved.
+- A detailed proposal on a feature is marked as `draft`, while a more general argument is usually labelled as `discussion` until a consensus is achieved.
 
-* An issue is `accepted` when it describes a feature or bugfix that a core team member has agreed to have added to the language, so as soon as a design is discussed (if needed), it's safe to start working on a pull request.
+- An issue is `accepted` when it describes a feature or bugfix that a core team member has agreed to have added to the language, so as soon as a design is discussed (if needed), it's safe to start working on a pull request.
 
-* Bug reports are marked as `needs-more-info`, where the author is requested to provide the info required; note that the issue may be closed after some time if it is not supplied.
+- Bug reports are marked as `needs-more-info`, where the author is requested to provide the info required; note that the issue may be closed after some time if it is not supplied.
 
-* Issues that are batched in an epic to be worked on as a group are typically marked as `deferred`, while low-prio issues or tasks far away in the roadmap are marked as `someday`.
+- Issues that are batched in an epic to be worked on as a group are typically marked as `deferred`, while low-prio issues or tasks far away in the roadmap are marked as `someday`.
 
-* Closed issues are marked as `implemented`, `invalid`, `duplicate` or `wontfix`, depending on their resolution.
+- Closed issues are marked as `implemented`, `invalid`, `duplicate` or `wontfix`, depending on their resolution.
 
-## Contributing to...
+## Contributing
 
 ### The documentation
 
-The language reference is available at https://crystal-lang.org/reference/.
+The language reference is available at <https://crystal-lang.org/reference/>.
 See the repository at [crystal-lang/crystal-book](https://github.com/crystal-lang/crystal-book) for contributing to it.
 
 The [standard library documentation](https://crystal-lang.org/api/) is on the code itself, in this repository.
-There is a version updated with every push to the master branch [here](https://crystal-lang.org/api/master/).
+The [`master` version](https://crystal-lang.org/api/master/) is updated with every push to the master branch.
 It uses a subset of [Markdown](http://daringfireball.net/projects/markdown/). You can [use Ruby as a source
 of inspiration](https://twitter.com/yukihiro_matz/status/549317901002342400) whenever applicable. To generate
 the docs execute `make docs`. Please follow the guidelines described in our
@@ -92,8 +93,8 @@ Additionally, all official documentation can be found on [the Crystal website](h
 
 ### The standard library
 
-1. Fork it ( https://github.com/crystal-lang/crystal/fork )
-2. Clone it
+1. [Fork](https://github.com/crystal-lang/crystal/fork) and checkout the
+   repository <https://github.com/crystal-lang/crystal/>
 
 Once in the cloned directory, and once you [installed Crystal](https://crystal-lang.org/install/),
 you can execute `bin/crystal` instead of `crystal`. This is a wrapper that will use the cloned repository
@@ -206,13 +207,13 @@ details of the pull request process. For non-trivial changes, the merge commit s
 
 1. Do not directly commit to the `master` branch. Always create a feature branch and pull request.
 2. Feature branches should typically be created in your fork. The main repo should only contain essential branches.
-   * CI changes affecting circle CI only run for branches on the main repo. They should be prefixed `ci/` to trigger a maintenance release.
-   * Long-running feature branches that accept contributions must be pushed to the main repo in order to allow PRs targeting that branch.
+   - CI changes affecting circle CI only run for branches on the main repo. They should be prefixed `ci/` to trigger a maintenance release.
+   - Long-running feature branches that accept contributions must be pushed to the main repo in order to allow PRs targeting that branch.
 
 ## Git pre-commit hook
 
 Code submitted to this repository should be formatted according to `crystal tool format`.
-A pre-commit hook can be installed into the local git repo to ensure the formatter validates every commit: https://github.com/crystal-lang/crystal/blob/master/scripts/git/pre-commit
+A pre-commit hook can be installed into the local git repo to ensure the formatter validates every commit: <https://github.com/crystal-lang/crystal/blob/master/scripts/git/pre-commit>
 
 Install the pre-commit hook:
 
diff --git a/NOTICE.md b/NOTICE.md
@@ -10,39 +10,39 @@ otherwise:
 Please see [REUSE.toml](REUSE.toml) and [LICENSE](LICENSE) for additional
 copyright and licensing information.
 
-* This repository includes vendored libraries (shards) in `/lib/` which have
-their own licenses. See [REUSE.toml](REUSE.toml) for details.
-* Crystal playground includes vendored libraries with their own licenses. See
-[src/compiler/crystal/tools/playground/public/vendor/REUSE.toml](src/compiler/crystal/tools/playground/public/vendor/REUSE.toml)
-for details.
+- This repository includes vendored libraries (shards) in `/lib/` which have
+  their own licenses. See [REUSE.toml](REUSE.toml) for details.
+- Crystal playground includes vendored libraries with their own licenses. See
+  [src/compiler/crystal/tools/playground/public/vendor/REUSE.toml](src/compiler/crystal/tools/playground/public/vendor/REUSE.toml)
+  for details.
 
 ## External libraries information
 
 Crystal compiler links the following libraries, which have their own license:
 
-  * [LLVM][] - [Apache-2.0 with LLVM exceptions][]
-  * [PCRE or PCRE2][] - [BSD-3][]
-  * [libevent2][] - [BSD-3][]
-  * [libiconv][] - [LGPLv3][]
-  * [bdwgc][] - [MIT][]
+- [LLVM][] - [Apache-2.0 with LLVM exceptions][]
+- [PCRE or PCRE2][] - [BSD-3][]
+- [libevent2][] - [BSD-3][]
+- [libiconv][] - [LGPLv3][]
+- [bdwgc][] - [MIT][]
 
 Crystal compiler calls the following tools as external process on compiling, which have their own license:
 
-  * [pkg-config](https://www.freedesktop.org/wiki/Software/pkg-config/) - [GPLv3]
+- [pkg-config](https://www.freedesktop.org/wiki/Software/pkg-config/) - [GPLv3]
 
 Crystal standard library uses the following libraries, which have their own licenses:
 
-  * [LLVM][] - [Apache-2.0 with LLVM exceptions][]
-  * [PCRE or PCRE2][] - [BSD-3][]
-  * [libevent2][] - [BSD-3][]
-  * [libiconv][] - [LGPLv3][]
-  * [bdwgc][] - [MIT][]
-  * [Zlib][] - [Zlib][Zlib-license]
-  * [OpenSSL][] - [Apache-2.0][]
-  * [Libxml2][] - [MIT][]
-  * [LibYAML][] - [MIT][]
-  * [readline][] - [GPLv3][]
-  * [GMP][] - [LGPLv3][]
+- [LLVM][] - [Apache-2.0 with LLVM exceptions][]
+- [PCRE or PCRE2][] - [BSD-3][]
+- [libevent2][] - [BSD-3][]
+- [libiconv][] - [LGPLv3][]
+- [bdwgc][] - [MIT][]
+- [Zlib][] - [Zlib][Zlib-license]
+- [OpenSSL][] - [Apache-2.0][]
+- [Libxml2][] - [MIT][]
+- [LibYAML][] - [MIT][]
+- [readline][] - [GPLv3][]
+- [GMP][] - [LGPLv3][]
 
 <!-- licenses -->
 [Apache-2.0]: https://www.openssl.org/source/apache-license-2.0.txt
@@ -51,21 +51,15 @@ Crystal standard library uses the following libraries, which have their own lice
 [GPLv3]: https://www.gnu.org/licenses/gpl-3.0.en.html
 [LGPLv3]: https://www.gnu.org/licenses/lgpl-3.0.en.html
 [MIT]: https://opensource.org/licenses/MIT
-[OFL-1.1]: https://opensource.org/licenses/OFL-1.1
 [Zlib-license]: https://opensource.org/licenses/Zlib
 <!-- libraries -->
-[ansi\_up]: https://github.com/drudru/ansi\_up
 [bdwgc]: http://www.hboehm.info/gc/
-[CodeMirror]: https://codemirror.net/
-[jQuery]: https://jquery.com/
 [GMP]: https://gmplib.org/
 [libevent2]: http://libevent.org/
 [libiconv]: https://www.gnu.org/software/libiconv/
 [Libxml2]: http://xmlsoft.org/
 [LibYAML]: http://pyyaml.org/wiki/LibYAML
 [LLVM]: http://llvm.org/
-[Materialize]: http://materializecss.com/
-[Octicons]: https://octicons.github.com/
 [OpenSSL]: https://www.openssl.org/
 [PCRE or PCRE2]: http://pcre.org/
 [readline]: https://tiswww.case.edu/php/chet/readline/rltop.html
diff --git a/README.md b/README.md
@@ -14,14 +14,13 @@
 
 Crystal is a programming language with the following goals:
 
-* Have a syntax similar to Ruby (but compatibility with it is not a goal)
-* Statically type-checked but without having to specify the type of variables or method arguments.
-* Be able to call C code by writing bindings to it in Crystal.
-* Have compile-time evaluation and generation of code, to avoid boilerplate code.
-* Compile to efficient native code.
+- Have a syntax similar to Ruby (but compatibility with it is not a goal)
+- Statically type-checked but without having to specify the type of variables or method arguments.
+- Be able to call C code by writing bindings to it in Crystal.
+- Have compile-time evaluation and generation of code, to avoid boilerplate code.
+- Compile to efficient native code.
 
-Why?
-----
+## Why?
 
 We love Ruby's efficiency for writing code.
 
@@ -35,37 +34,31 @@ We want full OOP.
 
 Oh, and we don't want to write C code to make the code run faster.
 
-Project Status
---------------
+## Project Status
 
 Within a major version, language features won't be removed or changed in any way that could prevent a Crystal program written with that version from compiling and working. The built-in standard library might be enriched, but it will always be done with backwards compatibility in mind.
 
 Development of the Crystal language is possible thanks to the community's effort and the continued support of [84codes](https://www.84codes.com/) and every other [sponsor](https://crystal-lang.org/sponsors).
 
-Installing
-----------
+## Installing
 
 [Follow these installation instructions](https://crystal-lang.org/install)
 
-Try it online
--------------
+## Try it online
 
 [play.crystal-lang.org](https://play.crystal-lang.org/)
 
-Documentation
--------------
+## Documentation
 
-* [Language Reference](http://crystal-lang.org/reference)
-* [Standard library API](https://crystal-lang.org/api)
-* [Roadmap](https://github.com/crystal-lang/crystal/wiki/Roadmap)
+- [Language Reference](http://crystal-lang.org/reference)
+- [Standard library API](https://crystal-lang.org/api)
+- [Roadmap](https://github.com/crystal-lang/crystal/wiki/Roadmap)
 
-Community
----------
+## Community
 
 Have any questions or suggestions? Ask on the [Crystal Forum](https://forum.crystal-lang.org), on our [Gitter channel](https://gitter.im/crystal-lang/crystal) or IRC channel [#crystal-lang](https://web.libera.chat/#crystal-lang) at irc.libera.chat, or on Stack Overflow under the [crystal-lang](http://stackoverflow.com/questions/tagged/crystal-lang) tag. There is also an archived [Google Group](https://groups.google.com/forum/?fromgroups#!forum/crystal-lang).
 
-Contributing
-------------
+## Contributing
 
 The Crystal repository is hosted at [crystal-lang/crystal](https://github.com/crystal-lang/crystal) on GitHub.
 
diff --git a/SECURITY.md b/SECURITY.md
@@ -1,6 +1,6 @@
-## Reporting a Vulnerability
+# Reporting a Vulnerability
 
-Should you find any security-related issue, please *do not share them openly* in
+Should you find any security-related issue, please _do not share them openly_ in
 the issue tracker. We have a dedicated mailbox where we keep track of them:
 
 <security@manas.tech>
diff --git a/UPGRADING.md b/UPGRADING.md
@@ -14,13 +14,13 @@ a specific release.
 
 ## Crystal 1.13
 
-* `CRYSTAL_LIBRARY_RPATH` and the `preview_win32_delay_load` feature flag have
+- `CRYSTAL_LIBRARY_RPATH` and the `preview_win32_delay_load` feature flag have
   been removed. Individual DLLs can be explicitly delay-loaded with the MSVC
   toolchain by using `/DELAYLOAD` as a linker flag. Similarly RPATH can be added
   with GCC or Clang toolchains by adding `-Wl,-rpath`.
 
 ## Crystal 1.9
 
-* The implementation of the comparison operator `#<=>` between `Big*` (`BigDecimal`,
+- The implementation of the comparison operator `#<=>` between `Big*` (`BigDecimal`,
   `BigFloat`, `BigInt`, `BigRational`) and `Float` (`Float32`, `Float64`) number types
   is now nilable. When invoking these comparisons, `Nil` values must be handled.

Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+# Pull Request`
	`2`	`+`
`1`	`3`	`We thank you for helping improve Crystal. In order to ease the reviewing process, we invite you to read the [guidelines](https://github.com/crystal-lang/crystal/blob/master/CONTRIBUTING.md#making-good-pull-requests) and ask you to consider the following points before submitting a PR:`
`2`	`4`
`3`	`5`	`1. We prefer to discuss the underlying issue _prior_ to discussing the code. Therefore, we kindly ask you to refer to an existing issue, or an existing discussion in a public space with members of the Core Team (forum, Gitter, Discord, ...). In few cases, we acknowledge that this might not be necessary, for instance when refactoring code or small bug fixes. In this case, the PR must include the same information an issue would have: a clear explanation of the issue, reproducible code, etc.`