├── .editorconfig ├── .eslintignore ├── .eslintrc.js ├── .gitattributes ├── .github ├── codeowners └── workflows │ └── ci-node.yaml ├── .gitignore ├── .husky └── pre-commit ├── .mailmap ├── .npmrc ├── .prettierignore ├── .remarkignore ├── .remarkrc.mjs ├── changelog.md ├── license ├── lint-staged.config.js ├── package-lock.json ├── package.json ├── packages └── @svengreb │ └── remark-preset-lint │ ├── index.js │ ├── package.json │ ├── readme.md │ └── rules │ ├── blockquotes.js │ ├── code.js │ ├── emphasis.js │ ├── headings.js │ ├── horizontal-rules.js │ ├── links.js │ ├── lists.js │ ├── naming-conventions.js │ ├── paragraphs.js │ ├── raw-html.js │ ├── strings.js │ ├── support.js │ ├── tables.js │ └── whitespace.js ├── prettier.config.js ├── readme.md └── rules ├── accessibility-a11y.md ├── blockquotes.md ├── code.md ├── comments.md ├── emphasis.md ├── headings.md ├── horizontal-rules.md ├── images.md ├── index.md ├── links.md ├── lists.md ├── naming-conventions.md ├── paragraphs.md ├── raw-html.md ├── strings.md ├── tables.md └── whitespace.md /.editorconfig: -------------------------------------------------------------------------------- 1 | # Copyright (c) 2016-present Sven Greb 2 | # This source code is licensed under the MIT license found in the license file. 3 | 4 | # Configurations for EditorConfig. 5 | # See https://editorconfig.org/#file-format-details for more details. 6 | 7 | # +--------------------+ 8 | # + Base Configuration + 9 | # +--------------------+ 10 | root = true 11 | 12 | [*] 13 | charset = utf-8 14 | end_of_line = lf 15 | indent_size = 2 16 | indent_style = space 17 | insert_final_newline = true 18 | max_line_length = 160 19 | trim_trailing_whitespace = true 20 | 21 | # +-----------+ 22 | # + Languages + 23 | # +-----------+ 24 | # +--- Markdown ---+ 25 | [*.{md}] 26 | max_line_length = off 27 | trim_trailing_whitespace = false 28 | -------------------------------------------------------------------------------- /.eslintignore: -------------------------------------------------------------------------------- 1 | # Copyright (c) 2016-present Sven Greb 2 | # This source code is licensed under the MIT license found in the license file. 3 | 4 | # Path match pattern to ignore (i.e. not lint) certain files and folders. 5 | # References: 6 | # 1. https://eslint.org/docs/latest/use/configure/ignore 7 | 8 | node_modules/ 9 | 10 | # Explicitly include specific "dotfiles". 11 | # ESLint automatically applies ignore pattern for "dotfiles" by default to prevent accidentally lint over paths like 12 | # `.git` or any other critical paths. 13 | !**/.eslintrc.js 14 | !.remarkrc.mjs 15 | -------------------------------------------------------------------------------- /.eslintrc.js: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright (c) 2016-present Sven Greb 3 | * This source code is licensed under the MIT license found in the license file. 4 | */ 5 | 6 | /** 7 | * Configurations for ESLint. 8 | * @see https://eslint.org/docs/latest/use/configure 9 | * @see https://eslint.org/docs/latest/use/configure/#using-configuration-files 10 | * @see https://eslint.org/docs/latest/use/configure/#specifying-environments 11 | * @see https://eslint.org/docs/latest/rules 12 | */ 13 | module.exports = { 14 | root: true, 15 | extends: [ 16 | "@arcticicestudio/eslint-config-base", 17 | /* 18 | * Enable support for projects using Prettier. 19 | * Note that this must always be placed after the `@arcticicestudio/eslint-config-base` preset to take precedence, otherwise it won't prevent errors 20 | * due to useless and possibly conflicting rules! 21 | */ 22 | "@arcticicestudio/eslint-config-base/prettier", 23 | ], 24 | overrides: [ 25 | { 26 | files: ["*.js"], 27 | rules: { 28 | "capitalized-comments": "off", 29 | }, 30 | }, 31 | ], 32 | }; 33 | -------------------------------------------------------------------------------- /.gitattributes: -------------------------------------------------------------------------------- 1 | # Copyright (c) 2016-present Sven Greb 2 | # This source code is licensed under the MIT license found in the license file. 3 | 4 | # Configuration to define attributes per path. 5 | # References: 6 | # 1. https://git-scm.com/docs/gitattributes 7 | # 2. https://git-scm.com/book/en/v2/Customizing-Git-Git-Attributes#Keyword-Expansion 8 | 9 | # Automatically perform line feed (LF) normalization for files detected as text and 10 | # leave all files detected as binary untouched. 11 | * text=auto eol=lf 12 | -------------------------------------------------------------------------------- /.github/codeowners: -------------------------------------------------------------------------------- 1 | # Copyright (c) 2016-present Sven Greb 2 | # This source code is licensed under the MIT license found in the license file. 3 | 4 | # Configuration for the GitHub feature to automatically request reviews from the code owners 5 | # when a pull request changes any owned files. 6 | # 7 | # References: 8 | # 1. https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners#codeowners-file-location 9 | # 2. https://github.com/blog/2392-introducing-code-owners 10 | 11 | # +----------------------+ 12 | # + Core Team Code Owner + 13 | # +----------------------+ 14 | * @svengreb 15 | -------------------------------------------------------------------------------- /.github/workflows/ci-node.yaml: -------------------------------------------------------------------------------- 1 | # Copyright (c) 2016-present Sven Greb 2 | # This source code is licensed under the MIT license found in the LICENSE file. 3 | 4 | # GitHub Action Workflow for continuous integration jobs. 5 | # References: 6 | # 1. https://docs.github.com/en/actions 7 | # 2. https://github.com/features/actions 8 | 9 | name: ci-node 10 | on: 11 | push: 12 | paths: 13 | - "**.js" 14 | - "**.json" 15 | - "**.md" 16 | - "**.yaml" 17 | branches: 18 | - main 19 | tags: 20 | - v* 21 | pull_request: 22 | paths: 23 | - "**.js" 24 | - "**.json" 25 | - "**.md" 26 | - "**.yaml" 27 | 28 | jobs: 29 | lint: 30 | runs-on: ubuntu-latest 31 | steps: 32 | - name: Print metadata and context information 33 | run: | 34 | echo "Git SHA: $GITHUB_SHA" 35 | echo "Git Ref: $GITHUB_REF" 36 | echo "Workflow Actor: $GITHUB_ACTOR" 37 | - name: Checkout repository 38 | uses: actions/checkout@v2 39 | - name: Setup Node.js version 16 40 | uses: actions/setup-node@v2.4.1 41 | with: 42 | node-version: "16" 43 | cache: "npm" 44 | - name: Install Node modules 45 | run: npm install --no-package-lock 46 | - name: Run linters in CI/CD mode 47 | run: npm run lint:ci 48 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | # Copyright (c) 2016-present Sven Greb 2 | # This source code is licensed under the MIT license found in the license file. 3 | 4 | # Path match pattern to intentionally ignore untracked files and directories. 5 | # See https://git-scm.com/docs/gitignore for more details. 6 | 7 | # +---------+ 8 | # + Node.js + 9 | # +---------+ 10 | node_modules/ 11 | -------------------------------------------------------------------------------- /.husky/pre-commit: -------------------------------------------------------------------------------- 1 | #!/bin/sh 2 | 3 | # Copyright (c) 2016-present Sven Greb 4 | # This source code is licensed under the MIT license found in the license file. 5 | 6 | # Git "pre-commit" hook for husky. 7 | # References: 8 | # 1. https://github.com/typicode/husky 9 | # 2. https://git-scm.com/docs/githooks#_pre_commit 10 | 11 | . "$(dirname "$0")/_/husky.sh" 12 | 13 | npm exec lint-staged 14 | -------------------------------------------------------------------------------- /.mailmap: -------------------------------------------------------------------------------- 1 | # Copyright (c) 2016-present Sven Greb 2 | # This source code is licensed under the MIT license found in the license file. 3 | 4 | # Configuration for the Git mail mapping feature to coalesce together commits by the same person in the shortlog, 5 | # where their name and/or email address was spelled differently or has been changed. 6 | # See https://git-scm.com/docs/git-shortlog#_mapping_authors for more details. 7 | Sven Greb 8 | Sven Greb 9 | -------------------------------------------------------------------------------- /.npmrc: -------------------------------------------------------------------------------- 1 | # Copyright (c) 2016-present Sven Greb 2 | # This source code is licensed under the MIT license found in the license file. 3 | 4 | # Configurations for npm. 5 | # See https://docs.npmjs.com/cli/v7/configuring-npm/npmrc for more details. 6 | 7 | # Only use a lockfile for single-consumer projects, like applications, but not for multi-consumer projects like 8 | # libraries. 9 | # It helps to pin dependency versions, improves the security through integrity checksums, prevents possible errors 10 | # caused by updated transitive dependencies and allows to get deterministic build results, but it can hide problems in 11 | # multi-consumer projects when any later versions of a used dependency, or its transitive dependencies, is not 12 | # compatible with the own project anymore. 13 | package-lock=true 14 | 15 | # Do not resolve to the latest minor and patch updates. 16 | # Automatically pin dependencies to exact versions instead of resolving to latest minor and patch updates. 17 | # This prevents possible errors caused by updated transitive dependencies. 18 | save-exact=true 19 | -------------------------------------------------------------------------------- /.prettierignore: -------------------------------------------------------------------------------- 1 | # Copyright (c) 2016-present Sven Greb 2 | # This source code is licensed under the MIT license found in the license file. 3 | 4 | # Path match pattern to ignore (i.e. not reformat) certain files and folders. 5 | # See https://prettier.io/docs/en/ignore for more details. 6 | 7 | .husky/_/ 8 | node_modules/ 9 | -------------------------------------------------------------------------------- /.remarkignore: -------------------------------------------------------------------------------- 1 | # Copyright (c) 2016-present Sven Greb 2 | # This source code is licensed under the MIT license found in the license file. 3 | 4 | # Path match pattern to ignore when searching for files. 5 | # See https://github.com/unifiedjs/unified-engine/blob/HEAD/doc/ignore.md for more details. 6 | 7 | node_modules/ 8 | -------------------------------------------------------------------------------- /.remarkrc.mjs: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright (c) 2016-present Sven Greb 3 | * This source code is licensed under the MIT license found in the license file. 4 | */ 5 | 6 | /** 7 | * Configurations for remark-lint. 8 | * @see https://github.com/remarkjs/remark-lint 9 | * @see https://remark.js.org 10 | */ 11 | 12 | export default { 13 | plugins: ["./packages/@svengreb/remark-preset-lint/index.js"], 14 | }; 15 | -------------------------------------------------------------------------------- /changelog.md: -------------------------------------------------------------------------------- 1 |

2 | 3 | 4 | 5 | 6 | 7 |

8 | 9 |

10 | 11 | 12 | 13 | 14 | 15 | 16 |

17 | 18 |

19 | 20 | 21 | 22 |

23 | 24 | 25 | 26 | # 0.5.0 27 | 28 | ![Release Date: 2023-04-27](https://img.shields.io/static/v1?style=flat-square&label=Release%20Date&message=2023-04-27&colorA=4c566a&colorB=88c0d0) [![Project Board](https://img.shields.io/static/v1?style=flat-square&label=Project%20Board&message=0.5.0&logo=github&logoColor=eceff4&colorA=4c566a&colorB=88c0d0)](https://github.com/users/svengreb/projects/10) [![Milestone](https://img.shields.io/static/v1?style=flat-square&label=Milestone&message=0.5.0&logo=github&logoColor=eceff4&colorA=4c566a&colorB=88c0d0)](https://github.com/svengreb/styleguide-markdown/milestones/4) 29 | 30 | ⇅ [Show all commits][34] 31 | 32 | This version [migrates this repository to the `@svengreb` GitHub account and npm package scope][58] and updates to [`remark-cli` major version `11`][59]. 33 | 34 | ## Improvements 35 | 36 |
37 | Update to tmpl template repository version 0.11.0 — #61 ⇄ #62 (⊶ 1641a0b1) 38 | 39 | → Updated to [`tmpl` version `0.11.0`][35], including the versions in between starting from [0.10.0][36]: 40 | 41 | 1. [Optimized GitHub action workflow scope][37]. 42 | 2. [Updated Node.js packages & GitHub actions][38] [^2] [^3]. 43 | 3. [Opts-in the Dependabot version update configuration][39]. 44 | 45 | This also includes changes required for any linter matches. 46 | 47 |
48 | 49 |
50 | svengreb GitHub account and @svengreb npm package scope migration — #63 ⇄ #64 (⊶ a49a8084) 51 | 52 | → With [the retirement of the _Arctic Ice Studio_ personal & Nord project brand][40] this project also moved to the _real-in-person_ identity “Sven Greb“ both in the context of the repository to [the `svengreb` GitHub account][41] and the `@svengreb` npm package scope. 53 | During this migration the only npm package [`@arcticicestudio/remark-preset-lint`][25] has been deprecated in favor of the new and upcoming [`@svengreb/remark-preset-lint`][43] that has been published afterwards. 54 | 55 | Also [the previous visual representation of this style guide][45] through the way too outdated and deprecated [GitBook][44] major version `2` has been unpublished and removed. The documentations and references have been updated to use the GitHub repository with the Markdown rendering instead for now until a custom website has been implemented using a modern _TechStack_ like [Next.js][46]. 56 | 57 |
58 | 59 |
60 | Update to remark-cli version 11.0.0 — #65 ⇄ #66 (⊶ 57d2f2c8) 61 | 62 |

63 | 64 | 65 | 66 | 67 |

68 | 69 | → Updated to the [currently latest `remark-cli` major version `11`][47] which comes with minimal breaking changes and does not require rules-based migration steps. 70 | This includes updates to the used packages… 71 | 72 | - [`remark-footnotes`][14] — `^1.0.0` → [major version `4`][53] 73 | - Now [supports ESM][51]. 74 | - [`remark-frontmatter`][52] — `^1.0.0` → [major version `4`][54] 75 | - Now [supports ESM][51]. 76 | - [`remark-gfm`][15] — `^1.0.0` → [major version `3`][49] 77 | - Now [supports ESM][51]. 78 | - Added support for [GFM footnotes][50]. 79 | - [`remark-lint`][21] — `^8.0.0` → [major version `9`][56] 80 | - Now [supports ESM][51]. 81 | 82 | The following plugins now also [support ESM][51]: 83 | 84 | - `remark-lint-blockquote-indentation` 85 | - `remark-lint-checkbox-character-style` 86 | - `remark-lint-checkbox-content-indent` 87 | - `remark-lint-code-block-style` 88 | - `remark-lint-definition-case` 89 | - `remark-lint-definition-spacing` 90 | - `remark-lint-emphasis-marker` 91 | - `remark-lint-fenced-code-flag` 92 | - `remark-lint-fenced-code-marker` 93 | - `remark-lint-file-extension` 94 | - `remark-lint-final-definition` 95 | - `remark-lint-final-newline` 96 | - `remark-lint-first-heading-level` 97 | - `remark-lint-hard-break-spaces` 98 | - `remark-lint-heading-increment` 99 | - `remark-lint-heading-style` 100 | - `remark-lint-linebreak-style` 101 | - `remark-lint-link-title-style` 102 | - `remark-lint-list-item-bullet-indent` 103 | - `remark-lint-list-item-content-indent` 104 | - `remark-lint-list-item-indent` 105 | - `remark-lint-list-item-spacing` 106 | - `remark-lint-maximum-heading-length` 107 | - `remark-lint-maximum-line-length` 108 | - `remark-lint-no-auto-link-without-protocol` 109 | - `remark-lint-no-blockquote-without-marker` 110 | - `remark-lint-no-consecutive-blank-lines` 111 | - `remark-lint-no-duplicate-defined-urls` 112 | - `remark-lint-no-duplicate-definitions` 113 | - `remark-lint-no-duplicate-headings-in-section` 114 | - `remark-lint-no-duplicate-headings` 115 | - `remark-lint-no-emphasis-as-heading` 116 | - `remark-lint-no-empty-url` 117 | - `remark-lint-no-file-name-articles` 118 | - `remark-lint-no-file-name-consecutive-dashes` 119 | - `remark-lint-no-file-name-irregular-characters` 120 | - `remark-lint-no-file-name-mixed-case` 121 | - `remark-lint-no-file-name-outer-dashes` 122 | - `remark-lint-no-heading-content-indent` 123 | - `remark-lint-no-heading-indent` 124 | - `remark-lint-no-heading-like-paragraph` 125 | - `remark-lint-no-heading-punctuation` 126 | - `remark-lint-no-html` 127 | - `remark-lint-no-inline-padding` 128 | - `remark-lint-no-literal-urls` 129 | - `remark-lint-no-missing-blank-lines` 130 | - `remark-lint-no-multiple-toplevel-headings` 131 | - `remark-lint-no-paragraph-content-indent` 132 | - `remark-lint-no-reference-like-url` 133 | - `remark-lint-no-shell-dollars` 134 | - `remark-lint-no-shortcut-reference-image` 135 | - `remark-lint-no-shortcut-reference-link` 136 | - `remark-lint-no-table-indentation` 137 | - `remark-lint-no-tabs` 138 | - `remark-lint-no-undefined-references` 139 | - `remark-lint-no-unneeded-full-reference-image` 140 | - `remark-lint-no-unneeded-full-reference-link` 141 | - `remark-lint-no-unused-definitions` 142 | - `remark-lint-ordered-list-marker-style` 143 | - `remark-lint-ordered-list-marker-value` 144 | - `remark-lint-rule-style` 145 | - `remark-lint-strikethrough-marker` 146 | - `remark-lint-strong-marker` 147 | - `remark-lint-table-cell-padding` 148 | - `remark-lint-table-pipe-alignment` 149 | - `remark-lint-table-pipes` 150 | - `remark-lint-unordered-list-marker-style` 151 | 152 |
153 | 154 |
155 | Support for remark-lint-strikethrough-marker — #67 ⇄ #68 (⊶ 154b026e) 156 | 157 | → To warn when the number of strikethrough markers is inconsistent and does not use two strikethrough markers (`~~`) the [`remark-lint-strikethrough-marker`][57] has been added to support such checks. 158 | 159 |
160 | 161 | # 0.4.0 162 | 163 | ![Release Date: 2021-04-06](https://img.shields.io/static/v1?style=flat-square&label=Release%20Date&message=2021-04-06&colorA=4c566a&colorB=88c0d0) [![Project Board](https://img.shields.io/static/v1?style=flat-square&label=Project%20Board&message=0.4.0&logo=github&logoColor=eceff4&colorA=4c566a&colorB=88c0d0)](https://github.com/users/svengreb/projects/10) [![Milestone](https://img.shields.io/static/v1?style=flat-square&label=Milestone&message=0.4.0&logo=github&logoColor=eceff4&colorA=4c566a&colorB=88c0d0)](https://github.com/svengreb/styleguide-markdown/milestones/3) 164 | 165 | ⇅ [Show all commits][9] 166 | 167 | This version changes this repository into a [monorepo][32] [^1], deprecates the [remark-preset-lint-arcticicestudio][8] package in favour of the new [@arcticicestudio/remark-preset-lint][25] package and adds support for [remark `13.0.0`][23]. 168 | 169 | ## Feature 170 | 171 |
172 | Monorepo with remark packages — #10 ⇄ #12 (⊶ 0c21fabc) 173 | 174 | ↠ Before this change this repository only contained the actual style guide documentation while specific projects that implement the guidelines for linters and code style analyzer lived in separate repositories. This was the best approach for modularity and a small and clear code base, but it increased the maintenance overhead by `1(n)` since changes to the development workflow or toolbox, general project documentations as well as dependency management required changes in every repository with dedicated tickets/issues and PRs. In particular, Node packages require frequent dependency management due to their fast development cycles to keep up-to-date with the latest package changes like (security) bug fixes. 175 | 176 | This style guide was implemented by the [remark-preset-lint-arcticicestudio][8] Node package that lived in its own repository. The development workflow was clean using most of GitHub's awesome features like project boards, _codeowner_ assignments, issue & PR automation and so on, but changes often required multiple actions when packages depend on each other or they use the same development tooling and documentation standards. 177 | 178 | ### Monorepo Comparison 179 | 180 | [Monorepos][32] [^1] are a fantastic way to manage such a project structure, but there are also some points that must be taken into account: 181 | 182 | - **No more scoped code** — the developer experience with Git is slightly worse because commits can contains changes to multiple scopes of the code. Since there is only a “transparent separation” of code, that was previously located in a dedicated repository but is not aggregated into a parent (e.g. `packages`) with other modules, commits can now contain changes to multiple code scopes spread over the entire code base. 183 | - **No more assignment of commits to single modules** — like described in the bullet point above, commit can contain changes to multiple modules, it is harder to detect which commit targeted a specific module. 184 | - **Steeper learning curve for new contributors** — in a dedicated repository that only hosts a specific module it is easier for new developers to contribute to the project, but in a monorepo they might need to change code in multiple places within other modules or the root code/documentation of the entire project. 185 | - **Uniform version number** — in order to keep conform to [SemVer][29], the entire project must use a uniform version number. This means that a module that has not been changed since the last version must also be incremented in order to keep compatible with the other modules. 186 | Using different version numbers prefixed/suffixed with an individual version number **is a not an option**, **increases the maintenance overhead** and **and drastically reduces the project overview and quality**! This would result in multiple Git tags on the `main` branch as well as “empty” changelogs and release notes with placeholder logs that only refer to changes of other modules. 187 | 188 | ### Project Future 189 | 190 | Even though a _monorepo_ required some special thoughts, it also comes with a lot of benefits and makes sense **for specific project modules that are slightly coupled** and where using dedicated repositories only increases the maintenance overhead **when changes must be reflected in multiple modules anyway**. 191 | 192 | In order to reduce the maintenance overhead, the [remark-preset-lint-arcticicestudio][8] Node package has been migrated into this repository by adapting to [Yarn workspaces][33]. This simplifies the development tooling setup and allows to use a unified documentation base as well as a smoother development and testing workflow. 193 | 194 | This change also implies that the root of the repository is the main package for the entire project setup including shared development dependencies, tools and documentations while the packages only contain specific configurations and (dev)dependencies. 195 | 196 | ### Scoped Packages 197 | 198 | Before [remark-preset-lint-arcticicestudio][8] was not a [scoped package][27] but suffixed with `-arcticicestudio`. To simplify the naming and improving the usage of user/organization specific packages, it is now scoped to `@arcticicestudio` resulting in the new name `@arcticicestudio/remark-preset-lint`. 199 | The currently released public version has been deprecated using the [`npm deprecate` command][26] where the provided message points out to migrate to the new scoped packages. 200 | 201 | ### Versioning 202 | 203 | The style guide itself and all packages use a shared/fixed/locked version. This helps all packages to keep in sync and ensure the compatibility with the latest style guide version. 204 | 205 |
206 | 207 |
208 | Update to remark 13.0.0 (micromark) — #28 ⇄ #29 (⊶ 9ff968f6) 209 | 210 |

211 | 212 | 213 | 214 | 215 |

216 | 217 | ↠ [remark 13.0.0][23] is a giant change for remark that replaced the 5+ year old internals with a new low-level parser called [micromark][12]. It comes with 100% CommonMark (and GFM as an extension) compliance and is a good base for the future of remark and Markdown. 218 | 219 | ### Migration 220 | 221 | This projects uses remark through the [remark-lint][21] plugin, which introduced support for remark `13.0.0` in its [package version `8.0.0`][17], and the [remark-cli][24] package, which comes with support for remark `13.0.0` in its [package version `9.0.0`][22]. 222 | 223 | - **Updated `remark-cli`** — bumped minimum version from [`5.0.0` to `9.0.0`][13] 224 | - **Updated `remark-lint`** — bumped minimum version from [`6.0.1` to `8.0.0`][16] 225 | - **Updated all `remark-lint-*` packages** — the [`@arcticicestudio/remark-preset-lint`][25] packages supports all `remark-lint-*` core rule packages whose minimum versions are now bumped to the major version that introduced support for remark `13.0.0`. 226 | - **Added [`remark-gfm` plugin][15]** — the support for [GitHub Flavored Markdown][1] has been moved into the `remark-gfm` plugin. 227 | - **Added [`remark-footnotes` plugin][14]** — adds support for [Pandoc][28] footnotes. 228 | - **Validated the code base with new linter rules** — Run checks with updated packages afterwards to fix and improve results found by linters. 229 | 230 | ### Features 231 | 232 | Because most package versions that are currently used were not up-to-date before, support for new features like core rules has also been added: 233 | 234 | - **Support for [`remark-lint-no-duplicate-defined-urls`][18]** — the core rule warns when definitions define the same URL. 235 | - **Support for [`remark-lint-no-unneeded-full-reference-image`][19]** — the core rule warns when full reference images are used that could be collapsed. 236 | - **Support for [`remark-lint-no-unneeded-full-reference-link`][20]** — the core rule warns when full reference links are used that could be collapsed. 237 | 238 |
239 | 240 | ## Improvements 241 | 242 |
243 | Plain text format for license file — #6 (⊶ a6f53c13) by @amayer5125 244 | 245 | ↠ Refactored the `LICENSE.md` file to use plain text instead of Markdown syntax and removed the `.md` file extension leaving the file named as `LICENSE`. 246 | Therefore the linting ignore statements have also been removed as well as adjusting the actual text to match exactly the one of the [MIT license][7]. 247 | This allows GitHub to display “MIT“ as the license instead of just showing a “View license“ placeholder text. 248 | 249 |
250 | 251 |
252 | “tmpl“ template repository migration — #11 ⇄ #13 (⊶ 47660393) 253 | 254 |

255 | 256 | 257 | 258 | 259 | 260 |

261 | 262 | ↠ Migrated the project setup, structure and development workflow [from version 0.9.0][30] of the [“tmpl“ template repository][31]. 263 | Additionally specific assets like the repository hero image have been replaced and documentations like the _README_ and GitHub issue/PR templates adjusted. 264 | 265 |
266 | 267 | ## Bug Fixes 268 | 269 |
270 | Invalid list entry character in documentation summary — #5 (⊶ 2fe4ad65) by @amayer5125 271 | 272 | ↠ Changed the invalid list entry character from `*` to `-` in the summary of the documentation to adhere to the style guide and fix failing CI builds. 273 | 274 |
275 | 276 | ## Tasks 277 | 278 |
279 | Update remark URLs to reflect master → main branch renaming — #7 (⊶ 23130286) by @outloudvi 280 | 281 | ↠ Updated the default branch name from `master` to `main` which is a global change due to recent humanity movements. Also see #21 (or the entry in this version changelog) for more details about how this projects also adapted this change. 282 | 283 |
284 | 285 |
286 | GitHub Flow migration — #19 ⇄ #20 (⊶ cf6f3fa2) 287 | 288 |

289 | 290 | 291 | 292 |

293 | 294 | > Subtask of svengreb/styleguide-git#9 295 | 296 | ↠ Adapted to [GitHub Flow][11] like documented in detail in the main task issue svengreb/styleguide-git#9. 297 | 298 |
299 | 300 |
301 | From master to main — #21 ⇄ #22 (⊶ c7946f2e) 302 | 303 |

304 | 305 | 306 | 307 |

308 | 309 | > Subtask of svengreb/styleguide-git#11 310 | 311 | ↠ Adapted to the [default branch renaming from `master` to `main`][10] like documented in detail in the main task issue svengreb/styleguide-git#11. 312 | 313 |
314 | 315 | # 0.2.0 316 | 317 | ![Release Date: 2018-11-15](https://img.shields.io/static/v1?style=flat-square&label=Release%20Date&message=2018-11-15&colorA=4c566a&colorB=88c0d0) [![Project Board](https://img.shields.io/static/v1?style=flat-square&label=Project%20Board&message=0.2.0&logo=github&logoColor=eceff4&colorA=4c566a&colorB=88c0d0)](https://github.com/users/svengreb/projects/10) [![Milestone](https://img.shields.io/static/v1?style=flat-square&label=Milestone&message=0.2.0&logo=github&logoColor=eceff4&colorA=4c566a&colorB=88c0d0)](https://github.com/svengreb/styleguide-markdown/milestones/2) 318 | 319 | ⇅ [Show all commits][6] 320 | 321 | ## Improvements 322 | 323 | ### Rules 324 | 325 |
326 | Change unordered marker from asterisk to dash — #3 ⇄ #4 (⊶ fea20a63) 327 | 328 | ↠ Changed [unordered list marker][5] from asterisk `*` to dash `-` because asterisks can be confused for bold/italic markers. This also aligns with the default format of Prettier. 329 | 330 |
331 | 332 | # 0.1.0 333 | 334 | ![Release Date: 2018-02-15](https://img.shields.io/static/v1?style=flat-square&label=Release%20Date&message=2018-02-15&colorA=4c566a&colorB=88c0d0) [![Project Board](https://img.shields.io/static/v1?style=flat-square&label=Project%20Board&message=0.1.0&logo=github&logoColor=eceff4&colorA=4c566a&colorB=88c0d0)](https://github.com/users/svengreb/projects/10) [![Milestone](https://img.shields.io/static/v1?style=flat-square&label=Milestone&message=0.1.0&logo=github&logoColor=eceff4&colorA=4c566a&colorB=88c0d0)](https://github.com/svengreb/styleguide-markdown/milestones/1) 335 | 336 | ⇅ [Show all commits][4] 337 | 338 | ## Features 339 | 340 | ### Rules 341 | 342 |
343 | Change unordered marker from asterisk to dash — #1 ⇄ #2 (⊶ 261fe4cb) 344 | 345 | ↠ Added the initial style guide with the [comprehensive base rule set][3] with support for [GitHub Flavored Markdown][1] which is based on the [CommonMark][2] specification. 346 | 347 |
348 | 349 |

350 | 351 | 352 | 353 | 354 | 355 |

356 | 357 |

358 | Copyright © 2016-present Sven Greb 359 |

360 | 361 |

362 | 363 | 364 | 365 | 366 | 367 | 368 |

369 | 370 | 387 | 388 | 389 | 390 | 391 | 392 | [1]: https://github.github.com/gfm 393 | [2]: https://commonmark.org 394 | [3]: https://github.com/svengreb/styleguide-markdown/blob/main/rules/index.md 395 | [25]: https://www.npmjs.com/package/@arcticicestudio/remark-preset-lint 396 | [14]: https://github.com/remarkjs/remark-footnotes 397 | [15]: https://github.com/remarkjs/remark-gfm 398 | [21]: https://github.com/remarkjs/remark-lint 399 | 400 | 401 | 402 | [4]: https://github.com/svengreb/styleguide-markdown/compare/e894a349...v0.1.0 403 | 404 | 405 | 406 | [5]: https://github.com/svengreb/styleguide-markdown/blob/main/rules/lists.md#unordered-marker 407 | [6]: https://github.com/svengreb/styleguide-markdown/compare/v0.1.0...v0.2.0 408 | 409 | 410 | 411 | [7]: https://choosealicense.com/licenses/mit 412 | [8]: https://www.npmjs.com/package/remark-preset-lint-arcticicestudio 413 | [9]: https://github.com/svengreb/styleguide-markdown/compare/v0.2.0...v0.4.0 414 | [10]: https://github.com/github/renaming 415 | [11]: https://docs.github.com/en/get-started/quickstart/github-flow 416 | [12]: https://github.com/micromark/micromark 417 | [13]: https://github.com/remarkjs/remark/compare/remark-cli@5.0.0...remark-cli@9.0.0 418 | [16]: https://github.com/remarkjs/remark-lint/compare/6.0.0...8.0.0 419 | [17]: https://github.com/remarkjs/remark-lint/releases/tag/8.0.0 420 | [18]: https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-duplicate-defined-urls 421 | [19]: https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-unneeded-full-reference-image 422 | [20]: https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-unneeded-full-reference-link 423 | [22]: https://github.com/remarkjs/remark/releases/tag/remark-cli%409.0.0 424 | [23]: https://github.com/remarkjs/remark/releases/tag/13.0.0 425 | [24]: https://github.com/remarkjs/remark 426 | [26]: https://docs.npmjs.com/cli/v9/commands/npm-deprecate 427 | [27]: https://docs.npmjs.com/about-scopes 428 | [28]: https://pandoc.org 429 | [29]: https://semver.org 430 | [30]: https://github.com/svengreb/tmpl/releases/tag/v0.9.0 431 | [32]: https://monorepo.tools 432 | [31]: https://github.com/svengreb/tmpl 433 | [33]: https://classic.yarnpkg.com/en/docs/workspaces 434 | 435 | 436 | 437 | [34]: https://github.com/svengreb/styleguide-markdown/compare/v0.4.0...v0.5.0 438 | [35]: https://github.com/svengreb/tmpl/releases/tag/v0.11.0 439 | [36]: https://github.com/svengreb/tmpl/releases/tag/v0.10.0 440 | [37]: https://github.com/svengreb/tmpl/issues/84 441 | [38]: https://github.com/svengreb/tmpl/issues/86 442 | [39]: https://github.com/svengreb/tmpl/issues/94 443 | [40]: https://github.com/orgs/nordtheme/discussions/183#retire-arctic-ice-studio-as-nord-brand 444 | [41]: https://github.com/svengreb 445 | [43]: https://www.npmjs.com/package/@svengreb/remark-preset-lint 446 | [44]: https://www.gitbook.com 447 | [45]: https://arcticicestudio.github.io/styleguide-markdown 448 | [46]: https://nextjs.org 449 | [47]: https://github.com/remarkjs/remark/releases/tag/remark-cli%4011.0.0 450 | [49]: https://github.com/remarkjs/remark-gfm/releases/tag/3.0.0 451 | [50]: https://github.blog/changelog/2021-09-30-footnotes-now-supported-in-markdown-fields 452 | [51]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c 453 | [52]: https://github.com/remarkjs/remark-frontmatter 454 | [53]: https://github.com/remarkjs/remark-footnotes/releases/tag/4.0.0 455 | [54]: https://github.com/remarkjs/remark-frontmatter/releases/tag/4.0.0 456 | [56]: https://github.com/remarkjs/remark-frontmatter/releases/tag/9.0.0 457 | [57]: https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-strikethrough-marker 458 | [58]: https://github.com/svengreb/styleguide-markdown/issues/63 459 | [59]: https://github.com/svengreb/styleguide-markdown/issues/65 460 | 461 | 462 | 463 | 464 | 465 | 466 | 467 | [^1]: https://trunkbaseddevelopment.com/monorepos 468 | 469 | 470 | 471 | [^2]: https://github.com/svengreb/tmpl/issues/78 472 | [^3]: https://github.com/svengreb/tmpl/issues/83 473 | -------------------------------------------------------------------------------- /license: -------------------------------------------------------------------------------- 1 | MIT License (MIT) 2 | 3 | Copyright (c) 2016-present Sven Greb (https://www.svengreb.de) 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /lint-staged.config.js: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright (c) 2016-present Sven Greb 3 | * This source code is licensed under the MIT license found in the license file. 4 | */ 5 | 6 | /** 7 | * Configurations for lint-staged. 8 | * @see https://github.com/okonet/lint-staged#configuration 9 | */ 10 | module.exports = { 11 | "*.{json,yaml}": "prettier --check --ignore-unknown --no-editorconfig", 12 | "*.{js,mjs}": ["eslint", "prettier --check --ignore-unknown --no-editorconfig"], 13 | "*.md": ["remark --no-stdout", "prettier --check --ignore-unknown --no-editorconfig"], 14 | ".husky/pre-*": "prettier --check --ignore-unknown --no-editorconfig", 15 | }; 16 | -------------------------------------------------------------------------------- /package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "@svengreb/styleguide-markdown", 3 | "version": "0.5.0", 4 | "description": "An opinionated, yet universally applicable Markdown code style guide", 5 | "author": { 6 | "name": "Sven Greb", 7 | "email": "development@svengreb.de", 8 | "url": "https://www.svengreb.de" 9 | }, 10 | "homepage": "https://github.com/svengreb/styleguide-markdown", 11 | "repository": { 12 | "type": "git", 13 | "url": "git+https://github.com/svengreb/styleguide-markdown.git" 14 | }, 15 | "bugs": { 16 | "url": "https://github.com/svengreb/styleguide-markdown/issues" 17 | }, 18 | "license": "MIT", 19 | "private": true, 20 | "engines": { 21 | "node": ">=15.13", 22 | "npm": ">=7.7" 23 | }, 24 | "workspaces": [ 25 | "packages/@svengreb/*" 26 | ], 27 | "scripts": { 28 | "format": "run-s format:*", 29 | "format:js": "eslint --fix .", 30 | "format:pretty": "prettier --ignore-unknown --no-editorconfig --write \"**\"", 31 | "lint": "run-s lint:js lint:md lint:pretty", 32 | "lint:ci": "run-s --continue-on-error lint:js lint:md lint:ci:pretty", 33 | "lint:ci:pretty": "prettier --check --ignore-unknown --loglevel silent --no-editorconfig --no-error-on-unmatched-pattern \"**\"", 34 | "lint:js": "eslint --ext js,mjs .", 35 | "lint:md": "remark --no-stdout . .github/", 36 | "lint:pretty": "prettier --check --ignore-unknown --no-editorconfig \"**\"", 37 | "prepare": "run-s prepare:*", 38 | "prepare:husky": "husky install", 39 | "test": "npm --workspaces run test" 40 | }, 41 | "devDependencies": { 42 | "@arcticicestudio/eslint-config-base": ">=0.11.0 <1.0.0", 43 | "eslint": "8.39.0", 44 | "eslint-config-prettier": "8.8.0", 45 | "eslint-plugin-import": "2.27.5", 46 | "eslint-plugin-prettier": "4.2.1", 47 | "husky": "8.0.3", 48 | "lint-staged": "13.2.2", 49 | "npm-run-all": "4.1.5", 50 | "prettier": "2.8.8", 51 | "prettier-plugin-sh": "0.12.8", 52 | "remark-cli": "11.0.0" 53 | } 54 | } 55 | -------------------------------------------------------------------------------- /packages/@svengreb/remark-preset-lint/index.js: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright (c) 2016-present Sven Greb 3 | * This source code is licensed under the MIT license found in the license file. 4 | */ 5 | 6 | import remarkLint from "remark-lint"; 7 | 8 | /* eslint-disable import/extensions */ 9 | import blockquotes from "./rules/blockquotes.js"; 10 | import code from "./rules/code.js"; 11 | import emphasis from "./rules/emphasis.js"; 12 | import headings from "./rules/headings.js"; 13 | import horizontalRules from "./rules/horizontal-rules.js"; 14 | import links from "./rules/links.js"; 15 | import lists from "./rules/lists.js"; 16 | import namingConventions from "./rules/naming-conventions.js"; 17 | import paragraphs from "./rules/paragraphs.js"; 18 | import rawHTML from "./rules/raw-html.js"; 19 | import strings from "./rules/strings.js"; 20 | import support from "./rules/support.js"; 21 | import tables from "./rules/tables.js"; 22 | import whitespace from "./rules/whitespace.js"; 23 | /* eslint-enable import/extensions */ 24 | 25 | /** 26 | * An opinionated, yet universally applicable Markdown code style guide rules as an extensible remark-lint rule preset. 27 | * @version 0.5.0 28 | * @license MIT 29 | * @author Sven Greb 30 | * @copyright 2016-present Sven Greb 31 | * @see https://remark.js.org 32 | * @see https://github.com/remarkjs/remark-lint 33 | * @see https://github.com/remarkjs/remark-lint/blob/main/doc/rules.md#list-of-rules 34 | * @see https://github.com/remarkjs/remark-lint#configuring-remark-lint 35 | */ 36 | const preset = { 37 | plugins: [ 38 | remarkLint, 39 | blockquotes, 40 | code, 41 | emphasis, 42 | headings, 43 | horizontalRules, 44 | links, 45 | lists, 46 | namingConventions, 47 | paragraphs, 48 | rawHTML, 49 | strings, 50 | support, 51 | tables, 52 | whitespace, 53 | ], 54 | }; 55 | 56 | export default preset; 57 | -------------------------------------------------------------------------------- /packages/@svengreb/remark-preset-lint/package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "@svengreb/remark-preset-lint", 3 | "version": "0.5.0", 4 | "description": "The opinionated, yet universally applicable Markdown code style guide rules as an extensible remark-lint rule preset", 5 | "author": { 6 | "name": "Sven Greb", 7 | "email": "development@svengreb.de", 8 | "url": "https://www.svengreb.de" 9 | }, 10 | "homepage": "https://github.com/svengreb/styleguide-markdown", 11 | "repository": { 12 | "type": "git", 13 | "url": "git+https://github.com/svengreb/styleguide-markdown.git" 14 | }, 15 | "bugs": { 16 | "url": "https://github.com/svengreb/styleguide-markdown/issues" 17 | }, 18 | "license": "MIT", 19 | "engines": { 20 | "node": ">=15.13", 21 | "npm": ">=7.7" 22 | }, 23 | "main": "index.js", 24 | "type": "module", 25 | "files": [ 26 | "rules", 27 | "index.js" 28 | ], 29 | "funding": { 30 | "type": "github", 31 | "url": "https://github.com/sponsors/svengreb" 32 | }, 33 | "keywords": [ 34 | "style", 35 | "guide", 36 | "markdown", 37 | "remark", 38 | "remark-lint", 39 | "rule", 40 | "preset" 41 | ], 42 | "publishConfig": { 43 | "access": "public" 44 | }, 45 | "dependencies": { 46 | "remark-footnotes": "^4.0.1", 47 | "remark-frontmatter": "^4.0.1", 48 | "remark-gfm": "^3.0.1", 49 | "remark-lint": "^9.1.1", 50 | "remark-lint-blockquote-indentation": "^3.1.1", 51 | "remark-lint-checkbox-character-style": "^4.1.1", 52 | "remark-lint-checkbox-content-indent": "^4.1.1", 53 | "remark-lint-code-block-style": "^3.1.0", 54 | "remark-lint-definition-case": "^3.1.1", 55 | "remark-lint-definition-spacing": "^3.1.1", 56 | "remark-lint-emphasis-marker": "^3.1.1", 57 | "remark-lint-fenced-code-flag": "^3.1.1", 58 | "remark-lint-fenced-code-marker": "^3.1.1", 59 | "remark-lint-file-extension": "^2.1.1", 60 | "remark-lint-final-definition": "^3.1.1", 61 | "remark-lint-final-newline": "^2.1.1", 62 | "remark-lint-first-heading-level": "^3.1.1", 63 | "remark-lint-hard-break-spaces": "^3.1.1", 64 | "remark-lint-heading-increment": "^3.1.1", 65 | "remark-lint-heading-style": "^3.1.1", 66 | "remark-lint-linebreak-style": "^3.1.1", 67 | "remark-lint-link-title-style": "^3.1.1", 68 | "remark-lint-list-item-bullet-indent": "^4.1.1", 69 | "remark-lint-list-item-content-indent": "^3.1.1", 70 | "remark-lint-list-item-indent": "^3.1.1", 71 | "remark-lint-list-item-spacing": "^4.1.1", 72 | "remark-lint-maximum-heading-length": "^3.1.1", 73 | "remark-lint-maximum-line-length": "^3.1.2", 74 | "remark-lint-no-auto-link-without-protocol": "^3.1.1", 75 | "remark-lint-no-blockquote-without-marker": "^5.1.1", 76 | "remark-lint-no-consecutive-blank-lines": "^4.1.2", 77 | "remark-lint-no-duplicate-defined-urls": "^2.1.1", 78 | "remark-lint-no-duplicate-definitions": "^3.1.1", 79 | "remark-lint-no-duplicate-headings": "^3.1.1", 80 | "remark-lint-no-duplicate-headings-in-section": "^3.1.1", 81 | "remark-lint-no-emphasis-as-heading": "^3.1.1", 82 | "remark-lint-no-empty-url": "^3.1.1", 83 | "remark-lint-no-file-name-articles": "^2.1.1", 84 | "remark-lint-no-file-name-consecutive-dashes": "^2.1.1", 85 | "remark-lint-no-file-name-irregular-characters": "^2.1.1", 86 | "remark-lint-no-file-name-mixed-case": "^2.1.1", 87 | "remark-lint-no-file-name-outer-dashes": "^2.1.1", 88 | "remark-lint-no-heading-content-indent": "^4.1.1", 89 | "remark-lint-no-heading-indent": "^4.1.1", 90 | "remark-lint-no-heading-like-paragraph": "^3.1.1", 91 | "remark-lint-no-heading-punctuation": "^3.1.1", 92 | "remark-lint-no-html": "^3.1.1", 93 | "remark-lint-no-inline-padding": "^4.1.1", 94 | "remark-lint-no-literal-urls": "^3.1.1", 95 | "remark-lint-no-missing-blank-lines": "^3.1.1", 96 | "remark-lint-no-multiple-toplevel-headings": "^3.1.1", 97 | "remark-lint-no-paragraph-content-indent": "^4.1.1", 98 | "remark-lint-no-reference-like-url": "^3.1.1", 99 | "remark-lint-no-shell-dollars": "^3.1.1", 100 | "remark-lint-no-shortcut-reference-image": "^3.1.1", 101 | "remark-lint-no-shortcut-reference-link": "^3.1.1", 102 | "remark-lint-no-table-indentation": "^4.1.1", 103 | "remark-lint-no-tabs": "^3.1.1", 104 | "remark-lint-no-undefined-references": "^4.2.0", 105 | "remark-lint-no-unneeded-full-reference-image": "^3.1.1", 106 | "remark-lint-no-unneeded-full-reference-link": "^3.1.1", 107 | "remark-lint-no-unused-definitions": "^3.1.1", 108 | "remark-lint-ordered-list-marker-style": "^3.1.1", 109 | "remark-lint-ordered-list-marker-value": "^3.1.1", 110 | "remark-lint-rule-style": "^3.1.1", 111 | "remark-lint-strikethrough-marker": "^2.1.1", 112 | "remark-lint-strong-marker": "^3.1.1", 113 | "remark-lint-table-cell-padding": "^4.1.2", 114 | "remark-lint-table-pipe-alignment": "^3.1.1", 115 | "remark-lint-table-pipes": "^4.1.1", 116 | "remark-lint-unordered-list-marker-style": "^3.1.1" 117 | }, 118 | "devDependencies": { 119 | "remark-cli": "^11.0.0" 120 | }, 121 | "peerDependencies": { 122 | "remark-cli": "^11.0.0" 123 | } 124 | } 125 | -------------------------------------------------------------------------------- /packages/@svengreb/remark-preset-lint/readme.md: -------------------------------------------------------------------------------- 1 |

2 | 3 | 4 | 5 | 6 | 7 |

8 | 9 |

10 | 11 | 12 | 13 | 14 | 15 | 16 |

17 | 18 |

19 | 20 | 21 | 22 | 23 | 24 | 25 |

26 | 27 |

28 | 29 | 30 | 31 |

32 | 33 |

34 | 35 | 36 | 37 | 38 | 39 | 40 | 41 | 42 | 43 |

44 | 45 |

The opinionated, yet universally applicable Markdown code style guide rules as an extensible remark-lint rule preset.

46 | 47 | This package implements the rules of the [Sven Greb Markdown style guide][1] as an extensible [remark-lint][9] rule preset. It supports all [official core rules][7] and [various plugins][4] like the [“frontmatter” Markdown extension][5] for [YAML][18] and [TOML][10] and [“GitHub Flavoured” Markdown][6]. 48 | 49 | ## Getting Started 50 | 51 | Note that this package uses [npm version 7.7.0 or higher][2] as the main package manager, but the documentations also include instructions to work with [Yarn][19] (classic / `v1`). 52 | 53 | ### Installation 54 | 55 | Add the package as development dependency to your project: 56 | 57 | ```sh 58 | # With npm... 59 | npm install --save-dev @svengreb/remark-preset-lint 60 | 61 | # or Yarn. 62 | yarn add --dev @svengreb/remark-preset-lint 63 | ``` 64 | 65 | Note that [peer dependencies][12], like the [remark-lint][9] package itself, are **only installed automatically when using a npm version equal or higher than `7.0.0`**, otherwise they must be installed separately like described in the [peer dependencies](#peer-dependencies) section below. 66 | See the [Node distribution index][13] for more information about which npm version is bundled with which Node version. 67 | 68 | #### Peer Dependencies 69 | 70 | This package depends on [various remark-lint rule packages][8] that are defined as [peer dependencies][12]. 71 | 72 | ##### npm versions `>=7.0.0` 73 | 74 | As of **npm version `7.0.0`, peer dependencies are** [**installed automatically**][3] and does not require any additional steps. 75 | 76 | ##### npm versions `>=5.0.0 <7.0.0` 77 | 78 | For **npm version equal to or higher than `5.0.0` (pre-bundled with [Node.js 8][14]) but less than `7.0.0`**, all peer dependencies can be auto-installed using the pre-bundled [`npx`][16] package: 79 | 80 | ```sh 81 | npx install-peerdeps --dev @svengreb/remark-preset-lint 82 | ``` 83 | 84 | ##### npm versions `<5.0.0` 85 | 86 | If you’re using a **npm version less than `5.0.0`**, the `npx` package is not pre-bundled, but users can either simply install the [`npx`][16] package globally to run the above command or use the [install-peerdeps][15] helper package locally/globally to let it handle the installation of all peer dependencies: 87 | 88 | ```sh 89 | # Install and use the "install-peerdeps" helper package locally... 90 | npm install install-peerdeps 91 | ./node_modules/.bin/install-peerdeps --dev @svengreb/remark-preset-lint 92 | 93 | # ...or globally. 94 | npm install --global install-peerdeps 95 | install-peerdeps --dev @svengreb/remark-preset-lint 96 | ``` 97 | 98 | To install all peer dependencies manually without `npx` or any helper package, the npm `info` command can be used to get a list of all packages and their versions: 99 | 100 | ```sh 101 | # List the names and versions of all peer dependencies... 102 | npm info "@svengreb/remark-preset-lint" peerDependencies 103 | 104 | # ...and install each listed package manually. 105 | npm install PACKAGE@VERSION 106 | ``` 107 | 108 | ##### Using Yarn instead of npm 109 | 110 | If you’re not using npm but Yarn, peer dependencies can be installed by either adding them manually or using the [install-peerdeps][15] helper package: 111 | 112 | ```sh 113 | # Either add all packages manually by listing all required names and their versions and install them manually... 114 | yarn info @svengreb/remark-preset-lint peerDependencies 115 | yarn add --dev remark-lint #... 116 | 117 | # ...or use the "install-peerdeps" helper package. 118 | yarn add --dev install-peerdeps 119 | yarn run install-peerdeps --dev @svengreb/remark-preset-lint 120 | ``` 121 | 122 | ## Usage 123 | 124 | The package can be used as rule preset by adding it to the plugins within your `.remarkrc.js` or `.remarkrc` [configuration file][17]: 125 | 126 | ```js 127 | module.exports = { 128 | plugins: ["@svengreb/remark-preset-lint"], 129 | }; 130 | ``` 131 | 132 | ## Contributing 133 | 134 | Please read the [contribution guidelines][11] of the [Sven Greb Markdown style guide][1] for more details. 135 | 136 |

137 | 138 | 139 | 140 | 141 | 142 |

143 | 144 |

145 | Copyright © 2016-present Sven Greb 146 |

147 | 148 |

149 | 150 | 151 | 152 | 153 | 154 | 155 |

156 | 157 | [1]: https://github.com/svengreb/styleguide-markdown 158 | [2]: https://github.blog/2020-10-13-presenting-v7-0-0-of-the-npm-cli 159 | [3]: https://github.com/npm/rfcs/blob/main/implemented/0025-install-peer-deps.md 160 | [4]: https://github.com/remarkjs/remark/blob/main/doc/plugins.md 161 | [5]: https://github.com/remarkjs/remark-frontmatter 162 | [6]: https://github.com/remarkjs/remark-gfm 163 | [7]: https://github.com/remarkjs/remark-lint/blob/main/doc/rules.md#list-of-rules 164 | [8]: https://github.com/remarkjs/remark-lint/tree/main/packages 165 | [9]: https://github.com/remarkjs/remark-lint 166 | [10]: https://github.com/toml-lang/toml 167 | [11]: https://github.com/svengreb/.github/blob/main/contributing.md 168 | [12]: https://nodejs.org/en/blog/npm/peer-dependencies 169 | [13]: https://nodejs.org/dist/index.json 170 | [14]: https://nodejs.org/dist/latest-v8.x 171 | [15]: https://www.npmjs.com/package/install-peerdeps 172 | [16]: https://www.npmjs.com/package/npx 173 | [17]: https://github.com/remarkjs/remark-lint#configuring-remark-lint 174 | [18]: https://yaml.org 175 | [19]: https://classic.yarnpkg.com 176 | -------------------------------------------------------------------------------- /packages/@svengreb/remark-preset-lint/rules/blockquotes.js: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright (c) 2016-present Sven Greb 3 | * This source code is licensed under the MIT license found in the license file. 4 | */ 5 | 6 | import blockquoteIndentation from "remark-lint-blockquote-indentation"; 7 | import noBlockquoteWithoutMarker from "remark-lint-no-blockquote-without-marker"; 8 | 9 | /** 10 | * Official remark-lint core rules for blockquote document nodes. 11 | * @see https://github.com/remarkjs/remark-lint/blob/main/doc/rules.md#list-of-rules 12 | */ 13 | const blockquotes = { 14 | plugins: [ 15 | /** 16 | * Enforce correct indentation for blockquotes. 17 | * @see https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-blockquote-indentation 18 | * @see https://github.com/svengreb/styleguide-markdown/blob/main/rules/blockquotes.md#indentation 19 | */ 20 | [blockquoteIndentation, ["error", 2]], 21 | /** 22 | * Disallow blank lines without markers ('>') in blockquotes. 23 | * @see https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-blockquote-without-marker 24 | * @see https://github.com/svengreb/styleguide-markdown/blob/main/rules/blockquotes.md#multi-line 25 | */ 26 | [noBlockquoteWithoutMarker, ["warn"]], 27 | ], 28 | }; 29 | 30 | export default blockquotes; 31 | -------------------------------------------------------------------------------- /packages/@svengreb/remark-preset-lint/rules/code.js: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright (c) 2016-present Sven Greb 3 | * This source code is licensed under the MIT license found in the license file. 4 | */ 5 | 6 | import codeBlockStyle from "remark-lint-code-block-style"; 7 | import fencedCodeFlag from "remark-lint-fenced-code-flag"; 8 | import fencedCodeMarker from "remark-lint-fenced-code-marker"; 9 | import noShellDollars from "remark-lint-no-shell-dollars"; 10 | 11 | /** 12 | * Official remark-lint core rules for code document nodes. 13 | * @see https://github.com/remarkjs/remark-lint/blob/main/doc/rules.md#list-of-rules 14 | */ 15 | const code = { 16 | plugins: [ 17 | /** 18 | * Enforce fenced code blocks. 19 | * @see https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-code-block-style 20 | * @see https://github.com/svengreb/styleguide-markdown/blob/main/rules/code.md#blocks 21 | */ 22 | [codeBlockStyle, ["error", "fenced"]], 23 | /** 24 | * Enforce language syntax flags for fenced code blocks. 25 | * @see https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-fenced-code-flag 26 | * @see https://github.com/svengreb/styleguide-markdown/blob/main/rules/code.md#syntax-highlighting 27 | */ 28 | [fencedCodeFlag, ["error", { allowEmpty: false }]], 29 | /** 30 | * Enforce language syntax flags for fenced code blocks. 31 | * @see https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-fenced-code-marker 32 | * @see https://github.com/svengreb/styleguide-markdown/blob/main/rules/code.md#marker-character-style 33 | */ 34 | [fencedCodeMarker, ["error", "`"]], 35 | /** 36 | * Warn when using a dollar sign ("$") in shell code. 37 | * @see https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-shell-dollars 38 | * @see https://github.com/svengreb/styleguide-markdown/blob/main/rules/code.md#no-shell-code-dollar-sign 39 | */ 40 | [noShellDollars, ["warn"]], 41 | ], 42 | }; 43 | 44 | export default code; 45 | -------------------------------------------------------------------------------- /packages/@svengreb/remark-preset-lint/rules/emphasis.js: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright (c) 2016-present Sven Greb 3 | * This source code is licensed under the MIT license found in the license file. 4 | */ 5 | 6 | import emphasisMarker from "remark-lint-emphasis-marker"; 7 | import noEmphasisAsHeading from "remark-lint-no-emphasis-as-heading"; 8 | import noInlinePadding from "remark-lint-no-inline-padding"; 9 | import strongMarker from "remark-lint-strong-marker"; 10 | 11 | /** 12 | * Official remark-lint core rules for emphasis document nodes. 13 | * @see https://github.com/remarkjs/remark-lint/blob/main/doc/rules.md#list-of-rules 14 | */ 15 | const emphasis = { 16 | plugins: [ 17 | /** 18 | * Enforce a consistent character style for emphasis marker. 19 | * @see https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-code-block-style 20 | * @see https://github.com/svengreb/styleguide-markdown/blob/main/rules/emphasis.md#italic 21 | * @see https://github.com/svengreb/styleguide-markdown/blob/main/rules/emphasis.md#bold 22 | * @see https://github.com/svengreb/styleguide-markdown/blob/main/rules/emphasis.md#strikethrough 23 | */ 24 | [emphasisMarker, ["warn", "consistent"]], 25 | /** 26 | * Warn when using emphasis elements (bold or italics) as replacement for headings. 27 | * @see https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-emphasis-as-heading 28 | * @see https://github.com/svengreb/styleguide-markdown/blob/main/rules/emphasis.md#no-header-replacement 29 | */ 30 | [noEmphasisAsHeading, ["warn"]], 31 | /** 32 | * Disallow inner padding within emphasis marker, code marker and link IDs. 33 | * @see https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-inline-padding 34 | * @see https://github.com/svengreb/styleguide-markdown/blob/main/rules/emphasis.md#no-inner-spacing 35 | * @see https://github.com/svengreb/styleguide-markdown/blob/main/rules/links.md#no-id-inner-spacing 36 | */ 37 | [noInlinePadding, ["error"]], 38 | /** 39 | * Enforce the character style for strong (bold) emphasis markers. 40 | * @see https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-strong-marker 41 | * @see https://github.com/svengreb/styleguide-markdown/blob/main/rules/emphasis.md#bold 42 | */ 43 | [strongMarker, ["error", "*"]], 44 | ], 45 | }; 46 | 47 | export default emphasis; 48 | -------------------------------------------------------------------------------- /packages/@svengreb/remark-preset-lint/rules/headings.js: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright (c) 2016-present Sven Greb 3 | * This source code is licensed under the MIT license found in the license file. 4 | */ 5 | 6 | import firstHeadingLevel from "remark-lint-first-heading-level"; 7 | import headingIncrement from "remark-lint-heading-increment"; 8 | import headingStyle from "remark-lint-heading-style"; 9 | import maximumHeadingLength from "remark-lint-maximum-heading-length"; 10 | import noDuplicateHeadings from "remark-lint-no-duplicate-headings"; 11 | import noDuplicateHeadingsInSection from "remark-lint-no-duplicate-headings-in-section"; 12 | import noHeadingContentIndent from "remark-lint-no-heading-content-indent"; 13 | import noHeadingIndent from "remark-lint-no-heading-indent"; 14 | import noHeadingLikeParagraph from "remark-lint-no-heading-like-paragraph"; 15 | import noHeadingPunctuation from "remark-lint-no-heading-punctuation"; 16 | import noMultipleToplevelHeadings from "remark-lint-no-multiple-toplevel-headings"; 17 | 18 | /** 19 | * Official remark-lint core rules for heading document nodes. 20 | * @see https://github.com/remarkjs/remark-lint/blob/main/doc/rules.md#list-of-rules 21 | */ 22 | const headings = { 23 | plugins: [ 24 | /** 25 | * Enforce a specific level for the first heading. 26 | * @see https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-first-heading-level 27 | */ 28 | [firstHeadingLevel, false], 29 | /** 30 | * Enforce headings to only increment by one at a time. 31 | * @see https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-heading-increment 32 | */ 33 | [headingIncrement, false], 34 | /** 35 | * Enforce ATX style headings. 36 | * @see https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-heading-style 37 | * @see https://github.com/svengreb/styleguide-markdown/blob/main/rules/headings.md#atx-style 38 | */ 39 | [headingStyle, ["error", "atx"]], 40 | /** 41 | * Warn if a maximum length for headings is exceeded. 42 | * @see https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-maximum-heading-length 43 | * @see https://github.com/svengreb/styleguide-markdown/blob/main/rules/headings.md#length 44 | */ 45 | [maximumHeadingLength, ["warn", 80]], 46 | /** 47 | * Warn when using two or more headers with the same content in the same markdown file. 48 | * @see https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-duplicate-headings 49 | * @see https://github.com/svengreb/styleguide-markdown/blob/main/rules/headings.md#no-duplicate 50 | */ 51 | [noDuplicateHeadings, ["warn"]], 52 | /** 53 | * Warn when using two or more headers with the same content in the same section. 54 | * @see https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-duplicate-headings-in-section 55 | * @see https://github.com/svengreb/styleguide-markdown/blob/main/rules/headings.md#no-duplicate 56 | */ 57 | [noDuplicateHeadingsInSection, ["warn"]], 58 | /** 59 | * Disallow invalid indention of headings content. 60 | * @see https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-heading-content-indent 61 | * @see https://github.com/svengreb/styleguide-markdown/blob/main/rules/headings.md#content-spacing 62 | */ 63 | [noHeadingContentIndent, ["error"]], 64 | /** 65 | * Disallow indention and any content (including whitespaces) before headings. 66 | * @see https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-heading-indent 67 | * @see https://github.com/svengreb/styleguide-markdown/blob/main/rules/headings.md#no-content-before 68 | */ 69 | [noHeadingIndent, ["error"]], 70 | /** 71 | * Disallow using level 7+ "headings". 72 | * @see https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-heading-like-paragraph 73 | */ 74 | [noHeadingLikeParagraph, ["error"]], 75 | /** 76 | * Warn when ending a heading content with a punctuation character. 77 | * @see https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-heading-punctuation 78 | * @see https://github.com/svengreb/styleguide-markdown/blob/main/rules/headings.md#punctuation-after-content 79 | */ 80 | [noHeadingPunctuation, ["warn"]], 81 | /** 82 | * Disallow multiple toplevel headings. 83 | * @see https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-multiple-toplevel-headings 84 | */ 85 | [noMultipleToplevelHeadings, false], 86 | ], 87 | }; 88 | 89 | export default headings; 90 | -------------------------------------------------------------------------------- /packages/@svengreb/remark-preset-lint/rules/horizontal-rules.js: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright (c) 2016-present Sven Greb 3 | * This source code is licensed under the MIT license found in the license file. 4 | */ 5 | 6 | import ruleStyle from "remark-lint-rule-style"; 7 | 8 | /** 9 | * Official remark-lint core rules for horizontal rule document nodes. 10 | * @see https://github.com/remarkjs/remark-lint/blob/main/doc/rules.md#list-of-rules 11 | */ 12 | const horizontalRules = { 13 | plugins: [ 14 | /** 15 | * Enforce the character style for horizontal rule markers. 16 | * @see https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-rule-style 17 | * @see https://github.com/svengreb/styleguide-markdown/blob/main/rules/horizontal-rules.md#marker-character-style 18 | */ 19 | [ruleStyle, ["error", "---"]], 20 | ], 21 | }; 22 | 23 | export default horizontalRules; 24 | -------------------------------------------------------------------------------- /packages/@svengreb/remark-preset-lint/rules/links.js: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright (c) 2016-present Sven Greb 3 | * This source code is licensed under the MIT license found in the license file. 4 | */ 5 | 6 | import definitionCase from "remark-lint-definition-case"; 7 | import definitionSpacing from "remark-lint-definition-spacing"; 8 | import finalDefinition from "remark-lint-final-definition"; 9 | import noAutoLinkWithoutProtocol from "remark-lint-no-auto-link-without-protocol"; 10 | import noDuplicateDefinitions from "remark-lint-no-duplicate-definitions"; 11 | import noDuplicateDefinedURLs from "remark-lint-no-duplicate-defined-urls"; 12 | import noEmptyUrl from "remark-lint-no-empty-url"; 13 | import noLiteralUrls from "remark-lint-no-literal-urls"; 14 | import noReferenceLikeUrl from "remark-lint-no-reference-like-url"; 15 | import noShortcutReferenceImage from "remark-lint-no-shortcut-reference-image"; 16 | import noShortcutReferenceLink from "remark-lint-no-shortcut-reference-link"; 17 | import noUndefinedReferences from "remark-lint-no-undefined-references"; 18 | import noUnusedDefinitions from "remark-lint-no-unused-definitions"; 19 | import noUnneededFullReferenceImage from "remark-lint-no-unneeded-full-reference-image"; 20 | import noUnneededFullReferenceLink from "remark-lint-no-unneeded-full-reference-link"; 21 | 22 | /** 23 | * Official remark-lint core rules for link document nodes. 24 | * @see https://github.com/remarkjs/remark-lint/blob/main/doc/rules.md#list-of-rules 25 | */ 26 | const links = { 27 | plugins: [ 28 | /** 29 | * Enforce lower case letters for reference link IDs. 30 | * @see https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-definition-case 31 | * @see https://github.com/svengreb/styleguide-markdown/blob/main/rules/links.md#letter-case 32 | */ 33 | [definitionCase, ["error"]], 34 | /** 35 | * Enforce a single space after the colon of reference links. 36 | * @see https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-definition-spacing 37 | * @see https://github.com/svengreb/styleguide-markdown/blob/main/rules/links.md#spacing-after-colon 38 | */ 39 | [definitionSpacing, ["error"]], 40 | /** 41 | * Enforce reference links to be placed at the bottom of the document. 42 | * @see https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-final-definition 43 | * @see https://github.com/svengreb/styleguide-markdown/blob/main/rules/links.md#definition-placement 44 | */ 45 | [finalDefinition, ["error"]], 46 | /** 47 | * Disallow autolinks without a valid protocols. 48 | * @see https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-auto-link-without-protocol 49 | * @see https://github.com/svengreb/styleguide-markdown/blob/main/rules/links.md#autolink-protocol 50 | */ 51 | [noAutoLinkWithoutProtocol, ["warn"]], 52 | /** 53 | * Disallow duplicate reference link IDs. 54 | * @see https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-duplicate-definitions 55 | * @see https://github.com/svengreb/styleguide-markdown/blob/main/rules/links.md#unique-ids 56 | */ 57 | [noDuplicateDefinitions, ["error"]], 58 | /** 59 | * Warn when definitions define the same URL. 60 | * @see https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-duplicate-defined-urls 61 | * @see https://github.com/svengreb/styleguide-markdown/blob/main/rules/links.md#unique-ids 62 | */ 63 | [noDuplicateDefinedURLs, ["warn"]], 64 | /** 65 | * Disallow empty link and image URLs. 66 | * @see https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-empty-url 67 | * @see https://github.com/svengreb/styleguide-markdown/blob/main/rules/links.md#no-empty-url 68 | */ 69 | [noEmptyUrl, ["error"]], 70 | /** 71 | * Disallow literal URLs and enforce to always use angle-brackets ("<>") for autolinks. 72 | * @see https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-literal-urls 73 | */ 74 | [noLiteralUrls, false], 75 | /** 76 | * Disallow URLs that are also defined identifiers. 77 | * @see https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-reference-like-url 78 | * @see https://github.com/svengreb/styleguide-markdown/blob/main/rules/links.md#no-reference-like-url 79 | */ 80 | [noReferenceLikeUrl, ["error"]], 81 | /** 82 | * Warn when using shortcut reference images. 83 | * @see https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-shortcut-reference-image 84 | */ 85 | [noShortcutReferenceImage, false], 86 | /** 87 | * Warn when using shortcut reference links. 88 | * @see https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-shortcut-reference-link 89 | */ 90 | [noShortcutReferenceLink, false], 91 | /** 92 | * Disallow the usage of references that are not defined. 93 | * @see https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-undefined-references 94 | * @see https://github.com/svengreb/styleguide-markdown/blob/main/rules/links.md#no-undefined 95 | */ 96 | [noUndefinedReferences, ["error"]], 97 | /** 98 | * Warn when unused definitions are found. 99 | * @see https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-unused-definitions 100 | * @see https://github.com/svengreb/styleguide-markdown/blob/main/rules/links.md#no-unused 101 | */ 102 | [noUnusedDefinitions, ["warn"]], 103 | /** 104 | * Warn when full reference images are used that could be collapsed. 105 | * @since 0.4.0 106 | * @see https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-unneeded-full-reference-image 107 | * @see https://github.com/svengreb/styleguide-markdown/blob/main/rules/images.md#collapsed-reference-links 108 | */ 109 | [noUnneededFullReferenceImage, ["warn"]], 110 | /** 111 | * Warn when full reference links are used that could be collapsed. 112 | * @since 0.4.0 113 | * @see https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-unneeded-full-reference-link 114 | * @see https://github.com/svengreb/styleguide-markdown/blob/main/rules/links.md#collapsed-references 115 | */ 116 | [noUnneededFullReferenceLink, ["warn"]], 117 | ], 118 | }; 119 | export default links; 120 | -------------------------------------------------------------------------------- /packages/@svengreb/remark-preset-lint/rules/lists.js: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright (c) 2016-present Sven Greb 3 | * This source code is licensed under the MIT license found in the license file. 4 | */ 5 | 6 | import checkboxCharacterStyle from "remark-lint-checkbox-character-style"; 7 | import checkboxContentIndent from "remark-lint-checkbox-content-indent"; 8 | import listItemBulletIndent from "remark-lint-list-item-bullet-indent"; 9 | import listItemContentIndent from "remark-lint-list-item-content-indent"; 10 | import listItemIndent from "remark-lint-list-item-indent"; 11 | import listItemSpacing from "remark-lint-list-item-spacing"; 12 | import orderedListMarkerStyle from "remark-lint-ordered-list-marker-style"; 13 | import orderedListMarkerValue from "remark-lint-ordered-list-marker-value"; 14 | import unorderedListMarkerStyle from "remark-lint-unordered-list-marker-style"; 15 | 16 | /** 17 | * Official remark-lint core rules for list document nodes. 18 | * @see https://github.com/remarkjs/remark-lint/blob/main/doc/rules.md#list-of-rules 19 | */ 20 | const lists = { 21 | plugins: [ 22 | /** 23 | * Enforce a valid character style for ticked list item checkboxes. 24 | * @see https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-checkbox-character-style 25 | * @see https://github.com/svengreb/styleguide-markdown/blob/main/rules/lists.md#checkbox-character-style 26 | */ 27 | [ 28 | checkboxCharacterStyle, 29 | [ 30 | "error", 31 | { 32 | checked: "x", 33 | unchecked: " ", 34 | }, 35 | ], 36 | ], 37 | /** 38 | * Allow only one whitespace after list item checkboxes. 39 | * @see https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-checkbox-content-indent 40 | */ 41 | [checkboxContentIndent, ["error"]], 42 | /** 43 | * Disallow that list item bullets are indented. 44 | * @see https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-list-item-bullet-indent 45 | * @see https://github.com/svengreb/styleguide-markdown/blob/main/rules/lists.md#no-content-before 46 | */ 47 | [listItemBulletIndent, ["error"]], 48 | /** 49 | * Enforce two (2) whitespaces for continuous content indentation of nested items. 50 | * @see https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-list-item-content-indent 51 | * @see https://github.com/svengreb/styleguide-markdown/blob/main/rules/lists.md#continuous-indentation 52 | */ 53 | [listItemContentIndent, ["error"]], 54 | /** 55 | * Enforce two (2) whitespaces for continuous indentation of nested items. 56 | * @see https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-list-item-indent 57 | * @see https://github.com/svengreb/styleguide-markdown/blob/main/rules/lists.md#continuous-indentation 58 | */ 59 | [listItemIndent, ["error", "space"]], 60 | /** 61 | * Disallow blank lines between list items. 62 | * @see https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-list-item-spacing 63 | * @see https://github.com/svengreb/styleguide-markdown/blob/main/rules/lists.md#empty-lines 64 | */ 65 | [listItemSpacing, false], 66 | /** 67 | * Enforce the dot (".") marker character style for ordered list items. 68 | * @see https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-ordered-list-marker-style 69 | * @see https://github.com/svengreb/styleguide-markdown/blob/main/rules/lists.md#ordered-marker 70 | */ 71 | [orderedListMarkerStyle, ["error", "."]], 72 | /** 73 | * Enforce continuous numerating for markers of ordered list items. 74 | * @see https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-ordered-list-marker-value 75 | * @see https://github.com/svengreb/styleguide-markdown/blob/main/rules/lists.md#ordered-marker 76 | */ 77 | [orderedListMarkerValue, ["error", "ordered"]], 78 | /** 79 | * Enforce dash (`-`) marker character style for unordered list items. 80 | * @see https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-unordered-list-marker-style 81 | * @see https://github.com/svengreb/styleguide-markdown/blob/main/rules/lists.md#unordered-marker 82 | */ 83 | [unorderedListMarkerStyle, ["error", "-"]], 84 | ], 85 | }; 86 | 87 | export default lists; 88 | -------------------------------------------------------------------------------- /packages/@svengreb/remark-preset-lint/rules/naming-conventions.js: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright (c) 2016-present Sven Greb 3 | * This source code is licensed under the MIT license found in the license file. 4 | */ 5 | 6 | import fileExtension from "remark-lint-file-extension"; 7 | import noFileNameArticles from "remark-lint-no-file-name-articles"; 8 | import noFileNameConsecutiveDashes from "remark-lint-no-file-name-consecutive-dashes"; 9 | import noFileNameIrregularCharacters from "remark-lint-no-file-name-irregular-characters"; 10 | import noFileNameMixedCase from "remark-lint-no-file-name-mixed-case"; 11 | import noFileNameOuterDashes from "remark-lint-no-file-name-outer-dashes"; 12 | 13 | /** 14 | * Official remark-lint core rules for naming conventions. 15 | * @see https://github.com/remarkjs/remark-lint/blob/main/doc/rules.md#list-of-rules 16 | */ 17 | const namingConventions = { 18 | plugins: [ 19 | /** 20 | * Enforce a consistent file extension. 21 | * @see https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-file-extension 22 | * @see https://github.com/svengreb/styleguide-markdown/blob/main/rules/naming-conventions.md#file-extension 23 | */ 24 | [fileExtension, ["error", "md"]], 25 | /** 26 | * Warn when file name start with an article. 27 | * @see https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-file-name-articles 28 | */ 29 | [noFileNameArticles, false], 30 | /** 31 | * Warn when file names contain consecutive dashes. 32 | * @see https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-file-name-consecutive-dashes 33 | */ 34 | [noFileNameConsecutiveDashes, ["warn"]], 35 | /** 36 | * Warn when file names contain irregular characters other than alpha-numericals, dashes, and dots. 37 | * @see https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-file-name-irregular-characters 38 | */ 39 | [noFileNameIrregularCharacters, false], 40 | /** 41 | * Disallow file names with mixed letter case: both upper- and lower case characters. 42 | * @see https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-file-name-mixed-case 43 | * @see https://github.com/svengreb/styleguide-markdown/blob/main/rules/naming-conventions.md#file-naming 44 | */ 45 | [noFileNameMixedCase, ["error"]], 46 | /** 47 | * Warn when file names contain initial or final dashes. 48 | * @see https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-file-name-outer-dashes 49 | */ 50 | [noFileNameOuterDashes, ["warn"]], 51 | ], 52 | }; 53 | 54 | export default namingConventions; 55 | -------------------------------------------------------------------------------- /packages/@svengreb/remark-preset-lint/rules/paragraphs.js: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright (c) 2016-present Sven Greb 3 | * This source code is licensed under the MIT license found in the license file. 4 | */ 5 | 6 | import noParagraphContentIndent from "remark-lint-no-paragraph-content-indent"; 7 | 8 | /** 9 | * Official remark-lint core rules for paragraph document nodes. 10 | * @see https://github.com/remarkjs/remark-lint/blob/main/doc/rules.md#list-of-rules 11 | */ 12 | const paragraphs = { 13 | plugins: [ 14 | /** 15 | * Disallow the content of paragraphs to be indented. 16 | * @see https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-paragraph-content-indent 17 | * @see https://github.com/svengreb/styleguide-markdown/blob/main/rules/paragraphs.md#no-indentation 18 | */ 19 | [noParagraphContentIndent, ["error"]], 20 | ], 21 | }; 22 | 23 | export default paragraphs; 24 | -------------------------------------------------------------------------------- /packages/@svengreb/remark-preset-lint/rules/raw-html.js: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright (c) 2016-present Sven Greb 3 | * This source code is licensed under the MIT license found in the license file. 4 | */ 5 | 6 | import noHtml from "remark-lint-no-html"; 7 | 8 | /** 9 | * Official remark-lint core rules for raw HTML document nodes. 10 | * @see https://github.com/remarkjs/remark-lint/blob/main/doc/rules.md#list-of-rules 11 | */ 12 | const rawHTML = { 13 | plugins: [ 14 | /** 15 | * Disallow using raw HTML nodes. 16 | * @see https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-html 17 | */ 18 | [noHtml, false], 19 | ], 20 | }; 21 | 22 | export default rawHTML; 23 | -------------------------------------------------------------------------------- /packages/@svengreb/remark-preset-lint/rules/strings.js: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright (c) 2016-present Sven Greb 3 | * This source code is licensed under the MIT license found in the license file. 4 | */ 5 | 6 | import linkTitleStyle from "remark-lint-link-title-style"; 7 | 8 | /** 9 | * Official remark-lint core rules for string document nodes. 10 | * @see https://github.com/remarkjs/remark-lint/blob/main/doc/rules.md#list-of-rules 11 | */ 12 | const strings = { 13 | plugins: [ 14 | /** 15 | * Enforce double quotes for link titles. 16 | * 17 | * @see https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-link-title-style 18 | * @see https://github.com/svengreb/styleguide-markdown/blob/main/rules/strings.md#quotes 19 | */ 20 | [linkTitleStyle, ["error", '"']], 21 | ], 22 | }; 23 | 24 | export default strings; 25 | -------------------------------------------------------------------------------- /packages/@svengreb/remark-preset-lint/rules/support.js: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright (c) 2016-present Sven Greb 3 | * This source code is licensed under the MIT license found in the license file. 4 | */ 5 | 6 | import footnotes from "remark-footnotes"; 7 | import frontmatter from "remark-frontmatter"; 8 | import gfm from "remark-gfm"; 9 | import strikethroughMarker from "remark-lint-strikethrough-marker"; 10 | 11 | /** 12 | * Support for plugins of specification addons and variants. 13 | */ 14 | const support = { 15 | plugins: [ 16 | /** 17 | * Adds support for Pandoc footnotes 18 | * @since 0.4.0 19 | * @see https://github.com/remarkjs/remark-footnotes 20 | * @see https://pandoc.org 21 | */ 22 | [ 23 | footnotes, 24 | { 25 | /* Enable support for inline notes like `^[note]`. */ 26 | inlineNotes: true, 27 | }, 28 | ], 29 | /** 30 | * Adds support for YAML and TOML frontmatter. 31 | * @since 0.3.0 32 | * @see http://yaml.org 33 | * @see https://github.com/toml-lang/toml 34 | */ 35 | [frontmatter, ["toml", "yaml"]], 36 | /** 37 | * Adds support for "GitHub Flavored Markdown". 38 | * @since 0.4.0 39 | * @see https://github.com/remarkjs/remark-gfm 40 | * @see https://github.github.com/gfm 41 | */ 42 | [ 43 | gfm, 44 | { 45 | /* Disallow strikethrough with a single tilde. */ 46 | singleTilde: false, 47 | /* Ensure a space between table cell delimiters (`|`) and and content. */ 48 | tableCellPadding: true, 49 | 50 | /* Align table delimiters (`|`) between cells so that they all align nicely and form a grid. */ 51 | tablePipeAlign: true, 52 | }, 53 | ], 54 | /** 55 | * Warn when the number of strikethrough markers is inconsistent and does not use two strikethrough markers. 56 | * @since 0.5.0 57 | * @see https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-strikethrough-marker 58 | * @see https://github.com/svengreb/styleguide-markdown/blob/main/rules/emphasis.md#strikethrough 59 | */ 60 | [strikethroughMarker, "~~"], 61 | ], 62 | }; 63 | 64 | export default support; 65 | -------------------------------------------------------------------------------- /packages/@svengreb/remark-preset-lint/rules/tables.js: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright (c) 2016-present Sven Greb 3 | * This source code is licensed under the MIT license found in the license file. 4 | */ 5 | 6 | import noTableIndentation from "remark-lint-no-table-indentation"; 7 | import tableCellPadding from "remark-lint-table-cell-padding"; 8 | import tablePipeAlignment from "remark-lint-table-pipe-alignment"; 9 | import tablePipes from "remark-lint-table-pipes"; 10 | 11 | /** 12 | * Official remark-lint core rules for table document nodes. 13 | * @see https://github.com/remarkjs/remark-lint/blob/main/doc/rules.md#list-of-rules 14 | */ 15 | const tables = { 16 | plugins: [ 17 | /** 18 | * Disallow tables to be indented. 19 | * @see https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-table-indentation 20 | * @see https://github.com/svengreb/styleguide-markdown/blob/main/rules/tables.md#no-indentation 21 | */ 22 | [noTableIndentation, ["error"]], 23 | /** 24 | * Enforces table cells to be padded correctly. 25 | * @see https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-table-cell-padding 26 | * @see https://github.com/svengreb/styleguide-markdown/blob/main/rules/tables.md#header-delimiter-row-spacing 27 | */ 28 | [tableCellPadding, ["error", "padded"]], 29 | /** 30 | * Enforces table cell header delimiter marker to be correctly aligned. 31 | * @see https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-table-pipe-alignment 32 | * @see https://github.com/svengreb/styleguide-markdown/blob/main/rules/tables.md#header-delimiter-row-spacing 33 | * @see https://github.com/svengreb/styleguide-markdown/blob/main/rules/tables.md#minimum-column-width 34 | */ 35 | [tablePipeAlignment, ["error"]], 36 | /** 37 | * Enforces table cell header delimiter marker to be correctly aligned. 38 | * @see https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-table-pipes 39 | * @see https://github.com/svengreb/styleguide-markdown/blob/main/rules/tables.md#alignment 40 | */ 41 | [tablePipes, ["error"]], 42 | ], 43 | }; 44 | 45 | export default tables; 46 | -------------------------------------------------------------------------------- /packages/@svengreb/remark-preset-lint/rules/whitespace.js: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright (c) 2016-present Sven Greb 3 | * This source code is licensed under the MIT license found in the license file. 4 | */ 5 | 6 | import finalNewline from "remark-lint-final-newline"; 7 | import hardBreakSpaces from "remark-lint-hard-break-spaces"; 8 | import linebreakStyle from "remark-lint-linebreak-style"; 9 | import maximumLineLength from "remark-lint-maximum-line-length"; 10 | import noConsecutiveBlankLines from "remark-lint-no-consecutive-blank-lines"; 11 | import noMissingBlankLines from "remark-lint-no-missing-blank-lines"; 12 | import noTabs from "remark-lint-no-tabs"; 13 | 14 | /** 15 | * Official remark-lint core rules for whitespaces. 16 | * @see https://github.com/remarkjs/remark-lint/blob/main/doc/rules.md#list-of-rules 17 | */ 18 | const whitespace = { 19 | plugins: [ 20 | /** 21 | * Enforce a newline at the end of a file. Empty files are allowed. 22 | * @see https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-final-newline 23 | * @see https://github.com/svengreb/styleguide-markdown/blob/main/rules/whitespace.md#newline 24 | */ 25 | [finalNewline, ["error"]], 26 | /** 27 | * Enforce a consistent number of trailing whitespaces for line breaks. 28 | * @see https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-hard-break-spaces 29 | * @see https://github.com/svengreb/styleguide-markdown/blob/main/rules/whitespace.md#trailing 30 | */ 31 | [hardBreakSpaces, ["error"]], 32 | /** 33 | * Enforce unix-style linebreaks. 34 | * @see https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-linebreak-style 35 | * @see https://github.com/svengreb/styleguide-markdown/blob/main/rules/whitespace.md#newline 36 | */ 37 | [linebreakStyle, ["error", "unix"]], 38 | /** 39 | * Enforce a maximum line length. 40 | * @see https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-maximum-line-length 41 | * @see https://github.com/svengreb/styleguide-markdown/blob/main/rules/whitespace.md#maximum-line-length 42 | */ 43 | [maximumLineLength, false], 44 | /** 45 | * Disallow more than one (1) blank line after and before each block. 46 | * @see https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-consecutive-blank-lines 47 | * @see https://github.com/svengreb/styleguide-markdown/blob/main/rules/whitespace.md#after-blocks 48 | */ 49 | [noConsecutiveBlankLines, ["warn"]], 50 | /** 51 | * Warn when missing blank line before a block node. 52 | * @see https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-missing-blank-lines 53 | * @see https://github.com/svengreb/styleguide-markdown/blob/main/rules/whitespace.md#before-blocks 54 | */ 55 | [noMissingBlankLines, ["warn", { exceptTightLists: true }]], 56 | /** 57 | * Disallow tabs and enforce to use whitespaces. 58 | * @see https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-tabs 59 | * @see https://github.com/svengreb/styleguide-markdown/blob/main/rules/whitespace.md#indentation-character 60 | */ 61 | [noTabs, ["error"]], 62 | ], 63 | }; 64 | 65 | export default whitespace; 66 | -------------------------------------------------------------------------------- /prettier.config.js: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright (c) 2016-present Sven Greb 3 | * This source code is licensed under the MIT license found in the license file. 4 | */ 5 | 6 | /** 7 | * Configurations for Prettier. 8 | * @see https://prettier.io/docs/en/configuration.html 9 | * @see https://prettier.io/docs/en/options.html 10 | * @see https://prettier.io/docs/en/options.html#parser 11 | * @see https://prettier.io/docs/en/plugins.html 12 | * @see https://github.com/un-ts/prettier/tree/master/packages/sh 13 | */ 14 | module.exports = { 15 | printWidth: 160, 16 | overrides: [ 17 | { 18 | files: [".husky/*"], 19 | options: { 20 | parser: "sh", 21 | }, 22 | }, 23 | ], 24 | }; 25 | -------------------------------------------------------------------------------- /readme.md: -------------------------------------------------------------------------------- 1 |

2 | 3 | 4 | 5 | 6 | 7 |

8 | 9 |

10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 |

20 | 21 |

22 | 23 | 24 | 25 |

26 | 27 |

28 | 29 | 30 | 31 |

32 | 33 |

34 | 35 | 36 | 37 | 38 | 39 | 40 |

41 | 42 |

An opinionated, yet universally applicable Markdown code style guide.

43 | 44 | Every major open source project has its own style guide, a set of standards and conventions for the writing and design of code, documentations and assets. It is much easier to understand a large codebase when all the code in it is in a consistent style. 45 | 46 | A style guide establishes and enforces style to improve the intelligibility and communication within the project community. It ensures consistency and enforces best practice in usage and language composition. 47 | 48 | ### Getting Started 49 | 50 | Learn about the [comprehensive base rule set][9] with support for [GitHub Flavored Markdown][10] which is based on the [CommonMark][1] specification. It includes rules for all document elements like e.g. [code blocks][2], [headings][4] or [lists][5], defines [naming conventions][6] and best practices for [Raw HTML][7], [emphasizing][3] and [strings][8]. 51 | 52 | ### Remark Configurations 53 | 54 | To follow the rules in a project and ensure that your code matches this style guide use the official extensible code linter rule preset [@svengreb/remark-preset-lint][12] for [remark-lint][11], a plugin for [remark][13]. 55 | 56 |

57 | 58 | 59 | 60 | 61 | 62 |

63 | 64 |

65 | Copyright © 2016-present Sven Greb 66 |

67 | 68 |

69 | 70 | 71 | 72 | 73 | 74 | 75 |

76 | 77 | [1]: https://commonmark.org 78 | [2]: https://github.com/svengreb/styleguide-markdown/blob/main/rules/code.md 79 | [3]: https://github.com/svengreb/styleguide-markdown/blob/main/rules/emphasis.md 80 | [4]: https://github.com/svengreb/styleguide-markdown/blob/main/rules/headings.md 81 | [5]: https://github.com/svengreb/styleguide-markdown/blob/main/rules/lists.md 82 | [6]: https://github.com/svengreb/styleguide-markdown/blob/main/rules/naming-conventions.md 83 | [7]: https://github.com/svengreb/styleguide-markdown/blob/main/rules/raw-html.md 84 | [8]: https://github.com/svengreb/styleguide-markdown/blob/main/rules/strings.md 85 | [9]: https://github.com/svengreb/styleguide-markdown/blob/main/rules/index.md 86 | [10]: https://github.github.com/gfm 87 | [11]: https://github.com/remarkjs/remark-lint 88 | [12]: https://github.com/svengreb/styleguide-markdown/tree/main/packages/@svengreb/remark-preset-lint 89 | [13]: https://remark.js.org 90 | -------------------------------------------------------------------------------- /rules/accessibility-a11y.md: -------------------------------------------------------------------------------- 1 | This chapter provides rules to improve the accessibility as documented by the [A11Y][1] project. 2 | 3 | ## Alternative Text 4 | 5 | Add an alternative text for images. 6 | 7 | ###### Examples 8 | 9 | ⇣ **Incorrect** code for this rule: 10 | 11 | 12 | 13 | ```markdown 14 | ![][snowflakes] 15 | 16 | [snowflakes]: https://raw.githubusercontent.com/nordtheme/assets/main/static/images/artworks/arctic/nature/dark/snowfall.svg?sanitize=true 17 | ``` 18 | 19 | 20 | 21 | ⇡ **Correct** code for this rule: 22 | 23 | ```markdown 24 | ![falling snowflakes][snowflakes] 25 | 26 | [snowflakes]: https://raw.githubusercontent.com/nordtheme/assets/main/static/images/artworks/arctic/nature/dark/snowfall.svg?sanitize=true 27 | ``` 28 | 29 | [1]: https://www.a11yproject.com 30 | -------------------------------------------------------------------------------- /rules/blockquotes.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | ## Indentation 4 | 5 | Always separate the marker `>` from the actual content using a single whitespace. 6 | 7 | > remark-lint: [blockquote-indentation][1] 8 | 9 | ###### Examples 10 | 11 | ⇣ **Incorrect** code for this rule: 12 | 13 | 14 | 15 | ```markdown 16 | >Winter 17 | ``` 18 | 19 | ```markdown 20 | > Winter 21 | ``` 22 | 23 | 24 | 25 | ⇡ **Correct** code for this rule: 26 | 27 | ```markdown 28 | > Winter 29 | ``` 30 | 31 | ## Multi Line 32 | 33 | Use a `greater than` sign for every line, including wrapped. 34 | 35 | > remark-lint: [no-blockquote-without-marker][2] 36 | 37 | ###### Examples 38 | 39 | ⇣ **Incorrect** code for this rule: 40 | 41 | 42 | 43 | ```markdown 44 | > Winter 45 | Snow 46 | ``` 47 | 48 | ```markdown 49 | > Many snowflakes are falling down. The winter has sparkling and frozen elements! It is home 50 | for many beautiful animals like snowy owls, 51 | arctic foxes, and grizzly bears. 52 | ``` 53 | 54 | 55 | 56 | ⇡ **Correct** code for this rule: 57 | 58 | ```markdown 59 | > Winter 60 | > Snow 61 | ``` 62 | 63 | ```markdown 64 | > Many snowflakes are falling down. The winter has sparkling and frozen elements! It is home 65 | > for many beautiful animals like snowy owls, 66 | > arctic foxes, and grizzly bears. 67 | ``` 68 | 69 | [1]: https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-blockquote-indentation 70 | [2]: https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-blockquote-without-marker 71 | -------------------------------------------------------------------------------- /rules/code.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | ## Blocks 4 | 5 | Avoid indentation based code blocks, use [fenced code blocks][4] for multi line code. This prevents malformed rendered output due to wrong indentation errors, increases the readability and allows the usage of [language syntax highlighting][5]. 6 | 7 | > remark-lint: [code-block-style][14] 8 | 9 | ###### Examples 10 | 11 | ⇣ **Incorrect** code for this rule: 12 | 13 | 14 | 15 | ```markdown 16 | import React, { PureComponent } from "react"; 17 | 18 | class Frost extends PureComponent { 19 | // ... 20 | } 21 | 22 | export default Frost; 23 | ``` 24 | 25 | 26 | 27 | ⇡ **Correct** code for this rule: 28 | 29 | ````markdown 30 | ```js 31 | import React, { PureComponent } from "react"; 32 | 33 | class Frost extends PureComponent { 34 | // ... 35 | } 36 | 37 | export default Frost; 38 | ``` 39 | ```` 40 | 41 | ## Syntax Highlighting 42 | 43 | Explicitly declare the language for blocks containing code snippets, so that neither the syntax highlighter nor the next editor must guess. 44 | 45 | > remark-lint: [fenced-code-flag][15] 46 | 47 | ###### Examples 48 | 49 | ⇣ **Incorrect** code for this rule: 50 | 51 | 52 | 53 | ````markdown 54 | ``` 55 | import React, { PureComponent } from "react"; 56 | 57 | class Frost extends PureComponent { 58 | // ... 59 | } 60 | 61 | export default Frost; 62 | ``` 63 | ```` 64 | 65 | 66 | 67 | ⇡ **Correct** code for this rule: 68 | 69 | ````markdown 70 | ```js 71 | import React, { PureComponent } from "react"; 72 | 73 | class Frost extends PureComponent { 74 | // ... 75 | } 76 | 77 | export default Frost; 78 | ``` 79 | ```` 80 | 81 | ## Escape Newlines In Terminal Commands 82 | 83 | Many command snippets are intended to be copied and pasted directly into e.g. a terminal. To protect the user to unintentional execute the copied code due to a newline (interpreted by the terminal as Enter) use a single backslash at the end of the line. 84 | 85 | ###### Examples 86 | 87 | ⇣ **Incorrect** code for this rule: 88 | 89 | 90 | 91 | ````markdown 92 | ```sh 93 | npx run docs:generate -- --template=winter --description="Sparkling and frozen" --elements="snow,frost,ice" --snowflakes=20 94 | ``` 95 | ```` 96 | 97 | 98 | 99 | ⇡ **Correct** code for this rule: 100 | 101 | ````markdown 102 | ```sh 103 | npx run docs:generate -- --template=winter --description="Sparkling and frozen" \ 104 | --elements="snow,frost,ice" --snowflakes=20 105 | ``` 106 | ```` 107 | 108 | ## No Shell Code Dollar Sign 109 | 110 | Avoid to use dollar sign (`$`) in shell code. It improves the readability and prevents error when users copy and paste the code. To clarify the output of a command use e.g. a comment on the next line or optionally append it to the command on the same line, separated by a whitespace. 111 | 112 | > remark-lint: [no-shell-dollars][17] 113 | 114 | ###### Examples 115 | 116 | ⇣ **Incorrect** code for this rule: 117 | 118 | 119 | 120 | ````markdown 121 | ```sh 122 | $ echo "The winter is sparkling and frozen!" 123 | ``` 124 | ```` 125 | 126 | 127 | 128 | ⇡ **Correct** code for this rule: 129 | 130 | ````markdown 131 | ```sh 132 | echo "The winter is sparkling and frozen!" 133 | ``` 134 | ```` 135 | 136 | ````markdown 137 | ```sh 138 | winter="The winter is sparkling and frozen!" 139 | echo $winter # The winter is sparkling and frozen! 140 | ``` 141 | ```` 142 | 143 | ## Within Lists 144 | 145 | When using code blocks within lists make sure to use the correct indention to not break the list. 146 | 147 | ###### Examples 148 | 149 | ⇣ **Incorrect** code for this rule: 150 | 151 | 152 | 153 | ````markdown 154 | * Winter 155 | ```jsx 156 | const Snow = ; 157 | ``` 158 | * Frost 159 | ```` 160 | 161 | 162 | 163 | ⇡ **Correct** code for this rule: 164 | 165 | ````markdown 166 | - Winter 167 | ```jsx 168 | const Snow = ; 169 | ``` 170 | - Frost 171 | ```` 172 | 173 | ## Inline 174 | 175 | Use one (1) backtick character `` ` `` to create a `inline code` span which will render all wrapped content literally. 176 | 177 | ###### Examples 178 | 179 | ⇣ **Incorrect** code for this rule: 180 | 181 | 182 | 183 | ````markdown 184 | The winter has ```sparkling``` and frozen ```elements```! 185 | ```` 186 | 187 | 188 | 189 | ⇡ **Correct** code for this rule: 190 | 191 | ```markdown 192 | The winter has `sparkling` and frozen `elements`! 193 | ``` 194 | 195 | To learn what content should be wrapped please read the [use cases](#use-cases) chapter. 196 | 197 | ## Marker Character Style 198 | 199 | Use backtick characters `` ` `` for both blocks and inline code. 200 | 201 | > remark-lint: [fenced-code-marker][16] 202 | 203 | ###### Examples 204 | 205 | ⇣ **Incorrect** code for this rule: 206 | 207 | 208 | 209 | ````markdown 210 | ~~~js 211 | import React, { PureComponent } from "react"; 212 | class Snow extends PureComponent { 213 | // ... 214 | } 215 | export default Snow; 216 | ~~~ 217 | ```` 218 | 219 | 220 | 221 | ⇡ **Correct** code for this rule: 222 | 223 | ````markdown 224 | ```js 225 | import React, { PureComponent } from "react"; 226 | class Snow extends PureComponent { 227 | // ... 228 | } 229 | export default Snow; 230 | ``` 231 | ```` 232 | 233 | ## Use Cases 234 | 235 | [Code Blocks](#blocks) should be used for code snippets longer than a single line or terminal command quotations that contain sample output when the being executed. 236 | 237 | [Inline code spans](#inline) on the other hand should be used to highlight e.g. 238 | 239 | - **executables** - `go`, `npm`, `gcc` 240 | - **paths** - `pkg/internal/transport/http/http.go`, `/etc/hosts` 241 | - **version numbers** - `0.2.0`, `1.8.6-beta.2` 242 | - **code e.g. reserved keywords, builtins and operators** - `this`, `true`/`false`, `String`, `=>` 243 | 244 | Don't use it for 245 | 246 | - **project or proper names** - e.g [React][13], [Go][8], [Rust][18] [Node.js][10] or [GCC][3]. 247 | - **libraries** - e.g. [libgit2][9], [libc][2] (Rust Bindings), [glibc][7] or [glib2][6]. 248 | - **packages and modules** - e.g. [react-dom][11], [snowsaw][12] or [archlinux-keyring][1]. 249 | 250 | [1]: https://archlinux.org/packages/core/any/archlinux-keyring 251 | [2]: https://crates.io/crates/libc 252 | [3]: https://gcc.gnu.org 253 | [4]: https://github.github.com/gfm/#fenced-code-blocks 254 | [5]: https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/creating-and-highlighting-code-blocks#syntax-highlighting 255 | [6]: https://wiki.gnome.org/Projects/GLib 256 | [7]: https://www.gnu.org/software/libc 257 | [8]: https://go.dev 258 | [9]: https://libgit2.org 259 | [10]: https://nodejs.org 260 | [11]: https://www.npmjs.com/package/react-dom 261 | [12]: https://github.com/svengreb/snowsaw 262 | [13]: https://react.dev 263 | [14]: https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-code-block-style 264 | [15]: https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-fenced-code-flag 265 | [16]: https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-fenced-code-marker 266 | [17]: https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-shell-dollars 267 | [18]: https://www.rust-lang.org 268 | -------------------------------------------------------------------------------- /rules/comments.md: -------------------------------------------------------------------------------- 1 | ## HTML 2 | 3 | Prefer [HTML comment syntax][1] to add hidden, non-rendered comments to the code. 4 | 5 | ###### Examples 6 | 7 | ⇡ **Correct** code for this rule: 8 | 9 | ```markdown 10 | 11 | ``` 12 | 13 | [1]: https://html.spec.whatwg.org/multipage/syntax.html#sec-comments 14 | -------------------------------------------------------------------------------- /rules/emphasis.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | ## Italic 4 | 5 | Use one (1) underscore `_` marker to generate spans for italic formatted text. 6 | 7 | > remark-lint: [emphasis-marker][2] 8 | 9 | ###### Examples 10 | 11 | ⇣ **Incorrect** code for this rule: 12 | 13 | 14 | 15 | ```markdown 16 | *Winter* 17 | ``` 18 | 19 | ```markdown 20 | ___Snow___ 21 | ``` 22 | 23 | 24 | 25 | ⇡ **Correct** code for this rule: 26 | 27 | ```markdown 28 | _Winter_ 29 | _Snow_ 30 | ``` 31 | 32 | ## Bold 33 | 34 | Use two (2) asterisk `*` marker to generate spans for bold formatted text. 35 | 36 | > remark-lint: [emphasis-marker][2] and [strong-marker][5] 37 | 38 | ###### Examples 39 | 40 | ⇣ **Incorrect** code for this rule: 41 | 42 | 43 | 44 | ```markdown 45 | *Winter* 46 | ``` 47 | 48 | ```markdown 49 | ***Snow*** 50 | ``` 51 | 52 | 53 | 54 | ⇡ **Correct** code for this rule: 55 | 56 | ```markdown 57 | **Winter** 58 | **Snow** 59 | ``` 60 | 61 | ## Strikethrough 62 | 63 | > Note that [strikethrough][1] is an **extension of GFM** and not implemented by all parsers! 64 | 65 | Use two (2) tilde `~` marker to generate spans for strikethrough text. 66 | 67 | > remark-lint: [strikethrough-marker][6], [emphasis-marker][2] 68 | 69 | ###### Examples 70 | 71 | ⇣ **Incorrect** code for this rule: 72 | 73 | 74 | 75 | ```markdown 76 | ~Winter~ 77 | ``` 78 | 79 | ```markdown 80 | ~~~Snow~~~ 81 | ``` 82 | 83 | 84 | 85 | ⇡ **Correct** code for this rule: 86 | 87 | ```markdown 88 | ~~Winter~~ 89 | ~~Snow~~ 90 | ``` 91 | 92 | ## No Header Replacement 93 | 94 | Don't use emphasis elements (bold or italics) to introduce a multi line named section. Use headers instead which is exactly the semantic meaning of headers. As a consequence, many implementations add useful behaviors to headers and not to emphasis elements, such as automatic ID generation (anchor) to make it easier to refer to the header later on. Use a level 6 header if the meaning of the header section should not stand out great. 95 | 96 | > remark-lint: [no-emphasis-as-heading][3] 97 | 98 | ###### Examples 99 | 100 | ⇣ **Incorrect** code for this rule: 101 | 102 | 103 | 104 | ```markdown 105 | **Winter** 106 | 107 | The winter has sparkling and frozen elements! 108 | 109 | __Snow__ 110 | 111 | Snow is falling down! 112 | ``` 113 | 114 | 115 | 116 | ⇡ **Correct** code for this rule: 117 | 118 | ```markdown 119 | ## Winter 120 | 121 | The winter has sparkling and frozen elements! 122 | 123 | ## Snow 124 | 125 | Snow is falling down! 126 | ``` 127 | 128 | ```markdown 129 | ###### Winter 130 | 131 | The winter has sparkling and frozen elements! 132 | 133 | ###### Snow 134 | 135 | Snow is falling down! 136 | ``` 137 | 138 | ## No Inner Spacing 139 | 140 | Don't use inner spaces for any markers. 141 | 142 | > remark-lint: [no-inline-padding][4] 143 | 144 | ###### Examples 145 | 146 | ⇣ **Incorrect** code for this rule: 147 | 148 | 149 | 150 | ```markdown 151 | ** Winter ** 152 | __ Snow __ 153 | ``` 154 | 155 | ```markdown 156 | ** Winter ** 157 | __ Snow __ 158 | ``` 159 | 160 | 161 | 162 | ⇡ **Correct** code for this rule: 163 | 164 | ```markdown 165 | **Winter** 166 | **Snow** 167 | ``` 168 | 169 | [1]: https://github.github.com/gfm/#strikethrough-extension- 170 | [2]: https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-emphasis-marker 171 | [3]: https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-emphasis-as-heading 172 | [4]: https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-inline-padding 173 | [5]: https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-strong-marker 174 | [6]: https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-strikethrough-marker 175 | -------------------------------------------------------------------------------- /rules/headings.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | ## ATX Style 4 | 5 | Always use [atx-style][1] headings (not closed) instead of [Setext][9]. The level can be easily seen and the number of characters must not match in both lines. ATX also works for all levels, while Setex only goes up to level 2. 6 | 7 | > remark-lint: [heading-style][2] 8 | 9 | ###### Examples 10 | 11 | ⇣ **Incorrect** code for this rule: 12 | 13 | 14 | 15 | ```markdown 16 | Winter 17 | ====== 18 | 19 | Frost 20 | ----- 21 | ``` 22 | 23 | No closed ATX styled headings: 24 | 25 | ```markdown 26 | # Winter # 27 | 28 | ## Frost ## 29 | 30 | ### Snow ### 31 | ``` 32 | 33 | 34 | 35 | ⇡ **Correct** code for this rule: 36 | 37 | ```markdown 38 | # Winter 39 | 40 | ## Frost 41 | 42 | ### Snow 43 | ``` 44 | 45 | ## Empty Lines Before And After 46 | 47 | Always surround headers by a single empty line except at the beginning of the file. 48 | 49 | ###### Examples 50 | 51 | ⇣ **Incorrect** code for this rule: 52 | 53 | 54 | 55 | ```markdown 56 | ... snowflakes are falling. 57 | # Winter 58 | Sparkling and frozen... 59 | ``` 60 | 61 | ```markdown 62 | ... snowflakes are falling. 63 | 64 | 65 | # Winter 66 | 67 | 68 | Sparkling and frozen... 69 | ``` 70 | 71 | 72 | 73 | ⇡ **Correct** code for this rule: 74 | 75 | ```markdown 76 | ... snowflakes are falling. 77 | 78 | # Winter 79 | 80 | Sparkling and frozen... 81 | ``` 82 | 83 | ## Content Spacing 84 | 85 | Always separate the marker character `#` from the actual header content using a single whitespace. 86 | 87 | > remark-lint: [no-heading-content-indent][6] 88 | 89 | ###### Examples 90 | 91 | ⇣ **Incorrect** code for this rule: 92 | 93 | 94 | 95 | ```markdown 96 | #Winter 97 | ``` 98 | 99 | ```markdown 100 | # Winter 101 | ``` 102 | 103 | 104 | 105 | ⇡ **Correct** code for this rule: 106 | 107 | ```markdown 108 | # Winter 109 | ``` 110 | 111 | ## No Content Before 112 | 113 | Make sure that there are no other characters (including whitespaces) in front of headings. 114 | 115 | > remark-lint: [no-heading-indent][7] 116 | 117 | ###### Examples 118 | 119 | Note: The `·` character represents a whitespace character. 120 | 121 | ⇣ **Incorrect** code for this rule: 122 | 123 | 124 | 125 | ```markdown 126 | .# Winter 127 | ``` 128 | 129 | ```markdown 130 | ·# Winter 131 | ``` 132 | 133 | 134 | 135 | ⇡ **Correct** code for this rule: 136 | 137 | ```markdown 138 | # Winter 139 | ``` 140 | 141 | ## No Duplicate 142 | 143 | Avoid using two or more headers with the same content in the same markdown file. many Markdown renderer generate IDs for headers based on the header content. 144 | 145 | > remark-lint: [no-duplicate-headings][5] and [no-duplicate-headings-in-section][4] 146 | 147 | ###### Examples 148 | 149 | ⇣ **Incorrect** code for this rule: 150 | 151 | 152 | 153 | ```markdown 154 | # Winter 155 | 156 | ## Snow 157 | 158 | # Arctic 159 | 160 | ## Snow 161 | ``` 162 | 163 | 164 | 165 | ⇡ **Correct** code for this rule: 166 | 167 | ```markdown 168 | # Winter 169 | 170 | ## Winter Snow 171 | 172 | # Arctic 173 | 174 | ## Arctic Snow 175 | ``` 176 | 177 | ## Letter Case 178 | 179 | Use an upper case letter as the first letter of a header, unless it is a word that always starts with lowercase letters, e.g. proper names or code snippets. The other letters have the same case they would have in the middle of a sentence. 180 | 181 | As an exception, [title case][10] can be optionally used for the top-level header. Use this exception sparingly, in cases where typographical perfection is important. Using title case all the time would require too much effort to decide if edge-case words should be upper case or not. 182 | 183 | ###### Examples 184 | 185 | ⇣ **Incorrect** code for this rule: 186 | 187 | 188 | 189 | ```markdown 190 | # winter is sparkling and frozen 191 | ``` 192 | 193 | Proper names or code snippets: 194 | 195 | ```markdown 196 | # react 197 | 198 | # `String` 199 | 200 | # Init 201 | ``` 202 | 203 | 204 | 205 | ⇡ **Correct** code for this rule: 206 | 207 | ```markdown 208 | # Winter is sparkling and frozen 209 | ``` 210 | 211 | Proper names or code snippets: 212 | 213 | ```markdown 214 | # React 215 | 216 | # `string` 217 | 218 | # init main 219 | ``` 220 | 221 | ## Length 222 | 223 | Prefer using short header with a maximum length of 80 character (without markers). Instead of using a huge sentence, make the header a summary and write the huge sentence as the first paragraph beneath the header. This makes it is easier to refer to the header later, specially if automatic IDs or a TOC are created. 224 | 225 | > remark-lint: [maximum-heading-length][3] 226 | 227 | ###### Examples 228 | 229 | ⇣ **Incorrect** code for this rule: 230 | 231 | 232 | 233 | ```markdown 234 | # The winter is sparkling and frozen and soft snowflakes are falling down on the world! 235 | ``` 236 | 237 | 238 | 239 | ⇡ **Correct** code for this rule: 240 | 241 | ```markdown 242 | # Winter 243 | 244 | The winter is sparkling and frozen and soft snowflakes are falling down on the world! 245 | ``` 246 | 247 | ## Punctuation After Content 248 | 249 | Don't use any punctuation at the end of a header e.g. a trailing (semi)colon `;:`, period `.`, closing marker `#` or any "sentence amplifier" (`!?`). Every header is an introduction to what is about to come next, which is exactly the function of a colon. Also the header is not a sentence, or at least only a short sentence, so there is not need to add a sentence separator to it. 250 | 251 | > remark-lint: [no-heading-punctuation][8] 252 | 253 | ###### Examples 254 | 255 | ⇣ **Incorrect** code for this rule: 256 | 257 | 258 | 259 | ```markdown 260 | # Winter: Sparkling 261 | ``` 262 | 263 | ```markdown 264 | # Winter. Frozen. 265 | ``` 266 | 267 | ```markdown 268 | # Winter # 269 | ``` 270 | 271 | 272 | 273 | ⇡ **Correct** code for this rule: 274 | 275 | ```markdown 276 | # Winter 277 | 278 | Sparkling and frozen. 279 | ``` 280 | 281 | [1]: http://www.aaronsw.com/2002/atx/intro 282 | [2]: https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-heading-style 283 | [3]: https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-maximum-heading-length 284 | [4]: https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-duplicate-headings-in-section 285 | [5]: https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-duplicate-headings 286 | [6]: https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-heading-content-indent 287 | [7]: https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-heading-indent 288 | [8]: https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-heading-punctuation 289 | [9]: https://docutils.sourceforge.io/mirror/setext.html 290 | [10]: https://en.wikipedia.org/wiki/Letter_case#Title_case 291 | -------------------------------------------------------------------------------- /rules/horizontal-rules.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | ## Marker Character Style 4 | 5 | A horizontal rule must consist of three (3) hyphens (`-`) without spaces. 6 | 7 | > remark-lint: [rule-style][1] 8 | 9 | ###### Examples 10 | 11 | ⇣ **Incorrect** code for this rule: 12 | 13 | 14 | 15 | ```markdown 16 | - 17 | ``` 18 | 19 | ```markdown 20 | -- 21 | 22 | - - 23 | ``` 24 | 25 | ```markdown 26 | -- - 27 | 28 | - -- 29 | ``` 30 | 31 | 32 | 33 | ⇡ **Correct** code for this rule: 34 | 35 | ```markdown 36 | --- 37 | ``` 38 | 39 | ## No Prepended Or Appended Content 40 | 41 | Make sure that there are no other prepended or appended characters (including whitespaces). 42 | 43 | ###### Examples 44 | 45 | ⇣ **Incorrect** code for this rule: 46 | 47 | 48 | 49 | ```markdown 50 | .--- 51 | ``` 52 | 53 | ```markdown 54 | --- 55 | ``` 56 | 57 | ```markdown 58 | ---x 59 | ``` 60 | 61 | 62 | 63 | ⇡ **Correct** code for this rule: 64 | 65 | ```markdown 66 | --- 67 | ``` 68 | 69 | ## Empty Lines Before And After 70 | 71 | Always surround lines by a single empty line except at the beginning of the file. 72 | 73 | ###### Examples 74 | 75 | ⇣ **Incorrect** code for this rule: 76 | 77 | 78 | 79 | ```markdown 80 | ... snowflakes are falling. 81 | --- 82 | Sparkling and frozen... 83 | ``` 84 | 85 | ```markdown 86 | ... snowflakes are falling. 87 | 88 | 89 | --- 90 | 91 | 92 | Sparkling and frozen... 93 | ``` 94 | 95 | 96 | 97 | ⇡ **Correct** code for this rule: 98 | 99 | ```markdown 100 | ... snowflakes are falling. 101 | 102 | --- 103 | 104 | Sparkling and frozen... 105 | ``` 106 | 107 | ## Use Cases 108 | 109 | Horizontal rules can be used to separate sections when headers are not applicable or to separate base document elements like a header, body and footer. 110 | 111 | [1]: https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-rule-style 112 | -------------------------------------------------------------------------------- /rules/images.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | ## Absolute URLs 4 | 5 | Prefer absolute URLs instead of relative ones to improve the portability of the document. 6 | 7 | ###### Examples 8 | 9 | ⇣ **Incorrect** code for this rule: 10 | 11 | 12 | 13 | ```markdown 14 | ![snowflake icon][snowflake] snowflakes falling down in the winter! 15 | 16 | [snowflake]: ../snowflake.svg 17 | ``` 18 | 19 | 20 | 21 | ⇡ **Correct** code for this rule: 22 | 23 | ```markdown 24 | ![falling snowflakes][snowflakes] snowflakes falling down in the winter! 25 | 26 | [snowflakes]: https://raw.githubusercontent.com/nordtheme/assets/main/static/images/artworks/arctic/nature/dark/snowfall.svg?sanitize=true 27 | ``` 28 | 29 | ## Collapsed Reference Links 30 | 31 | Full references (such as `[Winter][winter]`) can also be written as a collapsed reference (`[Winter][]`) if normalizing the reference text yields the label. 32 | 33 | > remark-lint: [no-unneeded-full-reference-image][3] 34 | 35 | ###### Examples 36 | 37 | ⇣ **Incorrect** code for this rule: 38 | 39 | 40 | 41 | ```markdown 42 | ![arctic][arctic] 43 | ![snowflakes][snowflakes] 44 | ![winter][winter] 45 | 46 | [arctic]: https://arctic-is-beautiful.io/north-pole.png 47 | [snowflakes]: https://raw.githubusercontent.com/nordtheme/assets/main/static/images/artworks/arctic/nature/dark/snowfall.svg?sanitize=true 48 | [winter]: https://the-winter-is-sparkling-and-frozen.io/winter.png 49 | ``` 50 | 51 | 52 | 53 | ⇡ **Correct** code for this rule: 54 | 55 | ```markdown 56 | ![arctic][north-pole] 57 | ![snowflakes][] 58 | ![winter][] 59 | 60 | [north-pole]: https://arctic-is-beautiful.io/north-pole.png 61 | [snowflakes]: https://raw.githubusercontent.com/nordtheme/assets/main/static/images/artworks/arctic/nature/dark/snowfall.svg?sanitize=true 62 | [winter]: https://the-winter-is-sparkling-and-frozen.io/winter.png 63 | ``` 64 | 65 | ## Badges 66 | 67 | Use badges to represent simple information like latest version number and URL to its docs, the status of CI builds or fetched information of external systems like e.g. the latest version and total download amount from the [NPM registry][2] or [Rust crates][1]. 68 | 69 | ###### Examples 70 | 71 | ⇡ **Correct** code for this rule: 72 | 73 | ```markdown 74 | [![GitHub Shield Latest Release][4]][1] [![NPM Registry Shield Latest Release Version Number][3]][2] 75 | 76 | [1]: https://github.com/svengreb/styleguide-markdown/releases/latest 77 | [2]: https://www.npmjs.com/package/@svengreb/remark-preset-lint 78 | [3]: https://img.shields.io/npm/v/@svengreb/remark-preset-lint.svg?style=flat-square 79 | [4]: https://img.shields.io/github/release/svengreb/styleguide-markdown.svg?style=flat-square 80 | ``` 81 | 82 | [1]: https://crates.io 83 | [2]: https://www.npmjs.com 84 | [3]: https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-unneeded-full-reference-image 85 | -------------------------------------------------------------------------------- /rules/index.md: -------------------------------------------------------------------------------- 1 |

2 | 3 | 4 | 5 |

6 | 7 |

This section contains rules for Markdown with support for GitHub Flavored Markdown which is based on the CommonMark specification. 8 | 9 | Markdown is a [lightweight markup language][3] with plain text formatting syntax for writing structured documents. It is designed so that it can be converted to HTML and many other formats. 10 | 11 | As the initial specification of Markdown contained ambiguities and unanswered questions, many implementations and extensions of Markdown in many languages appeared over the years to answer these issues. Some extended the original Markdown syntax with conventions for footnotes, tables, and other document elements and allowed Markdown documents to be rendered in many formats other than HTML. 12 | 13 | Today the most used specifications are [CommonMark][1] and its superset [GitHub Flavored Markdown][2] which powers the content of many large websites like GitHub, StackOverflow, and Reddit used by millions of people. And Markdown started to be used beyond the web, to author books, articles, slide shows, letters, and lecture notes. 14 | 15 | ## Rules 16 | 17 | - [Overview](https://github.com/svengreb/styleguide-markdown/blob/main/rules/index.md) 18 | - [Accessibility A11Y](https://github.com/svengreb/styleguide-markdown/blob/main/rules/accessibility-a11y.md) 19 | - [Alternative Text](https://github.com/svengreb/styleguide-markdown/blob/main/rules/accessibility-a11y.md#alternative-text) 20 | - [Blockquotes](https://github.com/svengreb/styleguide-markdown/blob/main/rules/blockquotes.md) 21 | - [Indentation](https://github.com/svengreb/styleguide-markdown/blob/main/rules/blockquotes.md#indentation) 22 | - [Multi Line](https://github.com/svengreb/styleguide-markdown/blob/main/rules/blockquotes.md#multi-line) 23 | - [Code](https://github.com/svengreb/styleguide-markdown/blob/main/rules/code.md) 24 | - [Blocks](https://github.com/svengreb/styleguide-markdown/blob/main/rules/code.md#blocks) 25 | - [Syntax Highlighting](https://github.com/svengreb/styleguide-markdown/blob/main/rules/code.md#syntax-highlighting) 26 | - [Escape Newlines In Terminal Commands](https://github.com/svengreb/styleguide-markdown/blob/main/rules/code.md#blocks#escape-newlines-in-terminal-commands) 27 | - [No Shell Code Dollar Sign](https://github.com/svengreb/styleguide-markdown/blob/main/rules/code.md#no-shell-code-dollar-sign) 28 | - [Within Lists](https://github.com/svengreb/styleguide-markdown/blob/main/rules/code.md#within-lists) 29 | - [Inline](https://github.com/svengreb/styleguide-markdown/blob/main/rules/code.md#inline) 30 | - [Marker Character Style](https://github.com/svengreb/styleguide-markdown/blob/main/rules/code.md#marker-character-style) 31 | - [Use Cases](https://github.com/svengreb/styleguide-markdown/blob/main/rules/code.md#use-cases) 32 | - [Comments](https://github.com/svengreb/styleguide-markdown/blob/main/rules/comments.md) 33 | - [HTML](https://github.com/svengreb/styleguide-markdown/blob/main/rules/comments.md#html) 34 | - [Emphasis](https://github.com/svengreb/styleguide-markdown/blob/main/rules/emphasis.md) 35 | - [Italic](https://github.com/svengreb/styleguide-markdown/blob/main/rules/emphasis.md#italic) 36 | - [Bold](https://github.com/svengreb/styleguide-markdown/blob/main/rules/emphasis.md#bold) 37 | - [Strikethrough](https://github.com/svengreb/styleguide-markdown/blob/main/rules/emphasis.md#strikethrough) 38 | - [No Header Replacement](https://github.com/svengreb/styleguide-markdown/blob/main/rules/emphasis.md#no-header-replacement) 39 | - [No Inner Spacing](https://github.com/svengreb/styleguide-markdown/blob/main/rules/emphasis.md#no-inner-spacing) 40 | - [Headings](https://github.com/svengreb/styleguide-markdown/blob/main/rules/headings.md) 41 | - [ATX Style](https://github.com/svengreb/styleguide-markdown/blob/main/rules/headings.md#atx-style) 42 | - [Empty Lines Before And After](https://github.com/svengreb/styleguide-markdown/blob/main/rules/headings.md#empty-lines-before-and-after) 43 | - [Content Spacing](https://github.com/svengreb/styleguide-markdown/blob/main/rules/headings.md#content-spacing) 44 | - [No Content Before](https://github.com/svengreb/styleguide-markdown/blob/main/rules/headings.md#no-content-before) 45 | - [No Duplicate](https://github.com/svengreb/styleguide-markdown/blob/main/rules/headings.md#no-duplicate) 46 | - [Letter Case](https://github.com/svengreb/styleguide-markdown/blob/main/rules/headings.md#letter-case) 47 | - [Length](https://github.com/svengreb/styleguide-markdown/blob/main/rules/headings.md#length) 48 | - [Punctuation After Content](https://github.com/svengreb/styleguide-markdown/blob/main/rules/headings.md#punctuation-after-content) 49 | - [Horizontal Rules](https://github.com/svengreb/styleguide-markdown/blob/main/rules/horizontal-rules.md) 50 | - [Marker Character Style](https://github.com/svengreb/styleguide-markdown/blob/main/rules/horizontal-rules.md#marker-character-style) 51 | - [No Prepended Or Appended Content](https://github.com/svengreb/styleguide-markdown/blob/main/rules/horizontal-rules.md#no-prepended-or-appended-content) 52 | - [Empty Lines Before And After](https://github.com/svengreb/styleguide-markdown/blob/main/rules/horizontal-rules.md#empty-lines-before-and-after) 53 | - [Use Cases](https://github.com/svengreb/styleguide-markdown/blob/main/rules/horizontal-rules.md#use-cases) 54 | - [Images](https://github.com/svengreb/styleguide-markdown/blob/main/rules/images.md) 55 | - [Absolute URLs](https://github.com/svengreb/styleguide-markdown/blob/main/rules/images.md#absolute-urls) 56 | - [Badges](https://github.com/svengreb/styleguide-markdown/blob/main/rules/images.md#badges) 57 | - [Links](https://github.com/svengreb/styleguide-markdown/blob/main/rules/links.md) 58 | - [Prefer Reference Links](https://github.com/svengreb/styleguide-markdown/blob/main/rules/links.md#prefer-reference-links) 59 | - [Inline](https://github.com/svengreb/styleguide-markdown/blob/main/rules/links.md#inline) 60 | - [Definition Placement](https://github.com/svengreb/styleguide-markdown/blob/main/rules/links.md#definition-placement) 61 | - [Empty Line Before](https://github.com/svengreb/styleguide-markdown/blob/main/rules/links.md#empty-line-before) 62 | - [Letter Case](https://github.com/svengreb/styleguide-markdown/blob/main/rules/links.md#letter-case) 63 | - [No ID Inner Spacing](https://github.com/svengreb/styleguide-markdown/blob/main/rules/links.md#no-id-inner-spacing) 64 | - [No Trailing Or Leading Title Spaces](https://github.com/svengreb/styleguide-markdown/blob/main/rules/links.md#no-trailing-or-leading-title-spaces) 65 | - [Spacing After Colon](https://github.com/svengreb/styleguide-markdown/blob/main/rules/links.md#spacing-after-colon) 66 | - [Sorting](https://github.com/svengreb/styleguide-markdown/blob/main/rules/links.md#sorting) 67 | - [Reference Link Groups](https://github.com/svengreb/styleguide-markdown/blob/main/rules/links.md#reference-link-groups) 68 | - [Reference Link Group Ordering](https://github.com/svengreb/styleguide-markdown/blob/main/rules/links.md#reference-link-group-ordering) 69 | - [No Unused](https://github.com/svengreb/styleguide-markdown/blob/main/rules/links.md#no-unused) 70 | - [No Undefined](https://github.com/svengreb/styleguide-markdown/blob/main/rules/links.md#no-undefined) 71 | - [Autolink Protocol](https://github.com/svengreb/styleguide-markdown/blob/main/rules/links.md#autolink-protocol) 72 | - [Unique IDs](https://github.com/svengreb/styleguide-markdown/blob/main/rules/links.md#unique-ids) 73 | - [No Empty URL](https://github.com/svengreb/styleguide-markdown/blob/main/rules/links.md#no-empty-url) 74 | - [No Reference Like URL](https://github.com/svengreb/styleguide-markdown/blob/main/rules/links.md#no-reference-like-url) 75 | - [Lists](https://github.com/svengreb/styleguide-markdown/blob/main/rules/lists.md) 76 | - [Unordered Marker](https://github.com/svengreb/styleguide-markdown/blob/main/rules/lists.md#unordered-marker) 77 | - [Ordered Marker](https://github.com/svengreb/styleguide-markdown/blob/main/rules/lists.md#ordered-marker) 78 | - [No Content Before](https://github.com/svengreb/styleguide-markdown/blob/main/rules/lists.md#no-content-before) 79 | - [Continuous Indentation](https://github.com/svengreb/styleguide-markdown/blob/main/rules/lists.md#continuous-indentation) 80 | - [Empty Lines](https://github.com/svengreb/styleguide-markdown/blob/main/rules/lists.md#empty-lines) 81 | - [Empty Lines Before And After](https://github.com/svengreb/styleguide-markdown/blob/main/rules/lists.md#empty-lines-before-and-after) 82 | - [Letter Case](https://github.com/svengreb/styleguide-markdown/blob/main/rules/lists.md#letter-case) 83 | - [Punctuation After Items](https://github.com/svengreb/styleguide-markdown/blob/main/rules/lists.md#punctuation-after-items) 84 | - [Checkbox Character Style](https://github.com/svengreb/styleguide-markdown/blob/main/rules/lists.md#checkbox-character-style) 85 | - [Naming Conventions](https://github.com/svengreb/styleguide-markdown/blob/main/rules/naming-conventions.md) 86 | - [File Extension](https://github.com/svengreb/styleguide-markdown/blob/main/rules/naming-conventions.md#file-extension) 87 | - [File Naming](https://github.com/svengreb/styleguide-markdown/blob/main/rules/naming-conventions.md#file-naming) 88 | - [Paragraphs](https://github.com/svengreb/styleguide-markdown/blob/main/rules/paragraphs.md) 89 | - [No Indentation](https://github.com/svengreb/styleguide-markdown/blob/main/rules/paragraphs.md#no-indentation) 90 | - [Raw HTML](https://github.com/svengreb/styleguide-markdown/blob/main/rules/raw-html.md) 91 | - [Aligned Content](https://github.com/svengreb/styleguide-markdown/blob/main/rules/raw-html.md#aligned-content) 92 | - [Inline Content](https://github.com/svengreb/styleguide-markdown/blob/main/rules/raw-html.md#inline-content) 93 | - [Collapsed Content](https://github.com/svengreb/styleguide-markdown/blob/main/rules/raw-html.md#collapsed-content) 94 | - [Strings](https://github.com/svengreb/styleguide-markdown/blob/main/rules/strings.md) 95 | - [Quotes](https://github.com/svengreb/styleguide-markdown/blob/main/rules/strings.md#quotes) 96 | - [Line Length](https://github.com/svengreb/styleguide-markdown/blob/main/rules/strings.md#line-length) 97 | - [Tables](https://github.com/svengreb/styleguide-markdown/blob/main/rules/tables.md) 98 | - [Prefer Lists](https://github.com/svengreb/styleguide-markdown/blob/main/rules/tables.md#prefer-lists) 99 | - [Empty Lines Before And After](https://github.com/svengreb/styleguide-markdown/blob/main/rules/tables.md#empty-lines-before-and-after) 100 | - [Content Spacing](https://github.com/svengreb/styleguide-markdown/blob/main/rules/tables.md#content-spacing) 101 | - [Header Delimiter Row Spacing](https://github.com/svengreb/styleguide-markdown/blob/main/rules/tables.md#header-delimiter-row-spacing) 102 | - [Minimum Column Width](https://github.com/svengreb/styleguide-markdown/blob/main/rules/tables.md#minimum-column-width) 103 | - [Alignment](https://github.com/svengreb/styleguide-markdown/blob/main/rules/tables.md#alignment) 104 | - [No Indentation](https://github.com/svengreb/styleguide-markdown/blob/main/rules/tables.md#no-indentation) 105 | - [Whitespace](https://github.com/svengreb/styleguide-markdown/blob/main/rules/whitespace.md) 106 | - [Indentation Character](https://github.com/svengreb/styleguide-markdown/blob/main/rules/whitespace.md#indentation-character) 107 | - [Newline](https://github.com/svengreb/styleguide-markdown/blob/main/rules/whitespace.md#newline) 108 | - [Before Blocks](https://github.com/svengreb/styleguide-markdown/blob/main/rules/whitespace.md#before-blocks) 109 | - [After Sentences](https://github.com/svengreb/styleguide-markdown/blob/main/rules/whitespace.md#after-sentences) 110 | - [Maximum Line Length](https://github.com/svengreb/styleguide-markdown/blob/main/rules/whitespace.md#maximum-line-length) 111 | - [Trailing](https://github.com/svengreb/styleguide-markdown/blob/main/rules/whitespace.md#trailing) 112 | 113 | [1]: https://commonmark.org 114 | [2]: https://github.github.com/gfm 115 | [3]: https://en.wikipedia.org/wiki/Lightweight_markup_language 116 | -------------------------------------------------------------------------------- /rules/links.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | ## Prefer Reference Links 4 | 5 | Always use [reference links][6] instead of [inline](#inline) links except for inner anchor links ([fragment identifiers][19]). 6 | 7 | There are three kinds of reference links: full, collapsed, and shortcut. 8 | This can be one of the three reference link types: 9 | 10 | - [full][4] 11 | - [collapsed][3] 12 | - [short][5] 13 | 14 | ###### Examples 15 | 16 | ⇣ **Incorrect** code for this rule: 17 | 18 | 19 | 20 | ```markdown 21 | [Winter](https://the-winter-is-sparkling-and-frozen.io) 22 | ``` 23 | 24 | 25 | 26 | ⇡ **Correct** code for this rule: 27 | 28 | ```markdown 29 | [Winter](#winter) 30 | 31 | ## Winter 32 | ``` 33 | 34 | ```markdown 35 | [Winter][winter-info] 36 | 37 | [winter-info]: https://the-winter-is-sparkling-and-frozen.io 38 | ``` 39 | 40 | ## Inline 41 | 42 | If it is necessary to use inline links instead of the preferred [reference links](prefer-reference-links) try to use shortened URLs wherever possible to keep the line length overhead as small as possible. 43 | 44 | ###### Examples 45 | 46 | ⇣ **Incorrect** code for this rule: 47 | 48 | 49 | 50 | ```markdown 51 | [Winter](https://the-winter-is-sparkling-and-frozen-and-snow-falls-down.io) 52 | ``` 53 | 54 | 55 | 56 | ⇡ **Correct** code for this rule: 57 | 58 | ```markdown 59 | [Winter](https://sho.rt/l1n-k) 60 | ``` 61 | 62 | ## Definition Placement 63 | 64 | Always place reference links at the bottom of the document. This keeps the focus of the reader on the content and increases the maintainability. 65 | 66 | > remark-lint: [final-definition][9] 67 | 68 | ###### Examples 69 | 70 | ⇣ **Incorrect** code for this rule: 71 | 72 | 73 | 74 | ```markdown 75 | The [Winter][winter-info] is sparkling and frozen! 76 | 77 | [winter-info]: https://the-winter-is-sparkling-and-frozen.io 78 | 79 | Many snowflakes are falling down. 80 | ``` 81 | 82 | 83 | 84 | ⇡ **Correct** code for this rule: 85 | 86 | ```markdown 87 | The [Winter][winter-info] is sparkling and frozen! 88 | 89 | Many snowflakes are falling down. 90 | 91 | [winter-info]: https://the-winter-is-sparkling-and-frozen.io 92 | ``` 93 | 94 | ## Empty Line Before 95 | 96 | Always add a single empty line before the first reference link. 97 | 98 | ###### Examples 99 | 100 | ⇣ **Incorrect** code for this rule: 101 | 102 | 103 | 104 | ```markdown 105 | The [Winter][winter-info] is sparkling and frozen! [Snowflakes][snowflakes-info] are falling. 106 | [snowflakes-info]: https://in-the-winter-many-snowflakes-are-falling.io 107 | [winter-info]: https://the-winter-is-sparkling-and-frozen.io 108 | ``` 109 | 110 | 111 | 112 | ⇡ **Correct** code for this rule: 113 | 114 | ```markdown 115 | The [Winter][winter-info] is sparkling and frozen! [Snowflakes][snowflakes-info] are falling. 116 | 117 | [snowflakes-info]: https://in-the-winter-many-snowflakes-are-falling.io 118 | [winter-info]: https://the-winter-is-sparkling-and-frozen.io 119 | ``` 120 | 121 | ## Letter Case 122 | 123 | Only use lower case letters for reference link IDs. This increases the readability and prevents errors since links are [case-insensitive][2]. 124 | 125 | > remark-lint: [definition-case][7] 126 | 127 | ###### Examples 128 | 129 | ⇣ **Incorrect** code for this rule: 130 | 131 | 132 | 133 | ```markdown 134 | The [Winter][WinterInfo] is sparkling and frozen! [Snowflakes][snowFlakes-Info] are falling. 135 | 136 | [snowFlakes-Info]: https://in-the-winter-many-snowflakes-are-falling.io 137 | [WinterInfo]: https://the-winter-is-sparkling-and-frozen.io 138 | ``` 139 | 140 | 141 | 142 | ⇡ **Correct** code for this rule: 143 | 144 | ```markdown 145 | The [Winter][winter-info] is sparkling and frozen! [Snowflakes][snowflakes-info] are falling. 146 | 147 | [snowflakes-info]: https://in-the-winter-many-snowflakes-are-falling.io 148 | [winter-info]: https://the-winter-is-sparkling-and-frozen.io 149 | ``` 150 | 151 | ## No ID Inner Spacing 152 | 153 | Don't use inner spaces within link IDs. 154 | 155 | > remark-lint: [no-inline-padding][14] 156 | 157 | ###### Examples 158 | 159 | ⇣ **Incorrect** code for this rule: 160 | 161 | 162 | 163 | ```markdown 164 | The [Winter][ winter-info ] is sparkling and frozen! 165 | 166 | [Snowflakes][ snowflakes-info ] are falling. 167 | 168 | [ snowflakes-info ]: https://in-the-winter-many-snowflakes-are-falling.io 169 | [ winter-info ]: https://the-winter-is-sparkling-and-frozen.io 170 | ``` 171 | 172 | 173 | 174 | ⇡ **Correct** code for this rule: 175 | 176 | ```markdown 177 | The [Winter][winter-info] is sparkling and frozen! 178 | 179 | [Snowflakes][snowflakes-info] are falling. 180 | 181 | [snowflakes-info]: https://in-the-winter-many-snowflakes-are-falling.io 182 | [winter-info]: https://the-winter-is-sparkling-and-frozen.io 183 | ``` 184 | 185 | ## No Trailing Or Leading Title Spaces 186 | 187 | Don't use trailing or leading spaces in link titles. Add necessary spaces before or after the brackets/braces (`[]`, `()`) to format links within flowing text. 188 | 189 | ###### Examples 190 | 191 | ⇣ **Incorrect** code for this rule: 192 | 193 | 194 | 195 | ```markdown 196 | The[ Winter ][winter-info]is sparkling and frozen![ Snowflakes ][snowflakes-info]are falling. 197 | 198 | [snowflakes-info]: https://in-the-winter-many-snowflakes-are-falling.io 199 | [winter-info]: https://the-winter-is-sparkling-and-frozen.io 200 | ``` 201 | 202 | 203 | 204 | ⇡ **Correct** code for this rule: 205 | 206 | ```markdown 207 | The [Winter][winter-info] is sparkling and frozen! [Snowflakes][snowflakes-info] are falling. 208 | 209 | [snowflakes-info]: https://in-the-winter-many-snowflakes-are-falling.io 210 | [winter-info]: https://the-winter-is-sparkling-and-frozen.io 211 | ``` 212 | 213 | ## Spacing After Colon 214 | 215 | Only use a single space after the colon of [reference links](#prefer-reference-links). Don't add multiple spaces to e.g. align the URLs of reference links vertically. 216 | 217 | > remark-lint: [definition-spacing][8] 218 | 219 | ###### Examples 220 | 221 | ⇣ **Incorrect** code for this rule: 222 | 223 | 224 | 225 | ```markdown 226 | The [Winter][winter-info] is sparkling and frozen! [Snowflakes][snowflakes-info] are falling. 227 | 228 | [snowflakes-info]: https://in-the-winter-many-snowflakes-are-falling.io 229 | [winter-info]: https://the-winter-is-sparkling-and-frozen.io 230 | ``` 231 | 232 | ```markdown 233 | The [Winter][winter-info] is sparkling and frozen! [Snowflakes][snowflakes-info] are falling. 234 | 235 | [snowflakes-info]:https://in-the-winter-many-snowflakes-are-falling.io 236 | [winter-info]:https://the-winter-is-sparkling-and-frozen.io 237 | ``` 238 | 239 | 240 | 241 | ⇡ **Correct** code for this rule: 242 | 243 | ```markdown 244 | The [Winter][winter-info] is sparkling and frozen! [Snowflakes][snowflakes-info] are falling. 245 | 246 | [snowflakes-info]: https://in-the-winter-many-snowflakes-are-falling.io 247 | [winter-info]: https://the-winter-is-sparkling-and-frozen.io 248 | ``` 249 | 250 | ## Sorting 251 | 252 | Always sort reference links alphabetically by their IDs. Each [reference link group](#reference-link-groups) must be sorted independent of others! 253 | 254 | It is home for many beautiful animals like snowy owls, arctic foxes, and grizzly bears 255 | 256 | ###### Examples 257 | 258 | ⇣ **Incorrect** code for this rule: 259 | 260 | 261 | 262 | ```markdown 263 | [Snowflakes][snowflakes-info] are falling. 264 | 265 | The [Winter][winter-info] is sparkling and frozen! 266 | 267 | The [Arctic][arctic-animals] is home for many beautiful animals. 268 | 269 | Snowballs are made of [1000s of snowflakes][1000-snowball_flakes]. 270 | 271 | [snowflakes-info]: https://in-the-winter-many-snowflakes-are-falling.io 272 | [winter-info]: https://the-winter-is-sparkling-and-frozen.io 273 | [arctic-animals]: https://arctic-home-for.animals 274 | [1000-snowball_flakes]: https://1000-snowball.flakes 275 | ``` 276 | 277 | 278 | 279 | ⇡ **Correct** code for this rule: 280 | 281 | ```markdown 282 | [Snowflakes][snowflakes-info] are falling. 283 | 284 | The [Winter][winter-info] is sparkling and frozen! 285 | 286 | The [Arctic][arctic-animals] is home for many beautiful animals. 287 | 288 | Snowballs are made of [1000s of snowflakes][1000-snowball_flakes]. 289 | 290 | [1000-snowball_flakes]: https://1000-snowball.flakes 291 | [arctic-animals]: https://arctic-home-for.animals 292 | [snowflakes-info]: https://in-the-winter-many-snowflakes-are-falling.io 293 | [winter-info]: https://the-winter-is-sparkling-and-frozen.io 294 | ``` 295 | 296 | ## Reference Link Groups 297 | 298 | Use one block for internal and external reference links. 299 | 300 | ###### Examples 301 | 302 | ⇣ **Incorrect** code for this rule: 303 | 304 | 305 | 306 | ```markdown 307 | The [Winter][winter-info] is sparkling and frozen! [Snowflakes][snowflakes-info] are falling. 308 | 309 | [winter-info]: winter/info.md 310 | 311 | [snowflakes-info]: https://in-the-winter-many-snowflakes-are-falling.io 312 | ``` 313 | 314 | ```markdown 315 | The [Winter][winter-info] is sparkling and frozen! [Snowflakes][snowflakes-info] are falling. 316 | 317 | [winter-info]: winter/info.md 318 | 319 | 320 | 321 | 322 | [snowflakes-info]: https://in-the-winter-many-snowflakes-are-falling.io 323 | ``` 324 | 325 | 326 | 327 | ⇡ **Correct** code for this rule: 328 | 329 | ```markdown 330 | The [Winter][winter-info] is sparkling and frozen! [Snowflakes][snowflakes-info] are falling. 331 | 332 | [winter-info]: winter/info.md 333 | [snowflakes-info]: https://in-the-winter-many-snowflakes-are-falling.io 334 | ``` 335 | 336 | ## Reference Link Group Ordering 337 | 338 | It is more convenient to always follow the same organization for reference link order to easier find internal and external targets. 339 | 340 | 1. Internal links group 341 | 1.1 [full reference links][4] 342 | 1.2 [collapsed reference links][3] 343 | 1.2 [short reference links][5] 344 | 2. External links group 345 | 346 | ###### Examples 347 | 348 | ⇣ **Incorrect** code for this rule: 349 | 350 | 351 | 352 | ```markdown 353 | The [Winter][winter-info] is sparkling and frozen! 354 | 355 | [Snowflakes][] are falling. 356 | 357 | The [Arctic][arctic-animals] is home for many beautiful animals. 358 | 359 | [snowflakes]: https://in-the-winter-many-snowflakes-are-falling.io 360 | [arctic-animals]: arctic-animals.md 361 | [winter-info]: winter/info.md 362 | ``` 363 | 364 | 365 | 366 | ⇡ **Correct** code for this rule: 367 | 368 | ```markdown 369 | The [Winter][winter-info] is sparkling and frozen! 370 | 371 | [Snowflakes][] are falling. 372 | 373 | The [Arctic][arctic-animals] is home for many beautiful animals. 374 | 375 | [arctic-animals]: arctic-animals.md 376 | [winter-info]: winter/info.md 377 | [snowflakes]: https://in-the-winter-many-snowflakes-are-falling.io 378 | ``` 379 | 380 | ## No Unused 381 | 382 | Remove unused reference links to improve the overview and maintainability. 383 | 384 | > remark-lint: [no-unused-definitions][18] 385 | 386 | ###### Examples 387 | 388 | ⇣ **Incorrect** code for this rule: 389 | 390 | 391 | 392 | ```markdown 393 | The [Winter][winter-info] is sparkling and frozen! 394 | 395 | [arctic-animals]: arctic-animals.md 396 | [snowflakes]: snow/flakes.md 397 | [winter-info]: winter/info.md 398 | ``` 399 | 400 | 401 | 402 | ⇡ **Correct** code for this rule: 403 | 404 | ```markdown 405 | The [Winter][winter-info] is sparkling and frozen! 406 | 407 | [winter-info]: winter/info.md 408 | ``` 409 | 410 | ## No Undefined 411 | 412 | Never use references that are not defined. 413 | 414 | > remark-lint: [no-undefined-references][16] 415 | 416 | ###### Examples 417 | 418 | ⇣ **Incorrect** code for this rule: 419 | 420 | 421 | 422 | ```markdown 423 | The [Winter][winter] is sparkling and frozen! 424 | ``` 425 | 426 | 427 | 428 | ⇡ **Correct** code for this rule: 429 | 430 | ```markdown 431 | The [Winter][winter] is sparkling and frozen! 432 | 433 | [winter]: https://the-winter-is-sparkling-and-frozen.io 434 | ``` 435 | 436 | ## No Duplicates 437 | 438 | Prevent definitions that use the same URL. 439 | 440 | > remark-lint: [no-duplicate-defined-urls][11] 441 | 442 | ###### Examples 443 | 444 | ⇣ **Incorrect** code for this rule: 445 | 446 | 447 | 448 | ```markdown 449 | [arctic][] 450 | [north-pole][] 451 | 452 | [arctic]: https://arctic-is-beautiful.io 453 | [north-pole]: https://arctic-is-beautiful.io 454 | ``` 455 | 456 | 457 | 458 | ⇡ **Correct** code for this rule: 459 | 460 | ```markdown 461 | [arctic][] 462 | [north-pole][] 463 | 464 | [arctic]: https://arctic-is-beautiful.io 465 | [north-pole]: https://frozen-nordic-arctic.io 466 | ``` 467 | 468 | ## Collapsed References 469 | 470 | Full references (such as `[Winter][winter]`) can also be written as a collapsed reference (`[Winter][]`) if normalizing the reference text yields the label. 471 | 472 | > remark-lint: [no-unneeded-full-reference-link][17] 473 | 474 | ###### Examples 475 | 476 | ⇣ **Incorrect** code for this rule: 477 | 478 | 479 | 480 | ```markdown 481 | [arctic][arctic] 482 | [snowflake][snowflake] 483 | [Winter][winter] 484 | 485 | [arctic]: https://arctic-is-beautiful.io 486 | [snowflake]: https://snow-is-falling-down.io 487 | [winter]: https://the-winter-is-sparkling-and-frozen.io 488 | ``` 489 | 490 | 491 | 492 | ⇡ **Correct** code for this rule: 493 | 494 | ```markdown 495 | [arctic][north-pole] 496 | [snowflake][] 497 | [Winter][] 498 | 499 | [north-pole]: https://arctic-is-beautiful.io 500 | [snowflake]: https://snow-is-falling-down.io 501 | [winter]: https://the-winter-is-sparkling-and-frozen.io 502 | ``` 503 | 504 | ## Autolink Protocol 505 | 506 | Always add a valid protocol when using [autolinks][1]. 507 | 508 | > remark-lint: [no-auto-link-without-protocol][10] 509 | 510 | ###### Examples 511 | 512 | ⇣ **Incorrect** code for this rule: 513 | 514 | 515 | 516 | ```markdown 517 | www.svengreb.de 518 | 519 | svengreb.de 520 | ``` 521 | 522 | 523 | 524 | ⇡ **Correct** code for this rule: 525 | 526 | ```markdown 527 | https://svengreb.de 528 | 529 | https://www.svengreb.de 530 | 531 | http://svengreb.de 532 | 533 | http://www.svengreb.de 534 | ``` 535 | 536 | ```markdown 537 | mailto:development@svengreb.de 538 | ``` 539 | 540 | ## Unique IDs 541 | 542 | Reference link IDs must be unique within a document file. 543 | 544 | > remark-lint: [no-duplicate-definitions][12] 545 | 546 | ###### Examples 547 | 548 | ⇣ **Incorrect** code for this rule: 549 | 550 | 551 | 552 | ```markdown 553 | [snow]: snow/flakes.md 554 | [snow]: snow/index.md 555 | ``` 556 | 557 | 558 | 559 | ⇡ **Correct** code for this rule: 560 | 561 | ```markdown 562 | [snow]: snow/index.md 563 | [snowflakes]: snow/flakes.md 564 | ``` 565 | 566 | ## No Empty URL 567 | 568 | Don't use links or images with empty URLs. 569 | 570 | > remark-lint: [no-empty-url][13] 571 | 572 | ###### Examples 573 | 574 | ⇣ **Incorrect** code for this rule: 575 | 576 | 577 | 578 | ```markdown 579 | The [winter][winter] is sparkling and frozen! 580 | 581 | ![snowflake image][snowflake] 582 | 583 | [snowflake]: 584 | [winter]: 585 | ``` 586 | 587 | ```markdown 588 | The [winter]() is sparkling and frozen! 589 | 590 | ![snowflake image]() 591 | ``` 592 | 593 | 594 | 595 | ⇡ **Correct** code for this rule: 596 | 597 | ```markdown 598 | The [winter][winter] is sparkling and frozen! 599 | 600 | ![falling snowflakes][snowflakes] 601 | 602 | [snowflakes]: https://raw.githubusercontent.com/nordtheme/assets/main/static/images/artworks/arctic/nature/dark/snowfall.svg?sanitize=true 603 | [winter]: https://the-winter-is-sparkling-and-frozen.io 604 | ``` 605 | 606 | ```markdown 607 | The [winter](https://the-winter-is-sparkling-and-frozen.io) is sparkling and frozen! 608 | 609 | ![falling snowflakes](https://raw.githubusercontent.com/nordtheme/assets/main/static/images/artworks/arctic/nature/dark/snowfall.svg?sanitize=true) 610 | ``` 611 | 612 | ## No Reference Like URL 613 | 614 | Never use URLs that are also defined reference link identifiers. 615 | 616 | > remark-lint: [no-reference-like-url][15] 617 | 618 | ###### Examples 619 | 620 | ⇣ **Incorrect** code for this rule: 621 | 622 | 623 | 624 | ```markdown 625 | The [winter](winter) is sparkling and frozen! 626 | 627 | [winter]: https://the-winter-is-sparkling-and-frozen.io 628 | ``` 629 | 630 | 631 | 632 | ⇡ **Correct** code for this rule: 633 | 634 | ```markdown 635 | The [winter](https://the-winter-is-sparkling-and-frozen.io) is sparkling and frozen! 636 | 637 | [winter]: https://the-winter-is-sparkling-and-frozen.io 638 | ``` 639 | 640 | [1]: https://github.github.com/gfm/#autolinks 641 | [2]: https://github.github.com/gfm/#example-170 642 | [3]: https://github.github.com/gfm/#collapsed-reference-link 643 | [4]: https://github.github.com/gfm/#full-reference-link 644 | [5]: https://github.github.com/gfm/#shortcut-reference-link 645 | [6]: https://github.github.com/gfm/#reference-link 646 | [7]: https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-definition-case 647 | [8]: https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-definition-spacing 648 | [9]: https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-final-definition 649 | [10]: https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-auto-link-without-protocol 650 | [11]: https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-duplicate-defined-urls 651 | [12]: https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-duplicate-definitions 652 | [13]: https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-empty-url 653 | [14]: https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-inline-padding 654 | [15]: https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-reference-like-url 655 | [16]: https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-undefined-references 656 | [17]: https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-unneeded-full-reference-link 657 | [18]: https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-unused-definitions 658 | [19]: https://html.spec.whatwg.org/multipage/browsers.html#navigating-to-a-fragment-identifier 659 | -------------------------------------------------------------------------------- /rules/lists.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | ## Unordered Marker 4 | 5 | Use dashes `-` as marker. 6 | 7 | > remark-lint: [unordered-list-marker-style][9] 8 | 9 | ###### Examples 10 | 11 | ⇣ **Incorrect** code for this rule: 12 | 13 | 14 | 15 | ```markdown 16 | * Winter 17 | * Snow 18 | * Frost 19 | ``` 20 | 21 | ```markdown 22 | + Winter 23 | + Snow 24 | + Frost 25 | ``` 26 | 27 | 28 | 29 | ⇡ **Correct** code for this rule: 30 | 31 | ```markdown 32 | - Winter 33 | - Snow 34 | - Frost 35 | ``` 36 | 37 | ## Ordered Marker 38 | 39 | Use continuous numerating marker for ordered list items. This increases the readability and overview and allows to refer to items by their number in the same markdown file or externally. It also allows to create sub-items which is not possible if the same number will be used for all top-level items. The marker character must be a dot (`.`), characters like a closing brace (`)`) are not allowed since they are only supported in [CommonMark][1]. 40 | 41 | The only disadvantage is that references break when a new list item is added. This problem can be reduced by 42 | 43 | - using an unordered list until the final structure and layout has been determined. 44 | - keeping references close to the list so authors are less likely to forget to update them. 45 | - always specify an specific version of the markdown file when referring from an external document. 46 | 47 | > remark-lint: [ordered-list-marker-style][7] and [ordered-list-marker-value][8] 48 | 49 | ###### Examples 50 | 51 | ⇣ **Incorrect** code for this rule: 52 | 53 | 54 | 55 | ```markdown 56 | 1. Winter 57 | 1. Snow 58 | 1.1 Snowflakes 59 | 1. Frost 60 | ``` 61 | 62 | ```markdown 63 | 1) Winter 64 | 1) Snow 65 | 1.1) Snowflakes 66 | 1) Frost 67 | ``` 68 | 69 | ```markdown 70 | 1) Winter 71 | 2) Snow 72 | 2.1) Snowflakes 73 | 3) Frost 74 | ``` 75 | 76 | 77 | 78 | ⇡ **Correct** code for this rule: 79 | 80 | ```markdown 81 | 1. Winter 82 | 2. Snow 83 | 2.1 Snowflakes 84 | 3. Frost 85 | ``` 86 | 87 | ## No Content Before 88 | 89 | Make sure that there are no other characters (including whitespaces) in front of each list item. 90 | 91 | > remark-lint: [list-item-bullet-indent][3] 92 | 93 | ###### Examples 94 | 95 | Note: The `·` character represents a whitespace character. 96 | 97 | ⇣ **Incorrect** code for this rule: 98 | 99 | 100 | 101 | ```markdown 102 | x- Winter 103 | - Snow 104 | .- Snowflakes 105 | "- Frost 106 | ·- Frost 107 | ``` 108 | 109 | ```markdown 110 | x1. Winter 111 | 2. Snow 112 | .2.1 Snowflakes 113 | "3. Frost 114 | ·3. Frost 115 | ``` 116 | 117 | 118 | 119 | ⇡ **Correct** code for this rule: 120 | 121 | ```markdown 122 | - Winter 123 | - Snow 124 | - Snowflakes 125 | - Frost 126 | ``` 127 | 128 | ```markdown 129 | 1. Winter 130 | 2. Snow 131 | 2.1 Snowflakes 132 | 3. Frost 133 | ``` 134 | 135 | ## Continuous Indentation 136 | 137 | Use two (2) whitespaces for continuous indentation of nested items and their content. 138 | 139 | > remark-lint: [list-item-content-indent][4] and [list-item-indent][5] 140 | 141 | ###### Examples 142 | 143 | ⇣ **Incorrect** code for this rule: 144 | 145 | 146 | 147 | ```markdown 148 | - Winter 149 | - Snow 150 | - Snowflakes 151 | - Frost 152 | - Arctic 153 | - Sparkling 154 | - Frozen 155 | ``` 156 | 157 | ```markdown 158 | - Winter 159 | Sparkling and frozen! 160 | - Snowflakes 161 | Made of snow! 162 | - Snow 163 | Falls down! 164 | Arctic beauty 165 | ``` 166 | 167 | ````markdown 168 | - Winter 169 | ```js 170 | import React, { PureComponent } from "react"; 171 | class Frost extends PureComponent { 172 | // ... 173 | } 174 | export default Frost; 175 | ``` 176 | - Snow 177 | ```java 178 | import static winter.Snow; 179 | String[] flakes = Snow.getFlakes(); 180 | ``` 181 | - Frost 182 | > Sparkling and frozen! 183 | ```` 184 | 185 | 186 | 187 | ⇡ **Correct** code for this rule: 188 | 189 | ```markdown 190 | - Winter 191 | - Snow 192 | - Snowflakes 193 | - Frost 194 | - Arctic 195 | - Sparkling 196 | - Frozen 197 | ``` 198 | 199 | ```markdown 200 | - Winter 201 | Sparkling and frozen! 202 | - Snowflakes 203 | Made of snow! 204 | - Snow 205 | Falls down! 206 | Arctic beauty 207 | ``` 208 | 209 | ````markdown 210 | - Winter 211 | ```js 212 | import React, { PureComponent } from "react"; 213 | class Frost extends PureComponent { 214 | // ... 215 | } 216 | export default Frost; 217 | ``` 218 | - Snow 219 | ```java 220 | import winter.Snow; 221 | String[] flakes = Snow.getFlakes(); 222 | ``` 223 | - Frost 224 | > Sparkling and frozen! 225 | ```` 226 | 227 | ## Empty Lines 228 | 229 | A list must not contain blank lines between each list item. 230 | 231 | > remark-lint: [list-item-spacing][6] 232 | 233 | ###### Examples 234 | 235 | ⇣ **Incorrect** code for this rule: 236 | 237 | 238 | 239 | ```markdown 240 | - Winter 241 | 242 | - Snow 243 | 244 | - Snowflakes 245 | 246 | - Frost 247 | ``` 248 | 249 | 250 | 251 | ⇡ **Correct** code for this rule: 252 | 253 | ```markdown 254 | - Winter 255 | - Snow 256 | - Snowflakes 257 | - Frost 258 | ``` 259 | 260 | ## Empty Lines Before And After 261 | 262 | Always surround lists by a single empty line except at the beginning of the file. 263 | 264 | ###### Examples 265 | 266 | ⇣ **Incorrect** code for this rule: 267 | 268 | 269 | 270 | ```markdown 271 | ... snowflakes are falling. 272 | - Winter 273 | - Snow 274 | - Snowflakes 275 | - Frost 276 | Sparkling and frozen... 277 | ``` 278 | 279 | ```markdown 280 | ... snowflakes are falling. 281 | 282 | 283 | - Winter 284 | - Snow 285 | - Snowflakes 286 | - Frost 287 | 288 | 289 | Sparkling and frozen... 290 | ``` 291 | 292 | 293 | 294 | ⇡ **Correct** code for this rule: 295 | 296 | ```markdown 297 | ... snowflakes are falling. 298 | 299 | - Winter 300 | - Snow 301 | - Snowflakes 302 | - Frost 303 | 304 | Sparkling and frozen... 305 | ``` 306 | 307 | ## Letter Case 308 | 309 | The case depends on the part of speech and syntax a list item contains. In general use upper cases for enumerations because most of the time the content is a noun, proper name, code snippet or standalone sentence. 310 | 311 | When the list items are meant to be imaginary concatenated with the sentence that comes before the list, adapt to the same case as the context. 312 | 313 | ###### Examples 314 | 315 | ⇣ **Incorrect** code for this rule: 316 | 317 | 318 | 319 | ```markdown 320 | The winter has 321 | 322 | - Many snowflakes that are falling down. 323 | - Sparkling and frozen elements! 324 | - A lot of beautiful animals like snowy owls, arctic foxes, and grizzly bears. 325 | ``` 326 | 327 | Enumerations or context-dependent: 328 | 329 | ```markdown 330 | The winter has 331 | 332 | - **snowflakes** - They are falling down. 333 | - **elements** - They are sparkling and frozen! 334 | - **beautiful animals** - Like e.g a lot of snowy owls, arctic foxes, and grizzly bears. 335 | ``` 336 | 337 | Proper names or code snippets: 338 | 339 | ```markdown 340 | A list for 341 | 342 | - react 343 | - `string` 344 | ``` 345 | 346 | 347 | 348 | ⇡ **Correct** code for this rule: 349 | 350 | ```markdown 351 | The winter has 352 | 353 | - many snowflakes that are falling down. 354 | - sparkling and frozen elements! 355 | - a lot of beautiful animals like snowy owls, arctic foxes, and grizzly bears. 356 | ``` 357 | 358 | Enumerations or context-dependent: 359 | 360 | ```markdown 361 | The winter has 362 | 363 | - **Snowflakes** - They are falling down. 364 | - **Elements** - They are sparkling and frozen! 365 | - **Beautiful animals** - e.g a lot of snowy owls, arctic foxes, and grizzly bears. 366 | ``` 367 | 368 | Proper names or code snippets: 369 | 370 | ```markdown 371 | A list for 372 | 373 | - React 374 | - `String` 375 | ``` 376 | 377 | ## Punctuation After Items 378 | 379 | Use punctuation at the end of a list item when it contains a sentence that starts with an upper case letter or multiple sentences or paragraphs. Omit the punctuation for single words. 380 | 381 | ###### Examples 382 | 383 | ⇣ **Incorrect** code for this rule: 384 | 385 | 386 | 387 | ```markdown 388 | - Winter. 389 | - Snow. 390 | - Frost. 391 | ``` 392 | 393 | ```markdown 394 | The Winter is 395 | 396 | - sparkling and frozen 397 | - cold and snowy 398 | - bright and enlightened 399 | ``` 400 | 401 | 402 | 403 | ⇡ **Correct** code for this rule: 404 | 405 | ```markdown 406 | - Winter 407 | - Snow 408 | - Frost 409 | ``` 410 | 411 | ```markdown 412 | The Winter is 413 | 414 | - sparkling and frozen. 415 | - cold and snowy. 416 | - bright and enlightened. 417 | ``` 418 | 419 | ## Checkbox Character Style 420 | 421 | Use `x` for ticked checkboxes and a single space ` ` for non ticked checkboxes. 422 | 423 | > remark-lint: [checkbox-character-style][2] 424 | 425 | ###### Examples 426 | 427 | ⇣ **Incorrect** code for this rule: 428 | 429 | 430 | 431 | ```markdown 432 | - [!] Winter 433 | - [~] Snow 434 | - [»] Frost 435 | ``` 436 | 437 | ```markdown 438 | - [] Winter 439 | - [ ] Snow 440 | - [ ] Frost 441 | ``` 442 | 443 | 444 | 445 | ⇡ **Correct** code for this rule: 446 | 447 | ```markdown 448 | - [x] Winter 449 | - [ ] Snow 450 | - [x] Frost 451 | ``` 452 | 453 | [1]: https://commonmark.org 454 | [2]: https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-checkbox-character-style 455 | [3]: https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-list-item-bullet-indent 456 | [4]: https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-list-item-content-indent 457 | [5]: https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-list-item-indent 458 | [6]: https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-list-item-spacing 459 | [7]: https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-ordered-list-marker-style 460 | [8]: https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-ordered-list-marker-value 461 | [9]: https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-unordered-list-marker-style 462 | -------------------------------------------------------------------------------- /rules/naming-conventions.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | ## File Extension 4 | 5 | Always use `.md` file extension also for files with [GFM syntax][1]. 6 | 7 | > remark-lint: [file-extension][2] 8 | 9 | ###### Examples 10 | 11 | ⇣ **Incorrect** code for this rule: 12 | 13 | 14 | 15 | ```raw 16 | ice.gfm 17 | snow.mdk 18 | frost.markdown 19 | ``` 20 | 21 | 22 | 23 | ⇡ **Correct** code for this rule: 24 | 25 | ```markdown 26 | ice.md 27 | snow.md 28 | frost.md 29 | ``` 30 | 31 | ## File Naming 32 | 33 | Always prefer [spinal-case][5] (also named [_kebab-case_ or _hyphen-separated_][4]) for file names and use [snake_case][6] only if it contributes to a better understanding of the content. 34 | 35 | > remark-lint: [no-file-name-mixed-case][3] 36 | 37 | ###### Examples 38 | 39 | ⇣ **Incorrect** code for this rule: 40 | 41 | 42 | 43 | ```raw 44 | winterSeason.md 45 | IceCold.md 46 | snow fall.md 47 | ``` 48 | 49 | 50 | 51 | ⇡ **Correct** code for this rule: 52 | 53 | ```raw 54 | winter_season.md 55 | ice_cold.md 56 | snow_fall.md 57 | ``` 58 | 59 | ⇢ **Recommended** code for this rule: 60 | 61 | ```raw 62 | winter-season.md 63 | ice-cold.md 64 | snow-fall.md 65 | ``` 66 | 67 | [1]: https://github.github.com/gfm 68 | [2]: https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-file-extension 69 | [3]: https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-file-name-mixed-case 70 | [4]: https://stackoverflow.com/questions/11273282/whats-the-name-for-hyphen-separated-case/12273101 71 | [5]: https://en.wikipedia.org/wiki/Letter_case#Special_case_styles 72 | [6]: https://en.wikipedia.org/wiki/Snake_case 73 | -------------------------------------------------------------------------------- /rules/paragraphs.md: -------------------------------------------------------------------------------- 1 | ## No Indentation 2 | 3 | Never indent the content of paragraphs. 4 | 5 | > remark-lint: [no-paragraph-content-indent][1] 6 | 7 | ###### Examples 8 | 9 | Note: The `·` character represents a whitespace. 10 | 11 | ⇣ **Incorrect** code for this rule: 12 | 13 | 14 | 15 | ```markdown 16 | ·The winter has sparkling and frozen elements! 17 | ·Many snowflakes are falling down. 18 | ``` 19 | 20 | ```markdown 21 | ······The winter has sparkling and frozen elements! 22 | ········Many snowflakes are falling down. 23 | ``` 24 | 25 | 26 | 27 | ⇡ **Correct** code for this rule: 28 | 29 | ```markdown 30 | The winter has sparkling and frozen elements! 31 | Many snowflakes are falling down. 32 | ``` 33 | 34 | [1]: https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-paragraph-content-indent 35 | -------------------------------------------------------------------------------- /rules/raw-html.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | > Please prefer standard Markdown syntax wherever possible and only use HTML if you can't accomplish the goal with the Markdown syntax! Raw HTML reduces the readability and portability, but can improve the design, layout and overview of rendered documents. 4 | > Anyway, consider to **use raw HTML sparingly and only if necessary**! 5 | 6 | ## Aligned Content 7 | 8 | Use a [HTML paragraph `

`][8] tag with the `align` attribute. Although if the [HTML 5 specification][10] states that the `align` attribute is obsolete it is the only possible solution because the [`style` tag is disallowed raw HTML][1] within Markdown so the CSS [`text-align`][3] property can not be used. 9 | 10 | Aligning content can improve the design and layout e.g. images and project logos by either using `center`, `left` or `right` as value for the `align` attribute. 11 | 12 | ###### Examples 13 | 14 | ⇣ **Incorrect** code for this rule: 15 | 16 | 17 | 18 | ```markdown 19 |

The winter is winter is sparkling and frozen!

20 | ``` 21 | 22 | 23 | 24 | ⇡ **Correct** code for this rule: 25 | 26 | ```markdown 27 |

The winter is winter is sparkling and frozen!

28 | ``` 29 | 30 | ## Inline Content 31 | 32 | Use a [HTML ``][7] to add inline content like images or icons for better visualization. This allows to use e.g. a favicon of a website and define its size with the `width` and `height` attributes using either a pixel or percentage (withdouble quotes for the `%` character) value. 33 | 34 | Although MDN states that the `width` and `height` attributes are deprecated and [advises to replace them with the corresponding CSS attributes][5], but it is the only possible solution because the [`style` tag is disallowed raw HTML][1] within Markdown so the CSS [`width`][4] and [`height`][2] property can not be used. 35 | 36 | ###### Examples 37 | 38 | ⇣ **Incorrect** code for this rule: 39 | 40 | 41 | 42 | ```markdown 43 | Sparkling snowflakes falling down in the winter! 44 | ``` 45 | 46 | No way to define the size: 47 | 48 | ```markdown 49 | Sparkling ![falling snowflakes](https://raw.githubusercontent.com/nordtheme/assets/main/static/images/artworks/arctic/nature/dark/snowfall.svg?sanitize=true) snowflakes falling down in the winter! 50 | ``` 51 | 52 | 53 | 54 | ⇡ **Correct** code for this rule: 55 | 56 | ```markdown 57 | Sparkling snowflakes falling down in the winter! 58 | ``` 59 | 60 | ## Collapsed Content 61 | 62 | Use the HTML [`
`][6] tag to add collapsible content. It creates a disclosure widget in which information is visible only when the widget is toggled into an _open_ state. A summary or label can be provided using the [``][9] element. 63 | 64 | This can be useful to e.g. hide large table of contents or code blocks that might disturb the focus or force the reader to scroll long sites. 65 | 66 | ###### Examples 67 | 68 | ⇡ **Correct** code for this rule: 69 | 70 | ```markdown 71 |
72 | Winter 73 |

Sparkling and frozen!

74 |
75 | ``` 76 | 77 | [1]: https://github.github.com/gfm/#disallowed-raw-html-extension- 78 | [2]: https://developer.mozilla.org/en-US/docs/Web/CSS/height 79 | [3]: https://developer.mozilla.org/en-US/docs/Web/CSS/text-align 80 | [4]: https://developer.mozilla.org/en-US/docs/Web/CSS/width 81 | [5]: https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes 82 | [6]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/details 83 | [7]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img 84 | [8]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/p 85 | [9]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/summary 86 | [10]: https://html.spec.whatwg.org/multipage/grouping-content.html#the-p-element 87 | -------------------------------------------------------------------------------- /rules/strings.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | ## Quotes 4 | 5 | Use double quotes `""` for strings: 6 | 7 | - **Double quotes can be used for inline HTML**. 8 | - **Consistency to other style guides**. Double quotes are used by many code styles like [JavaScript][2]. 9 | - **Parallelism to the natural language**. Double quotes are used to identify a passage of quoted text. When using single quotes, the reader may misinterpret it as a contraction. The other meaning of a passage of text surrounded by the `'` indicates the _colloquial_ meaning. It makes sense to stay consistent with pre-existing languages, and this may likely ease the learning and interpretation of code. 10 | 11 | > remark-lint: [link-title-style][1] 12 | 13 | ###### Examples 14 | 15 | ⇣ **Incorrect** code for this rule: 16 | 17 | 18 | 19 | ```markdown 20 | 'The winter is sparkling and frozen!' 21 | ``` 22 | 23 | 24 | 25 | ⇡ **Correct** code for this rule: 26 | 27 | ```markdown 28 | "The winter is sparkling and frozen!" 29 | ``` 30 | 31 | ## Line Length 32 | 33 | Strings that cause the line to go over 100 characters should not be written across multiple lines using string concatenation. Broken strings are painful to work with and make code less searchable. 34 | 35 | ###### Examples 36 | 37 | ⇣ **Incorrect** code for this rule: 38 | 39 | 40 | 41 | ```markdown 42 | "Cupcake ipsum candy pudding soufflé chocolate. Croissant \ 43 | muffin biscuit brownie caramels pudding toffee pie. Tiramisu cookie ice cream \ 44 | cake dessert icing donut." 45 | ``` 46 | 47 | ```markdown 48 | "Cupcake ipsum candy pudding soufflé chocolate. Croissant" + 49 | "muffin biscuit brownie caramels pudding toffee pie. Tiramisu cookie ice cream " + 50 | "cake dessert icing donut." 51 | ``` 52 | 53 | 54 | 55 | ⇡ **Correct** code for this rule: 56 | 57 | ```markdown 58 | "Cupcake ipsum candy pudding soufflé chocolate. Croissant muffin biscuit brownie caramels pudding toffee pie. Tiramisu cookie ice cream cake dessert icing donut." 59 | ``` 60 | 61 | [1]: https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-link-title-style 62 | [2]: https://github.com/svengreb/styleguide-javascript 63 | -------------------------------------------------------------------------------- /rules/tables.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | ## Prefer Lists 4 | 5 | Prefer [lists][4] and only use tables for small, non-complex and single line content. 6 | Complex, large tables are difficult to read in source and most importantly, a pain to modify, indent and also read later e.g. when using 7 | 8 | - line breaks within rows 9 | - very long sentences that must be wrapped 10 | - document elements like [code blocks][2] or [blockquotes][1] 11 | - [inline links][3] with long URLs 12 | 13 | Lists and subheadings usually suffice to present the same information in a slightly less compact, though much more edit-friendly and more elegant way. 14 | 15 | ###### Examples 16 | 17 | ⇣ **Incorrect** code for this rule: 18 | 19 | 20 | 21 | ```markdown 22 | | Element | URL | Note | Attributes | Types | 23 | | :------: | --- | ---- | ---------- | ----- | 24 | | Snow | [Wikipedia](http://this-is-a-very-long-url-for-information-about-snowflakes.com) | It falls down in winter! | soft, damp, crystal-like | powder snow, wet snow, lazy snow | 25 | | Frost | [Wikipedia](http://this-is-a-very-long-url-for-information-about-frost-and-the-winter-season.com) | Sparkling and frozen! | cold, grainy | permafrost, hard rime, ground frost | 26 | ``` 27 | 28 | 29 | 30 | ⇡ **Correct** code for this rule: 31 | 32 | ```markdown 33 | ## Elements 34 | 35 | ### Snow 36 | 37 | - [Wikipedia][wikipedia-snow] 38 | - It falls down in winter! 39 | - Attributes: 40 | - soft 41 | - damp 42 | - crystal-like 43 | - Types: 44 | - powder snow 45 | - wet snow 46 | - lazy snow 47 | 48 | ## Frost 49 | 50 | - [Knowledge Base][knowledge_base-frost] 51 | - Sparkling and frozen! 52 | - Attributes: 53 | - cold 54 | - grainy 55 | - Types: 56 | - permafrost 57 | - hard rime 58 | - ground frost 59 | 60 | [knowledge_base-frost]: http://this-is-a-very-long-url-for-information-about-frost-and-the-winter-season.com 61 | [wikipedia-snow]: http://this-is-a-very-long-url-for-information-about-snow.com 62 | ``` 63 | 64 | For small, non-complex and single line content: 65 | 66 | ```markdown 67 | | Element | Attribute | 68 | | ------- | --------- | 69 | | Frost | Sparkling | 70 | | Ice | Frozen | 71 | ``` 72 | 73 | ## Empty Lines Before And After 74 | 75 | Always surround tables by a single empty line except at the beginning of the file. 76 | 77 | ###### Examples 78 | 79 | ⇣ **Incorrect** code for this rule: 80 | 81 | 82 | 83 | ```markdown 84 | ... snowflakes are falling. 85 | | Element | Attribute | 86 | | ------- | --------- | 87 | | Snow | Falling | 88 | | Frost | Sparkling | 89 | | Ice | Cold | 90 | Sparkling and frozen... 91 | ``` 92 | 93 | ```markdown 94 | ... snowflakes are falling. 95 | 96 | 97 | | Element | Attribute | 98 | | ------- | --------- | 99 | | Snow | Falling | 100 | | Frost | Sparkling | 101 | | Ice | Cold | 102 | 103 | 104 | Sparkling and frozen... 105 | ``` 106 | 107 | 108 | 109 | ⇡ **Correct** code for this rule: 110 | 111 | ```markdown 112 | ... snowflakes are falling. 113 | 114 | | Element | Attribute | 115 | | ------- | --------- | 116 | | Snow | Falling | 117 | | Frost | Sparkling | 118 | | Ice | Cold | 119 | 120 | Sparkling and frozen... 121 | ``` 122 | 123 | ## Content Spacing 124 | 125 | Surround the content of headers and cells with at least one (1) single whitespace. 126 | 127 | ###### Examples 128 | 129 | ⇣ **Incorrect** code for this rule: 130 | 131 | 132 | 133 | ```markdown 134 | |Element|Attribute| 135 | | ----- | ------- | 136 | |Frost|Sparkling | 137 | ``` 138 | 139 | ```markdown 140 | | Element | Attribute | 141 | | ------- | --------- | 142 | | Frost | Sparkling | 143 | ``` 144 | 145 | 146 | 147 | ⇡ **Correct** code for this rule: 148 | 149 | ```markdown 150 | | Element | Attribute | 151 | | ------- | --------- | 152 | | Frost | Sparkling | 153 | ``` 154 | 155 | ## Header Delimiter Row Spacing 156 | 157 | The delimiter row must only consist of cells whose only content are hyphens (`-`) surrounded by a single whitespace, and optionally, a leading or trailing colon (`:`), or both, to indicate left, right, or center alignment respectively. 158 | 159 | > remark-lint: [table-cell-padding][6] and [table-pipe-alignment][7] 160 | 161 | ###### Examples 162 | 163 | ⇣ **Incorrect** code for this rule: 164 | 165 | 166 | 167 | ```markdown 168 | | Element | Attribute | 169 | |---------|-----------| 170 | | Frost | Sparkling | 171 | ``` 172 | 173 | ```markdown 174 | | Element | Attribute | 175 | |---------|-----------| 176 | | Frost | Sparkling | 177 | ``` 178 | 179 | ```markdown 180 | | Element | Attribute | 181 | |--- | --- | 182 | | Frost | Sparkling | 183 | ``` 184 | 185 | ```markdown 186 | | Element | Attribute | 187 | |:-------:|----------:| 188 | | Frost | Sparkling | 189 | ``` 190 | 191 | 192 | 193 | ⇡ **Correct** code for this rule: 194 | 195 | ```markdown 196 | | Element | Attribute | 197 | | ------- | --------- | 198 | | Frost | Sparkling | 199 | ``` 200 | 201 | ```markdown 202 | | Element | Attribute | 203 | | :-----: | --------: | 204 | | Frost | Sparkling | 205 | ``` 206 | 207 | ## Minimum Column Width 208 | 209 | The minimum column width is determined by the cell with the longest content in the column. 210 | 211 | > remark-lint: [table-pipe-alignment][7] 212 | 213 | ###### Examples 214 | 215 | ⇣ **Incorrect** code for this rule: 216 | 217 | 218 | 219 | ```markdown 220 | | Element | Attribute | 221 | | ------- | --------- | 222 | | Frost | Sparkling and frozen! | 223 | | Snow | Falling down! | 224 | ``` 225 | 226 | 227 | 228 | ⇡ **Correct** code for this rule: 229 | 230 | ```markdown 231 | | Element | Attribute | 232 | | ------- | --------------------- | 233 | | Frost | Sparkling and frozen! | 234 | | Snow | Falling down! | 235 | ``` 236 | 237 | ## Alignment 238 | 239 | Always align tables vertically. 240 | 241 | Unaligned tables are easier to write, but tables with aligned border pipes (`|`) are more readable. Preceding pipes make it easier to determine where a table starts and ends. Trailing pipes make it look better because of symmetry. 242 | 243 | > remark-lint: [table-pipes][8] 244 | 245 | ###### Examples 246 | 247 | ⇣ **Incorrect** code for this rule: 248 | 249 | 250 | 251 | ```markdown 252 | | Element | Attribute | 253 | | --- | --- | 254 | | Frost | Sparkling and frozen! | 255 | | Snow | Falling down! | 256 | | Ice | Everything is smooth and slippery in winter! | 257 | ``` 258 | 259 | 260 | 261 | ⇡ **Correct** code for this rule: 262 | 263 | ```markdown 264 | | Element | Attribute | 265 | | ------- | -------------------------------------------- | 266 | | Frost | Sparkling and frozen! | 267 | | Snow | Falling down! | 268 | | Ice | Everything is smooth and slippery in winter! | 269 | ``` 270 | 271 | ## No Indentation 272 | 273 | Never indent tables. 274 | 275 | > remark-lint: [no-table-indentation][5] 276 | 277 | ###### Examples 278 | 279 | Note: The `·` character represents a whitespace. 280 | 281 | ⇣ **Incorrect** code for this rule: 282 | 283 | 284 | 285 | ```markdown 286 | ·| Element | Attribute | 287 | ·| ------- | --------- | 288 | ·| Frost | Sparkling and frozen! | 289 | ·| Snow | Falling down! | 290 | ``` 291 | 292 | ```markdown 293 | ··| Element | Attribute | 294 | ··| ------- | --------- | 295 | ··| Frost | Sparkling and frozen! | 296 | ··| Snow | Falling down! | 297 | ``` 298 | 299 | ```markdown 300 | ·········| Element | Attribute | 301 | ·········| ------- | --------- | 302 | ·········| Frost | Sparkling and frozen! | 303 | ·········| Snow | Falling down! | 304 | ``` 305 | 306 | 307 | 308 | ⇡ **Correct** code for this rule: 309 | 310 | ```markdown 311 | | Element | Attribute | 312 | | ------- | --------------------- | 313 | | Frost | Sparkling and frozen! | 314 | | Snow | Falling down! | 315 | ``` 316 | 317 | [1]: https://github.com/svengreb/styleguide-markdown/blob/main/rules/blockquotes.md 318 | [2]: https://github.com/svengreb/styleguide-markdown/blob/main/rules/code.md#blocks 319 | [3]: https://github.com/svengreb/styleguide-markdown/blob/main/rules/links.md#inline 320 | [4]: https://github.com/svengreb/styleguide-markdown/blob/main/rules/lists.md 321 | [5]: https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-table-indentation 322 | [6]: https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-table-cell-padding 323 | [7]: https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-table-pipe-alignment 324 | [8]: https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-table-pipes 325 | -------------------------------------------------------------------------------- /rules/whitespace.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | ## Indentation Character 4 | 5 | Always use spaces characters where two (2) spaces are used for indentation. **The usage of tab characters is disallowed**. A tab could be a different number of columns depending on the environment, but a space is always one column. Adhering to this rule increases the code readability and maintainability significantly. 6 | 7 | > remark-lint: [no-tabs][10] 8 | 9 | ###### Examples 10 | 11 | Note: The `»` character represents a tab. 12 | 13 | ⇣ **Incorrect** code for this rule: 14 | 15 | 16 | 17 | ```markdown 18 | The winter has sparkling and frozen elements! 19 | » This line contains a tab character. 20 | } 21 | ``` 22 | 23 | ```markdown 24 | The winter has sparkling and frozen elements! 25 | This line contains 4 space characters. 26 | } 27 | ``` 28 | 29 | ```markdown 30 | The winter has sparkling and frozen elements! 31 | This line contains only 1 space character. 32 | } 33 | ``` 34 | 35 | ⇡ **Correct** code for this rule: 36 | 37 | ```markdown 38 | The winter has sparkling and frozen elements! 39 | This line contains 2 space characters. 40 | } 41 | ``` 42 | 43 | 44 | 45 | ## Newline 46 | 47 | End files with a single [newline][16] character. Always use unix-style _LF_ linebreaks (`\n`, denoted as `␊`) and avoid the usage of Microsoft Windows _CRLF_ characters (`\r\n`, denoted as `␍␊`). 48 | 49 | > remark-lint: [final-newline][4] and [linebreak-style][6] 50 | 51 | ###### Examples 52 | 53 | Note: The `¬` character represents a line break. 54 | 55 | ⇣ **Incorrect** code for this rule: 56 | 57 | 58 | 59 | ```markdown 60 | The winter has sparkling and frozen elements! 61 | Many snowflakes are falling down. 62 | ``` 63 | 64 | ```markdown 65 | The winter has sparkling and frozen elements! 66 | Many snowflakes are falling down.¬ 67 | ¬ 68 | 69 | ``` 70 | 71 | ⇡ **Correct** code for this rule: 72 | 73 | ```markdown 74 | The winter has sparkling and frozen elements! 75 | Many snowflakes are falling down.¬ 76 | 77 | ``` 78 | 79 | 80 | 81 | ###### References 82 | 83 | - [Wikipedia: _Control Character_][14] 84 | 85 | ## Before Blocks 86 | 87 | Always add one (1) blank line before blocks except the first line of the file. 88 | 89 | > remark-lint: [no-consecutive-blank-lines][8] and [no-missing-blank-lines][9] 90 | 91 | ###### Examples 92 | 93 | Note: The `¬` character represents a line break. 94 | 95 | ⇣ **Incorrect** code for this rule: 96 | 97 | 98 | 99 | ```markdown 100 | The winter has sparkling and frozen elements! 101 | Many snowflakes are falling down. 102 | ``` 103 | 104 | 105 | 106 | ⇡ **Correct** code for this rule: 107 | 108 | ```markdown 109 | The winter has sparkling and frozen elements! 110 | ¬ 111 | Many snowflakes are falling down. 112 | ``` 113 | 114 | ## After Sentences 115 | 116 | Use a single space after sentences. 117 | 118 | ###### Examples 119 | 120 | ⇣ **Incorrect** code for this rule: 121 | 122 | 123 | 124 | ```markdown 125 | Many snowflakes are falling down. The winter has sparkling and frozen elements! 126 | ``` 127 | 128 | ```markdown 129 | Many snowflakes are falling down.The winter has sparkling and frozen elements! 130 | ``` 131 | 132 | 133 | 134 | ⇡ **Correct** code for this rule: 135 | 136 | ```markdown 137 | Many snowflakes are falling down. The winter has sparkling and frozen elements! 138 | ``` 139 | 140 | ## Maximum Line Length 141 | 142 | In contrast to source code, where lines contain statements that can be almost always be broken up or indented, this rule can not be applied to flowing text. The author should be able to write sentences and text blocks without worrying about the line length. 143 | 144 | Other style guides suggest to use line breaks after the character limit has been reached, but this will lead to deformed rendered output since GFM supports [soft line breaks][2]. Therefore, this guide advices to **avoid using a character limit per line for flowing text**, but try to use a maximum line length of 160 characters (including whitespaces) for all other document elements. 145 | 146 | Instead of enforcing a maximum line length, users should use [soft line wrapping][15]: 147 | 148 | - **Soft wrapping allows line lengths to visually adjust automatically with adjustments to the width of the user's window** or margin settings - This is a standard feature of all modern text editors like [VSCode][13] or [Atom][1], IDEs like [JetBrains IntelliJ IDEA][3], word processors, and email clients like [Thunderbird][12]. 149 | - **Using hard wrap inserts actual line breaks in the text at wrap points causing the Markdown to not look like the rendered output** - With soft wrapping the actual text is still on the same line but will be rendered by the application like it's divided into several lines. This **increases the readability** significantly and leads to the same visual result as if a maximum line length with hard line breaks for flowing text would have been used. 150 | - **Less writer effort** - The author can focus on the content instead of formatting. 151 | 152 | Note that the [rule for long strings][11] is related to this rule, and should not be broken up. 153 | 154 | > remark-lint: [maximum-line-length][7] 155 | 156 | ###### Examples 157 | 158 | ⇣ **Incorrect** code for this rule: 159 | 160 | 161 | 162 | ````markdown 163 | > The winter and all of its fascinating, sparkling and 164 | frozen elements and lively, diverse and beautiful wildlife. 165 | 166 | Many snowflakes are falling down. The winter has sparkling and frozen elements! It is home 167 | for many beautiful animals like snowy owls, 168 | arctic foxes, and grizzly bears. 169 | 170 | ```js 171 | const season = winter && winter.elements && winter.elements.snow && winter.elements.snow.state && winter.elements.snow.state.temperature && winter.elements.snow.state.temperature.celsius; 172 | ``` 173 | ```` 174 | 175 | 176 | 177 | ⇡ **Correct** code for this rule: 178 | 179 | ````markdown 180 | > The winter and all of its fascinating, sparkling and frozen elements and lively, diverse and beautiful wildlife. 181 | 182 | Many snowflakes are falling down. The winter has sparkling and frozen elements! It is home for many beautiful animals like snowy owls, arctic foxes, and grizzly bears. 183 | 184 | ```js 185 | const season = 186 | winter && 187 | winter.elements && 188 | winter.elements.snow && 189 | winter.elements.snow.state && 190 | winter.elements.snow.state.temperature && 191 | winter.elements.snow.state.temperature.celsius; 192 | ``` 193 | ```` 194 | 195 | ## Trailing 196 | 197 | Don't use trailing whitespace to generate a line break, use flowing text style or a blank line to create a new paragraph. 198 | 199 | > remark-lint: [hard-break-spaces][5] 200 | 201 | ###### Examples 202 | 203 | Note: The `·` character represents a whitespace and the `¬` character represents a line break. 204 | 205 | ⇣ **Incorrect** code for this rule: 206 | 207 | 208 | 209 | ```markdown 210 | The winter has sparkling and frozen elements!··¬ 211 | Many snowflakes are falling down. 212 | ``` 213 | 214 | ```markdown 215 | The winter has sparkling and frozen elements!¬ 216 | Many snowflakes are falling down. 217 | ``` 218 | 219 | 220 | 221 | ⇡ **Correct** code for this rule: 222 | 223 | ```markdown 224 | The winter has sparkling and frozen elements! Many snowflakes are falling down. 225 | ``` 226 | 227 | ```markdown 228 | The winter has sparkling and frozen elements!¬ 229 | 230 | Many snowflakes are falling down. 231 | ``` 232 | 233 | [1]: http://flight-manual.atom.io/getting-started/sections/atom-basics/#soft-wrap 234 | [2]: https://github.github.com/gfm/#soft-line-breaks 235 | [3]: https://www.jetbrains.com/help/idea/using-code-editor.html#13ac7976 236 | [4]: https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-final-newline 237 | [5]: https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-hard-break-spaces 238 | [6]: https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-linebreak-style 239 | [7]: https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-maximum-line-length 240 | [8]: https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-consecutive-blank-lines 241 | [9]: https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-missing-blank-lines 242 | [10]: https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-tabs 243 | [11]: https://github.com/svengreb/styleguide-markdown/blob/main/rules/strings.md#line-length 244 | [12]: https://www.thunderbird.net 245 | [13]: https://code.visualstudio.com/docs/editor/codebasics#_common-questions 246 | [14]: https://en.wikipedia.org/wiki/Control_character 247 | [15]: https://en.wikipedia.org/wiki/Line_wrap_and_word_wrap 248 | [16]: https://en.wikipedia.org/wiki/Newline 249 | --------------------------------------------------------------------------------