The Arctic Ice Studio Markdown code style.
- - - - - - - -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. - -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. - -### Getting Started - -The [project documentation][docs] contains chapters to learn about -the [comprehensive base rule set][docs-rules] with support for [GitHub Flavored Markdown][gfm] which is based on the [CommonMark][commonmark] specification. It includes rules for all document elements like e.g. [code blocks][docs-rules-code-blocks], [headings][docs-rules-headings] or [lists][docs-rules-lists], defines [naming conventions][docs-rules-naming-conventions] and best practices for [whitespaces][docs-rules-whitespaces], [Raw HTML][docs-rules-raw-html], [emphasizing][docs-rules-emphasis] and [strings][docs-rules-strings]. - -The development chapters contain information about the [requirements][docs-dev-requirements] and [how to build][docs-dev-building] the style guide documentation. - -### Remark Configurations - -To follow the rules in a project and ensure that your code matches this style guide use the official extensible code linter rule preset [@arcticicestudio/remark-preset-lint][gh-tree-pkg-remark-preset-lint] for [remark-lint][gh-remarkjs/remark-lint], a plugin for [remark][]. - -### Contributing - -Read the [contributing guide][docs-dev-contributing] to learn about the development process and how to propose [enhancement suggestions][docs-dev-contributing-enhancements] and [report bugs][docs-dev-contributing-bug-reports], how to [submit pull requests][docs-dev-contributing-pr] and the project‘s [style guides][docs-dev-contributing-styleguides], [branch organization][docs-dev-contributing-branch-org] and [versioning][docs-dev-contributing-versioning] model. - -The guide also includes information about [minimal, complete, and verifiable examples][docs-dev-contributing-mcve] and other ways to contribute to the project like [improving existing issues][docs-dev-contributing-other-improve-issues] and [giving feedback on issues and pull requests][docs-dev-contributing-other-feedback]. - - - -Copyright © 2018-present Arctic Ice Studio and Sven Greb
- - - -[commonmark]: http://commonmark.org -[docs-dev-building]: https://arcticicestudio.github.io/styleguide-markdown/development/building.html -[docs-dev-contributing-branch-org]: https://arcticicestudio.github.io/styleguide-markdown/development/contributing.html#branch-organization -[docs-dev-contributing-bug-reports]: https://arcticicestudio.github.io/styleguide-markdown/development/contributing.html#bug-reports -[docs-dev-contributing-enhancements]: https://arcticicestudio.github.io/styleguide-markdown/development/contributing.html#enhancement-suggestions -[docs-dev-contributing-mcve]: https://arcticicestudio.github.io/styleguide-markdown/development/contributing.html#mcve -[docs-dev-contributing-other-feedback]: https://arcticicestudio.github.io/styleguide-markdown/development/contributing.html#give-feedback-on-issues-and-pull-requests -[docs-dev-contributing-other-improve-issues]: https://arcticicestudio.github.io/styleguide-markdown/development/contributing.html#improve-issues -[docs-dev-contributing-pr]: https://arcticicestudio.github.io/styleguide-markdown/development/contributing.html#pull-requests -[docs-dev-contributing-styleguides]: https://arcticicestudio.github.io/styleguide-markdown/development/contributing.html#style-guides -[docs-dev-contributing-versioning]: https://arcticicestudio.github.io/styleguide-markdown/development/contributing.html#versioning -[docs-dev-contributing]: https://arcticicestudio.github.io/styleguide-markdown/development/contributing.html -[docs-dev-requirements]: https://arcticicestudio.github.io/styleguide-markdown/development/requirements.html -[docs-rules-code-blocks]: https://arcticicestudio.github.io/styleguide-markdown/rules/code.html#blocks -[docs-rules-emphasis]: https://arcticicestudio.github.io/styleguide-markdown/rules/emphasis.html -[docs-rules-headings]: https://arcticicestudio.github.io/styleguide-markdown/rules/headings.html -[docs-rules-lists]: https://arcticicestudio.github.io/styleguide-markdown/rules/lists.html -[docs-rules-naming-conventions]: https://arcticicestudio.github.io/styleguide-markdown/rules/naming-conventions.html -[docs-rules-raw-html]: https://arcticicestudio.github.io/styleguide-markdown/rules/raw-html.html -[docs-rules-strings]: https://arcticicestudio.github.io/styleguide-markdown/rules/strings.html -[docs-rules-whitespaces]: https://arcticicestudio.github.io/styleguide-markdown/rules/whitespaces.html -[docs-rules]: https://arcticicestudio.github.io/styleguide-markdown/rules/index.html -[docs]: https://arcticicestudio.github.io/styleguide-markdown -[gfm]: https://github.github.com/gfm -[gh-remarkjs/remark-lint]: https://github.com/remarkjs/remark-lint -[gh-tree-pkg-remark-preset-lint]: https://github.com/arcticicestudio/styleguide-markdown/tree/main/packages/@arcticicestudio/remark-preset-lint -[remark]: https://remark.js.org +{% include "git+https://github.com/arcticicestudio/styleguide-markdown.git/README.md" %} diff --git a/src/development/requirements.md b/src/development/requirements.md index 8941368..50534db 100644 --- a/src/development/requirements.md +++ b/src/development/requirements.md @@ -4,7 +4,7 @@ Styleguide Markdown is build with [Node.js][nodejs] which is required to build s ### npm -[npm][npm] is used as package manager which comes prebundled with Node.js and can be used from the CLI. +[npm][] is used as package manager which comes pre-bundled with Node.js and can be used from the CLI. [nodejs]: https://nodejs.org/en/download/releases [npm]: https://npmjs.com diff --git a/src/rules/accessibility-a11y.md b/src/rules/accessibility-a11y.md index ee38354..1a6169a 100644 --- a/src/rules/accessibility-a11y.md +++ b/src/rules/accessibility-a11y.md @@ -1,4 +1,4 @@ -This chapter provides rules to improve the accessibility as documented by the [A11Y][a11y] project. +This chapter provides rules to improve the accessibility as documented by the [A11Y][] project. ## Alternative Text diff --git a/src/rules/code.md b/src/rules/code.md index a5ea8aa..2ee1e17 100644 --- a/src/rules/code.md +++ b/src/rules/code.md @@ -241,9 +241,9 @@ export default Snow; Don't use it for -- **project or proper names** - e.g [React][react], [GCC][gcc], [Node.js][nodejs], [Golang][golang] or [Rust][rustlang] -- **libraries** - e.g. [libgit2][], [libc][crates-libc] (Rust Bindings), [glibc][], [glib2][] or [jackson-databind][bintray-jackson-databind] (Java) -- **packages and modules** - e.g. [react-dom][npm-react-dom], [snowsaw][pypi-snowsaw] or [archlinux-keyring][archlinux-keyring] +- **project or proper names** - e.g [React][], [GCC][], [Node.js][nodejs], [Go][] or [Rust][]. +- **libraries** - e.g. [libgit2][], [libc][crates-libc] (Rust Bindings), [glibc][], [glib2][] or [jackson-databind][bintray-jackson-databind] (Java). +- **packages and modules** - e.g. [react-dom][npm-react-dom], [snowsaw][pypi-snowsaw] or [archlinux-keyring][]. [archlinux-keyring]: https://www.archlinux.org/packages/core/any/archlinux-keyring [bintray-jackson-databind]: https://bintray.com/bintray/jcenter/com.fasterxml.jackson.core%3Ajackson-databind @@ -253,7 +253,7 @@ Don't use it for [gh-help-gfm_code_syntax_highlighting]: https://help.github.com/articles/creating-and-highlighting-code-blocks/#syntax-highlighting [glib2]: https://wiki.gnome.org/Projects/GLib [glibc]: https://www.gnu.org/software/libc -[golang]: https://golang.org +[go]: https://golang.org [libgit2]: https://libgit2.github.com [nodejs]: https://nodejs.org [npm-react-dom]: https://www.npmjs.com/package/react-dom @@ -263,4 +263,4 @@ Don't use it for [remark-lint-fenced-code-flag]: https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-fenced-code-flag [remark-lint-fenced-code-marker]: https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-fenced-code-marker [remark-lint-no-shell-dollars]: https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-shell-dollars -[rustlang]: https://www.rust-lang.org +[rust]: https://www.rust-lang.org diff --git a/src/rules/images.md b/src/rules/images.md index 1906b31..99f951d 100644 --- a/src/rules/images.md +++ b/src/rules/images.md @@ -24,6 +24,42 @@ Prefer absolute URLs instead of relative ones to improve the portability of the [snowflake]: https://raw.githubusercontent.com/arcticicestudio/styleguide-markdown/main/src/assets/snowflake.png ``` +## Collapsed Reference Links + +Full references (such as `[Winter][winter]`) can also be written as a collapsed reference (`[Winter][]`) if normalizing the reference text yields the label. + +> remark-lint: [no-unneeded-full-reference-image][remark-lint-no-unneeded-full-reference-image] + +###### Examples + +⇣ **Incorrect** code for this rule: + + + +```markdown +![arctic][arctic] +![snowflake][snowflake] +![winter][winter] + +[arctic]: https://arctic-is-beautiful.io/north-pole.png +[snowflake]: https://snow-is-falling-down.io/snowflake.png +[winter]: https://the-winter-is-sparkling-and-frozen.io/winter.png +``` + + + +⇡ **Correct** code for this rule: + +```markdown +![arctic][north-pole] +![snowflake][] +![winter][] + +[north-pole]: https://arctic-is-beautiful.io/north-pole.png +[snowflake]: https://snow-is-falling-down.io/snowflake.png +[winter]: https://the-winter-is-sparkling-and-frozen.io/winter.png +``` + ## Badges 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][npm] or [Rust crates][crates.io]. @@ -43,3 +79,4 @@ Use badges to represent simple information like latest version number and URL to [crates.io]: https://crates.io [npm]: https://npmjs.com +[remark-lint-no-unneeded-full-reference-image]: https://github.com/remarkjs/remark-lint/tree/main/packages/remark-no-unneeded-full-reference-image diff --git a/src/rules/links.md b/src/rules/links.md index 4f42b2f..98e8bd6 100644 --- a/src/rules/links.md +++ b/src/rules/links.md @@ -431,6 +431,74 @@ The [Winter][winter] is sparkling and frozen! [winter]: https://the-winter-is-sparkling-and-frozen.io ``` +## No Duplicates + +Prevent definitions that use the same URL. + +> remark-lint: [no-duplicate-defined-urls][remark-lint-no-duplicate-defined-urls] + +###### Examples + +⇣ **Incorrect** code for this rule: + + + +```markdown +[arctic][] +[north-pole][] + +[arctic]: https://arctic-is-beautiful.io +[north-pole]: https://arctic-is-beautiful.io +``` + + + +⇡ **Correct** code for this rule: + +```markdown +[arctic][] +[north-pole][] + +[arctic]: https://arctic-is-beautiful.io +[north-pole]: https://frozen-nordic-arctic.io +``` + +## Collapsed References + +Full references (such as `[Winter][winter]`) can also be written as a collapsed reference (`[Winter][]`) if normalizing the reference text yields the label. + +> remark-lint: [no-unneeded-full-reference-link][remark-lint-no-unneeded-full-reference-link] + +###### Examples + +⇣ **Incorrect** code for this rule: + + + +```markdown +[arctic][arctic] +[snowflake][snowflake] +[Winter][winter] + +[arctic]: https://arctic-is-beautiful.io +[snowflake]: https://snow-is-falling-down.io +[winter]: https://the-winter-is-sparkling-and-frozen.io +``` + + + +⇡ **Correct** code for this rule: + +```markdown +[arctic][north-pole] +[snowflake][] +[Winter][] + +[north-pole]: https://arctic-is-beautiful.io +[snowflake]: https://snow-is-falling-down.io +[winter]: https://the-winter-is-sparkling-and-frozen.io +``` + ## Autolink Protocol Always add a valid protocol when using [autolinks][gfm-spec-links-autolinks]. @@ -577,10 +645,12 @@ The [winter](https://the-winter-is-sparkling-and-frozen.io) is sparkling and fro [remark-lint-definition-spacing]: https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-definition-spacing [remark-lint-final-definition]: https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-final-definition [remark-lint-no-auto-link-without-protocol]: https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-auto-link-without-protocol +[remark-lint-no-duplicate-defined-urls]: https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-duplicate-defined-urls [remark-lint-no-duplicate-definitions]: https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-duplicate-definitions [remark-lint-no-empty-url]: https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-empty-url [remark-lint-no-inline-padding]: https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-inline-padding [remark-lint-no-reference-like-url]: https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-reference-like-url [remark-lint-no-undefined-references]: https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-undefined-references +[remark-lint-no-unneeded-full-reference-link]: https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-unneeded-full-reference-link [remark-lint-no-unused-definitions]: https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-unused-definitions [w3-html5-spec-navigate_fragment_identifier]: https://www.w3.org/TR/html52/browsers.html#navigating-to-a-fragment-identifier diff --git a/src/rules/tables.md b/src/rules/tables.md index ad2f619..21008bd 100644 --- a/src/rules/tables.md +++ b/src/rules/tables.md @@ -1,11 +1,11 @@ ## Prefer Lists -Prefer [lists][lists] and only use tables for small, non-complex and single line content. +Prefer [lists][] and only use tables for small, non-complex and single line content. 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 - line breaks within rows - very long sentences that must be wrapped -- document elements like [code blocks][code-blocks] or [blockquotes][blockquotes] +- document elements like [code blocks][code-blocks] or [blockquotes][] - [inline links][links-inline] with long URLs Lists and subheadings usually suffice to present the same information in a slightly less compact, though much more edit-friendly and more elegant way. diff --git a/src/rules/whitespace.md b/src/rules/whitespace.md index 7071f29..715c230 100644 --- a/src/rules/whitespace.md +++ b/src/rules/whitespace.md @@ -143,7 +143,7 @@ Other style guides suggest to use line breaks after the character limit has been Instead of enforcing a maximum line length, users should use [soft line wrapping][wiki-line_wrap]: -- **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][vscode-doc-soft_wrap] or [Atom][atom-doc-soft_wrap], IDEs like [JetBrains IntelliJ IDEA][jetbrains-intellij-doc-soft_wrap], word processors, and email clients like [Thunderbird][thunderbird]. +- **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][vscode-doc-soft_wrap] or [Atom][atom-doc-soft_wrap], IDEs like [JetBrains IntelliJ IDEA][jetbrains-intellij-doc-soft_wrap], word processors, and email clients like [Thunderbird][]. - **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. - **Less writer effort** - The author can focus on the content instead of formatting.