From f5014a37fc5179e76db08e47a6d5eb4b1df3bea1 Mon Sep 17 00:00:00 2001 From: Arctic Ice Studio Date: Mon, 12 Feb 2018 17:44:22 +0100 Subject: [PATCH] Add base rules and documentations Includes the Circle CI config. GH-1 --- .circleci/config.yml | 31 ++ .github/ISSUE_TEMPLATE.md | 4 +- .remarkignore | 5 + .remarkrc.js | 17 + CONTRIBUTING.md | 4 +- README.md | 55 ++- package.json | 16 +- src/README.md | 67 ++++ src/SUMMARY.md | 134 ++++++++ src/assets/markdown-logo.png | Bin 0 -> 31980 bytes src/assets/snowflake.png | Bin 0 -> 1541 bytes src/book.json | 20 ++ src/development/building.md | 25 ++ src/development/changelog.md | 1 + src/development/code-of-conduct.md | 1 + src/development/contributing.md | 1 + src/development/credits.md | 43 +++ src/development/requirements.md | 10 + src/rules/accessibility-a11y.md | 25 ++ src/rules/blockquotes.md | 60 ++++ src/rules/code.md | 238 +++++++++++++ src/rules/comments.md | 13 + src/rules/emphasis.md | 151 +++++++++ src/rules/headings.md | 256 ++++++++++++++ src/rules/horizontal-rules.md | 101 ++++++ src/rules/images.md | 41 +++ src/rules/index.md | 13 + src/rules/links.md | 520 +++++++++++++++++++++++++++++ src/rules/lists.md | 422 +++++++++++++++++++++++ src/rules/naming-conventions.md | 62 ++++ src/rules/paragraphs.md | 30 ++ src/rules/raw-html.md | 75 +++++ src/rules/strings.md | 53 +++ src/rules/tables.md | 295 ++++++++++++++++ src/rules/whitespace.md | 222 ++++++++++++ src/styles/website.css | 35 ++ 36 files changed, 3040 insertions(+), 6 deletions(-) create mode 100644 .circleci/config.yml create mode 100644 .remarkignore create mode 100644 .remarkrc.js create mode 100644 src/README.md create mode 100644 src/SUMMARY.md create mode 100644 src/assets/markdown-logo.png create mode 100755 src/assets/snowflake.png create mode 100644 src/book.json create mode 100644 src/development/building.md create mode 100644 src/development/changelog.md create mode 100644 src/development/code-of-conduct.md create mode 100644 src/development/contributing.md create mode 100644 src/development/credits.md create mode 100644 src/development/requirements.md create mode 100644 src/rules/accessibility-a11y.md create mode 100644 src/rules/blockquotes.md create mode 100644 src/rules/code.md create mode 100644 src/rules/comments.md create mode 100644 src/rules/emphasis.md create mode 100644 src/rules/headings.md create mode 100644 src/rules/horizontal-rules.md create mode 100644 src/rules/images.md create mode 100644 src/rules/index.md create mode 100644 src/rules/links.md create mode 100644 src/rules/lists.md create mode 100644 src/rules/naming-conventions.md create mode 100644 src/rules/paragraphs.md create mode 100644 src/rules/raw-html.md create mode 100644 src/rules/strings.md create mode 100644 src/rules/tables.md create mode 100644 src/rules/whitespace.md create mode 100644 src/styles/website.css diff --git a/.circleci/config.yml b/.circleci/config.yml new file mode 100644 index 0000000..b0a08e1 --- /dev/null +++ b/.circleci/config.yml @@ -0,0 +1,31 @@ +# Copyright (c) 2018-present Arctic Ice Studio +# Copyright (c) 2018-present Sven Greb + +# Project: Styleguide Markdown +# Repository: https://github.com/arcticicestudio/styleguide-markdown +# License: MIT +# References: +# https://circleci.com/docs/2.0 +# https://circleci.com/docs/2.0/circleci-images/#nodejs + +version: 2 +jobs: + build: + docker: + - image: circleci/node:latest + steps: + - checkout + - run: + name: preprocess-clean-node-modules + command: rm -rf node_modules + - run: + name: preprocess-npm-install + command: npm install + - run: + name: lint + command: npm run lint + - run: + name: build-docs + command: npm run docs:build + - store_artifacts: + path: build/docs diff --git a/.github/ISSUE_TEMPLATE.md b/.github/ISSUE_TEMPLATE.md index 3b9f655..0542b10 100644 --- a/.github/ISSUE_TEMPLATE.md +++ b/.github/ISSUE_TEMPLATE.md @@ -51,7 +51,7 @@ What actually happens? Provide a [MCVE - The Minimal, Complete, and Verifiable Example](https://github.com/arcticicestudio/styleguide-markdown/blob/develop/CONTRIBUTING.md#mcve) -**This is a optional section, but it can drastically increase the speed at which this issue can be processed since it takes away the time-consuming reconstruction to reproduce the enhancement or bug.** +Note that **this is a optional section, but it can drastically increase the speed at which this issue can be processed since it takes away the time-consuming reconstruction to reproduce the enhancement or bug.** The recommened way is to upload it as [Gist](https://gist.github.com) or new repository to GitHub, but of course you can [attach it to this issue](https://help.github.com/articles/file-attachments-on-issues-and-pull-requests), use any free file hosting service or paste the code in [Markdown code blocks](https://help.github.com/articles/basic-writing-and-formatting-syntax) into this issue. @@ -70,7 +70,7 @@ If possible please provide more context by answering these questions: ## Stack Trace and Error Messages -``` +```raw Paste the full stack trace, error messages or the logfile here ... ``` diff --git a/.remarkignore b/.remarkignore new file mode 100644 index 0000000..c6b1021 --- /dev/null +++ b/.remarkignore @@ -0,0 +1,5 @@ +# +---------+ +# + Node.js + +# +---------+ +src/node_modules/* +node_modules/* diff --git a/.remarkrc.js b/.remarkrc.js new file mode 100644 index 0000000..72db352 --- /dev/null +++ b/.remarkrc.js @@ -0,0 +1,17 @@ +/* + * Copyright (c) 2018-present Arctic Ice Studio + * Copyright (c) 2018-present Sven Greb + * + * Project: Arctic Ice Studio remark-lint Preset + * Repository: https://github.com/arcticicestudio/remark-preset-lint-arcticicestudio + * License: MIT + */ + +/** + * @file The remark-lint configuration. + * @author Arctic Ice Studio + */ + +module.exports = { + plugins: ["remark-preset-lint-arcticicestudio"] +}; diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6c9f038..40f6852 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -10,7 +10,7 @@ As for everything else in the project, the contributions to Styleguide Markdown ## Getting Started -Styleguide Markdown is an open source project and we love to receive contributions from the community! There are many ways to contribute, from [writing- and improving documentation and tutorials](), [reporting bugs](#bug-reports), [submitting enhancement suggestions](#enhancement-suggestions) which can be incorporated into Styleguide Markdown itself by [submitting a pull request](#pull-requests). +Styleguide Markdown is an open source project and we love to receive contributions from the community! There are many ways to contribute, from [writing- and improving documentation and tutorials](#documentations), [reporting bugs](#bug-reports), [submitting enhancement suggestions](#enhancement-suggestions) which can be incorporated into Styleguide Markdown itself by [submitting a pull request](#pull-requests). The project development workflow and process uses [GitHub Issues][gh-issues]- and [Pull Requests][gh-pr] management to track issues and pull requests. @@ -113,7 +113,7 @@ A well-crafted Git commit message is the best way to communicate *context* about Styleguide Markdown adheres to the [Arctic Ice Studio Git Style Guide][styleguide-git-github]. -[![][styleguide-git-badge]][styleguide-git-github] +[![Arctic Ice Studio Git Style Guide Badge][styleguide-git-badge]][styleguide-git-github] The style guide assumes that you are familiar with the [gitflow][gitflow] branching model. diff --git a/README.md b/README.md index ebbedbe..5924917 100644 --- a/README.md +++ b/README.md @@ -4,12 +4,65 @@

-

+

+ +

+--- + +

+ +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. + +To make sure your code matches this style guide use the official [remark-preset-lint-arcticicestudio][remark-preset-lint-arcticicestudio-ghio] code linter preset for [remark-lint][remark-lint-gh], 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 [styleguides][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 & Sven Greb

+ +[commonmark]: http://commonmark.org +[docs]: https://arcticicestudio.github.io/styleguide-markdown +[docs-dev-building]: https://arcticicestudio.github.io/styleguide-markdown/development/building.html +[docs-dev-contributing]: https://arcticicestudio.github.io/styleguide-markdown/development/contributing.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#styleguides +[docs-dev-contributing-versioning]: https://arcticicestudio.github.io/styleguide-markdown/development/contributing.html#versioning +[docs-dev-requirements]: https://arcticicestudio.github.io/styleguide-markdown/development/requirements.html +[docs-rules]: https://arcticicestudio.github.io/styleguide-markdown/rules/index.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 +[gfm]: https://github.github.com/gfm +[remark]: https://remark.js.org +[remark-lint-gh]: https://github.com/remarkjs/remark-lint +[remark-preset-lint-arcticicestudio-ghio]: https://arcticicestudio.github.io/remark-preset-lint-arcticicestudio diff --git a/package.json b/package.json index 467e7f0..a5784bb 100644 --- a/package.json +++ b/package.json @@ -25,5 +25,19 @@ "config", "preset" ], - "private": true + "private": true, + "scripts": { + "clean": "del build", + "docs:build": "gitbook install src && gitbook build src build/docs", + "docs:dev": "npm run docs:build && gitbook serve src build/docs", + "lint:md": "remark --no-stdout ./*.md src/ .github/", + "lint": "npm run lint:md", + "prepublishOnly": "npm run lint" + }, + "devDependencies": { + "del-cli": "1.1.0", + "gitbook-cli": "2.3.2", + "remark-cli": "5.0.0", + "remark-preset-lint-arcticicestudio": "0.1.0" + } } diff --git a/src/README.md b/src/README.md new file mode 100644 index 0000000..1f50a65 --- /dev/null +++ b/src/README.md @@ -0,0 +1,67 @@ +

+ +

+ +

+ +

+ +

+ +

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 + +This style guide provides the [comprehensive base rule set][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][rules-code-blocks], [headings][rules-headings] or [lists][rules-lists], defines [naming conventions][rules-naming-conventions] and best practices for [whitespaces][rules-whitespaces], [Raw HTML][rules-raw-html], [emphasizing][rules-emphasis] and [strings][rules-strings]. + +The development chapters contain information about the [requirements][dev-requirements] and [how to build][dev-building] this style guide documentation. + +To make sure your code matches this style guide use the official [remark-preset-lint-arcticicestudio][remark-preset-lint-arcticicestudio-ghio] code linter preset for [remark-lint][remark-lint-gh], a plugin for [remark][]. + +### Contributing + +Read the [contributing guide][dev-contributing] to learn about the development process and how to propose [enhancement suggestions][dev-contributing-enhancements] and [report bugs][dev-contributing-bug-reports], how to [submit pull requests][dev-contributing-pr] and the project's [styleguides][dev-contributing-styleguides], [branch organization][dev-contributing-branch-org] and [versioning][dev-contributing-versioning] model. + +The guide also includes information about [minimal, complete, and verifiable examples][dev-contributing-mcve] and other ways to contribute to the project like [improving existing issues][dev-contributing-other-improve-issues] and [giving feedback on issues and pull requests][dev-contributing-other-feedback]. + +

+ +

Copyright © 2018-present Arctic Ice Studio & Sven Greb

+ +

+ +[dev-building]: development/building.md +[dev-contributing]: development/contributing.md +[dev-contributing-branch-org]: development/contributing.md#branch-organization +[dev-contributing-bug-reports]: development/contributing.md#bug-reports +[dev-contributing-enhancements]: development/contributing.md#enhancement-suggestions +[dev-contributing-mcve]: development/contributing.md#mcve +[dev-contributing-other-feedback]: development/contributing.md#give-feedback-on-issues-and-pull-requests +[dev-contributing-other-improve-issues]: development/contributing.md#improve-issues +[dev-contributing-pr]: development/contributing.md#pull-requests +[dev-contributing-styleguides]: development/contributing.md#styleguides +[dev-contributing-versioning]: development/contributing.md#versioning +[dev-requirements]: development/requirements.md +[rules]: rules/index.md +[rules-code-blocks]: rules/code.md#blocks +[rules-emphasis]: rules/emphasis.md +[rules-headings]: rules/headings.md +[rules-lists]: rules/lists.md +[rules-naming-conventions]: rules/naming-conventions.md +[rules-raw-html]: rules/raw-html.md +[rules-strings]: rules/strings.md +[rules-whitespaces]: rules/whitespaces.md + +[commonmark]: http://commonmark.org +[gfm]: https://github.github.com/gfm +[remark]: https://remark.js.org +[remark-lint-gh]: https://github.com/remarkjs/remark-lint +[remark-preset-lint-arcticicestudio-ghio]: https://arcticicestudio.github.io/remark-preset-lint-arcticicestudio diff --git a/src/SUMMARY.md b/src/SUMMARY.md new file mode 100644 index 0000000..e2e4376 --- /dev/null +++ b/src/SUMMARY.md @@ -0,0 +1,134 @@ +# Summary + +### Introduction + +* [Overview](README.md) + +### Rules + +* [Overview](rules/index.md) +* [Accessibility A11Y](rules/accessibility-a11y.md) + * [Alternative Text](rules/accessibility-a11y.md#alternative-text) +* [Blockquotes](rules/blockquotes.md) + * [Indentation](rules/blockquotes.md#indentation) + * [Multi Line](rules/blockquotes.md#multi-line) +* [Code](rules/code.md) + * [Blocks](rules/code.[code]#blocks) + * [Syntax Highlighting](rules/code.md#blocks#syntax-highlighting) + * [Escape Newlines In Terminal Commands](rules/code.md#blocks#escape-newlines-in-terminal-commands) + * [No Shell Code Dollar Sign](rules/code.md#blocks#no-shell-code-dollar-sign) + * [Within Lists](rules/code.md#blocks#within-lists) + * [Inline](rules/code.md#blocks#inline) + * [Marker Character Style](rules/code.md#blocks#marker-character-style) + * [Use Cases](rules/code.md#blocks#use-cases) +* [Comments](rules/comments.md) + * [HTML](rules/comments.md#html) +* [Emphasis](rules/emphasis.md) + * [Italic](rules/emphasis.md#italic) + * [Bold](rules/emphasis.md#bold) + * [Strikethrough](rules/emphasis.md#strikethrough) + * [No Header Replacement](rules/emphasis.md#no-header-replacement) + * [No Inner Spacing](rules/emphasis.md#no-inner-spacing) +* [Headings](rules/headings.md) + * [ATX Style](rules/headings.md#atx-style) + * [Empty Lines Before And After](rules/headings.md#empty-lines-before-and-after) + * [Content Spacing](rules/headings.md#content-spacing) + * [No Content Before](rules/headings.md#no-content-before) + * [No Duplicate](rules/headings.md#no-duplicate) + * [Letter Case](rules/headings.md#letter-case) + * [Length](rules/headings.md#length) + * [Punctuation After Content](rules/headings.md#punctuation-after-content) +* [Horizontal Rules](rules/horizontal-rules.md) + * [Marker Character Style](rules/horizontal-rules.md#marker-character-style) + * [No Prepended Or Appended Content](rules/horizontal-rules.md#no-prepended-or-appended-content) + * [Empty Lines Before And After](rules/horizontal-rules.md#empty-lines-before-and-after) + * [Use Cases](rules/horizontal-rules.md#use-cases) +* [Images](rules/images.md) + * [Absolute URLs](rules/images.md#absolute-urls) + * [Badges](rules/images.md#badges) +* [Links](rules/links.md) + * [Prefer Reference Links](rules/links.md#prefer-reference-links) + * [Inline](rules/links.md#inline) + * [Definition Placement](rules/links.md#definition-placement) + * [Empty Line Before](rules/links.md#empty-line-before) + * [Letter Case](rules/links.md#letter-case) + * [No ID Inner Spacing](rules/links.md#no-id-inner-spacing) + * [No Trailing Or Leading Title Spaces](rules/links.md#no-trailing-or-leading-title-spaces) + * [Spacing After Colon](rules/links.md#spacing-after-colon) + * [Sorting](rules/links.md#sorting) + * [Reference Link Groups](rules/links.md#reference-link-groups) + * [Reference Link Group Ordering](rules/links.md#reference-link-group-ordering) + * [No Unused](rules/links.md#no-unused) + * [No Undefined](rules/links.md#no-undefined) + * [Autolink Protocol](rules/links.md#autolink-protocol) + * [Unique IDs](rules/links.md#unique-ids) + * [No Empty URL](rules/links.md#no-empty-url) + * [No Reference Like URL](rules/links.md#no-reference-like-url) +* [Lists](rules/lists.md) + * [Unordered Marker](rules/lists.md#unordered-marker) + * [Ordered Marker](rules/lists.md#ordered-marker) + * [No Content Before](rules/lists.md#no-content-before) + * [Continuous Indentation](rules/lists.md#continuous-indentation) + * [Empty Lines](rules/lists.md#empty-lines) + * [Empty Lines Before And After](rules/lists.md#empty-lines-before-and-after) + * [Letter Case](rules/lists.md#letter-case) + * [Punctuation After Items](rules/lists.md#punctuation-after-items) + * [Checkbox Character Style](rules/lists.md#checkbox-character-style) +* [Naming Conventions](rules/naming-conventions.md) + * [File Extension](rules/naming-conventions.md#file-extension) + * [File Naming](rules/naming-conventions.md#file-naming) +* [Paragraphs](rules/paragraphs.md) + * [No Indentation](rules/paragraphs.md#no-indentation) +* [Raw HTML](rules/raw-html.md) + * [Aligned Content](rules/raw-html.md#aligned-content) + * [Inline Content](rules/raw-html.md#inline-content) + * [Collapsed Content](rules/raw-html.md#collapsed-content) +* [Strings](rules/strings.md) + * [Quotes](rules/strings.md#quotes) + * [Line Length](rules/strings.md#line-length) +* [Tables](rules/tables.md) + * [Prefer Lists](rules/tables.md#prefer-lists) + * [Empty Lines Before And After](rules/tables.md#empty-lines-before-and-after) + * [Content Spacing](rules/tables.md#content-spacing) + * [Header Delimiter Row Spacing](rules/tables.md#header-delimiter-row-spacing) + * [Minimum Column Width](rules/tables.md#minimum-column-width) + * [Alignment](rules/tables.md#alignment) + * [No Indentation](rules/tables.md#no-indentation) +* [Whitespace](rules/whitespace.md) + * [Indentation Character](rules/whitespace.md#indentation-character) + * [Newline](rules/whitespace.md#newline) + * [Before Blocks](rules/whitespace.md#before-blocks) + * [After Sentences](rules/whitespace.md#after-sentences) + * [Maximum Line Length](rules/whitespace.md#maximum-line-length) + * [Trailing](rules/whitespace.md#trailing) + +### Development + +* [Requirements](development/requirements.md) +* [Building](development/building.md) + * [Documentations](development/building.md#documentations) +* [Contributing](development/contributing.md) + * [Getting Started](development/contributing.md#getting-started) + * [Port Projects](development/contributing.md#port-projects) + * [Bug Reports](development/contributing.md#bug-reports) + * [Enhancement Suggestions](development/contributing.md#enhancement-suggestions) + * [Pull Requests](development/contributing.md#pull-requests) + * [Documentations](development/contributing.md#documentations) + * [Branch Organization](development/contributing.md#branch-organization) + * [How else can I help?](development/contributing.md#how-else-can-i-help) + * [Improve Issues](development/contributing.md#improve-issues) + * [Give Feedback On Issues and Pull Requests](development/contributing.md#give-feedback-on-issues-and-pull-requests) + * [Styleguides](development/contributing.md#styleguides) + * [Git Commit Messages](development/contributing.md#git-commit-messages) + * [MCVE](development/contributing.md#mcve) + * [Versioning](development/contributing.md#versioning) + * [Credits](development/contributing.md#credits) +* [Changelog](development/changelog.md) + * [0.1.0](development/changelog.md#010) +* [Code of Conduct](development/code-of-conduct.md) + * [What we believe in and how we act](development/code-of-conduct.md#what-we-believe-in-and-how-we-act) + * [Unacceptable Behavior](development/code-of-conduct.md#unacceptable-behavior) + * [Responsibilities](development/code-of-conduct.md#responsibilities) + * [Consequences for Violations](development/code-of-conduct.md#consequences-for-violations) + * [Scope](development/code-of-conduct.md#scope) +* [Credits](development/credits.md) diff --git a/src/assets/markdown-logo.png b/src/assets/markdown-logo.png new file mode 100644 index 0000000000000000000000000000000000000000..768a659e7b76bf2e68a00da30593a195de6d23b1 GIT binary patch literal 31980 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 literal 0 HcmV?d00001 diff --git a/src/assets/snowflake.png b/src/assets/snowflake.png new file mode 100755 index 0000000000000000000000000000000000000000..d58d6f7bb8420f1c5758785bbf98670482b922b2 GIT binary patch literal 1541 zcmV+g2KxDlP)mKj%uZ8MwDSI(AsoW6| zX>k~Y?ja$INd|$2LLb)lVNgb0t}by4ecr=htdNJ4veI;H1j1khg^);dThxbz`N6?u zcxkMw$nt8%7M6c!5BJK_l_j@=LJwTH_xJmq^ZovQ=g;q4RFy%V+yfoT-Fuu?RdR*$ zY_3qARaJ8L9;b5;bZAg}7K6%~cM8i|af{^~!X<=DZn2!hvQ}90P7P`HlfiR6RXFBKS=2ym%%_}J90T1v{&Lf*w z=H^$%L&l6bgD}m0nQ)7hSKj}!a=06BmkYMGI1c((45ilC?{6)}s)@02XX?O$VjTfK zK)3)j01!R_nN*|zEV+dz6Uo}@5@VwQ5&a`DxwR#~1pe0d1l+tgg2f}CMEiKDCK7Xq zx$owQzI!5d7t{^rj|9&osQd1T)Ll1E6fyU!iNsuo=}Dl3#UnTGjr1izj2jsJyb~Oe z3}OxgWAJqpz{#X@0f|7=^~WGsGlrPMh-5+}jDAjx8=a707ewS8j46b`mD3RW;^d#U+9avy9m1eU(%w~Pq-fu=wK1Dc3%=@?(2{%uanD;TlIh0TB{br=4&t@v^ zOdVM0g(bNMI>efHipIX8lTFm-=2ylQ>xdui{Q+pCW*GMV1;9q?XWes7mQdVWo%c=( zW_k9+p(Qt8OAy=2@J#Bq9yQh{*KoX~eq8P7pRPg8ce>24M_XMY)Y| zj>yyJ?mV>rl0AxP>12=C`8&&X0l9$af6@3`$o4eIg**RQ|AUoW`*uy>jaYN&C1+~1 zYN_5rWac};8>tzDCPI@&YG$uG;bhV|L}o12Th7#IHP#$@N#Kp-+P7JqT&`C)g5W*c>~>8{dIq6ecrroUD-*Xjh}#?Wr`Gyj zc@E%Y!zWRHYOS~QiF;+Y@MPk96G+xpmr(f-^do44*|xddZznAhwrwtV3^hSNLgm9` zZFQ-aPRLj8eC2tJIpcRSrjE$LAm^Jvw0)$3_<0_ZdUa!)xJ^q3k%M3st7D_TbBkrL ztec%ZX82Os*7p#Z?f@XT&nv;r*e2_z*Rj_7?w&yZ9Bkk;$mtG@DPZS2?1BbovE(?k z`$1HTsPzr73P+nA;7(gn9DfXgHLHmADAb5R2}_RC;A|&kh=7w#tz&qWRu30QvR0c# ztrwjv&8zd?$(_RDm)B+gU7V})-bp7*GlKPVesXX&1P+rJp6zbWcQ+T?k*|m}-^7yp zL4Qcl$t(Z}W*OvdR6awv@1GLqvGlhFYXx97bKu|pNwu~quVM5>wj*D4!~N(#CVdI? z6E|N=5Z}5TfVZ+D0+iU?cgo2oYJ=Dt{5FhjWe6@4ghhnKo&N-XZXg+$fNh(*h?#OS r=^V;+l Please make sure to complete the [requirement][requirements] steps first in order to build the project! + +Run `npm install` from within the project root to bootstrap the project and install all dependencies. + +Continuous integration builds are running at [Circle CI][ci-circle]. + +## Documentations + +This documentation can be build by running + +```sh +npm run docs:build +``` + +from within the project root to bootstrap the build toolchain and install all dependencies. The output will be placed in `build/docs`. + +To start the local hot reload server with browser live reload, using the default port `4000`, run + +```sh +npm run docs:dev +``` + +[requirements]: requirements.md + +[ci-circle]: https://circleci.com/gh/arcticicestudio/styleguide-markdown diff --git a/src/development/changelog.md b/src/development/changelog.md new file mode 100644 index 0000000..b376bb0 --- /dev/null +++ b/src/development/changelog.md @@ -0,0 +1 @@ +{% include "git+https://github.com/arcticicestudio/styleguide-markdown.git/CHANGELOG.md" %} diff --git a/src/development/code-of-conduct.md b/src/development/code-of-conduct.md new file mode 100644 index 0000000..411dfab --- /dev/null +++ b/src/development/code-of-conduct.md @@ -0,0 +1 @@ +{% include "git+https://github.com/arcticicestudio/styleguide-markdown.git/CODE_OF_CONDUCT.md" %} diff --git a/src/development/contributing.md b/src/development/contributing.md new file mode 100644 index 0000000..12ec574 --- /dev/null +++ b/src/development/contributing.md @@ -0,0 +1 @@ +{% include "git+https://github.com/arcticicestudio/styleguide-markdown.git/CONTRIBUTING.md" %} diff --git a/src/development/credits.md b/src/development/credits.md new file mode 100644 index 0000000..f9c63c6 --- /dev/null +++ b/src/development/credits.md @@ -0,0 +1,43 @@ +Thanks for the inspirations and attributions to GitHub's [Open Source Guides](https://opensource.guide) and other large style guides like [Atlassian Design][atlassian-design], [Google's DocGuide][google-docguide-gh], the [Google Developer Documentation Style Guide][google-developer-doc-style-guide] and the [Markdown Style Guide][markdown_style_guide-ciro_santilli] by Ciro Santilli. + +If you use this style guide in your project, you can include these badges in the documentation to let other developer know that the code adheres to this style. + +![Markdown Style Guide Badge][badge-styleguide-markdown] + +```md +[![Markdown Style Guide](https://cdn.rawgit.com/arcticicestudio/styleguide-markdown/develop/assets/styleguide-markdown-banner-typography-badge.svg) +``` + +![Code Style Badge][badge-styleguide-code-style] + +```md +[![Markdown Style Guide](https://cdn.rawgit.com/arcticicestudio/styleguide-markdown/develop/assets/styleguide-badge-code-style.svg) +``` + +![Markdown Style Guide Badge Version][badge-shield-code-style-version] + +```md +![Markdown Style Guide](https://img.shields.io/badge/Markdown_Style_Guide-0.1.0-88C0D0.svg?style=flat-square&colorA=2E3440&logo=data%3Aimage%2Fsvg%2Bxml%3Bbase64%2CPHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIzOSIgaGVpZ2h0PSIzOSIgdmlld0JveD0iMCAwIDM5IDM5Ij48cGF0aCBmaWxsPSJub25lIiBzdHJva2U9IiNEOERFRTkiIHN0cm9rZS13aWR0aD0iMyIgc3Ryb2tlLW1pdGVybGltaXQ9IjEwIiBkPSJNMS41IDEuNWgzNnYzNmgtMzZ6Ii8%2BPHBhdGggZmlsbD0iI0Q4REVFOSIgZD0iTTIwLjY4MyAyNS42NTVsNS44NzItMTMuNDhoLjU2Nmw1Ljg3MyAxMy40OGgtMS45OTZsLTQuMTU5LTEwLjA1Ni00LjE2MSAxMC4wNTZoLTEuOTk1em0tMi42OTYgMGwtMTMuNDgtNS44NzJ2LS41NjZsMTMuNDgtNS44NzJ2MS45OTVMNy45MzEgMTkuNWwxMC4wNTYgNC4xNnoiLz48L3N2Zz4%3D) +``` + +![Code Style Badge][badge-shield-code-style] + +```md +![Markdown Style Guide](https://img.shields.io/badge/%20-Code_Style-88C0D0.svg?style=flat-square&colorA=2E3440&logo=data%3Aimage%2Fsvg%2Bxml%3Bbase64%2CPHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIzOSIgaGVpZ2h0PSIzOSIgdmlld0JveD0iMCAwIDM5IDM5Ij48cGF0aCBmaWxsPSJub25lIiBzdHJva2U9IiNEOERFRTkiIHN0cm9rZS13aWR0aD0iMyIgc3Ryb2tlLW1pdGVybGltaXQ9IjEwIiBkPSJNMS41IDEuNWgzNnYzNmgtMzZ6Ii8%2BPHBhdGggZmlsbD0iI0Q4REVFOSIgZD0iTTIwLjY4MyAyNS42NTVsNS44NzItMTMuNDhoLjU2Nmw1Ljg3MyAxMy40OGgtMS45OTZsLTQuMTU5LTEwLjA1Ni00LjE2MSAxMC4wNTZoLTEuOTk1em0tMi42OTYgMGwtMTMuNDgtNS44NzJ2LS41NjZsMTMuNDgtNS44NzJ2MS45OTVMNy45MzEgMTkuNWwxMC4wNTYgNC4xNnoiLz48L3N2Zz4%3D) +``` + +![Code Style Badge Color Inverted][badge-shield-code-style-inverted] + +```md +![Markdown Style Guide](https://img.shields.io/badge/%20-Code_Style-2E3440.svg?style=flat-square&colorA=ffffff&logo=data%3Aimage%2Fsvg%2Bxml%3Bbase64%2CPHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIzMi41IiBoZWlnaHQ9IjMyLjUiIHZpZXdCb3g9IjAgMCAzMi41IDMyLjUiPjxwYXRoIGZpbGw9Im5vbmUiIHN0cm9rZT0iIzJFMzQ0MCIgc3Ryb2tlLXdpZHRoPSIuNSIgc3Ryb2tlLW1pdGVybGltaXQ9IjEwIiBkPSJNLjI1LjI1aDMydjMyaC0zMnoiLz48cGF0aCBmaWxsPSIjMkUzNDQwIiBkPSJNMTcuNDMzIDIyLjQwNWw1Ljg3Mi0xMS45OGguNTY2bDUuODczIDExLjk4aC0uNDk2bC01LjY1OS0xMS41NTYtNS42NjEgMTEuNTU2aC0uNDk1em0tMi42OTYgMGwtMTEuOTgtNS44NzN2LS41NjZsMTEuOTgtNS44NzJ2LjQ5NUwzLjE4MSAxNi4yNWwxMS41NTYgNS42NnYuNDk1eiIvPjwvc3ZnPg%3D%3D) +``` + +[atlassian-design]: https://atlassian.design +[badge-shield-code-style]: https://img.shields.io/badge/%20-Code_Style-88C0D0.svg?style=flat-square&colorA=2E3440&logo=data%3Aimage%2Fsvg%2Bxml%3Bbase64%2CPHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIzOSIgaGVpZ2h0PSIzOSIgdmlld0JveD0iMCAwIDM5IDM5Ij48cGF0aCBmaWxsPSJub25lIiBzdHJva2U9IiNEOERFRTkiIHN0cm9rZS13aWR0aD0iMyIgc3Ryb2tlLW1pdGVybGltaXQ9IjEwIiBkPSJNMS41IDEuNWgzNnYzNmgtMzZ6Ii8%2BPHBhdGggZmlsbD0iI0Q4REVFOSIgZD0iTTIwLjY4MyAyNS42NTVsNS44NzItMTMuNDhoLjU2Nmw1Ljg3MyAxMy40OGgtMS45OTZsLTQuMTU5LTEwLjA1Ni00LjE2MSAxMC4wNTZoLTEuOTk1em0tMi42OTYgMGwtMTMuNDgtNS44NzJ2LS41NjZsMTMuNDgtNS44NzJ2MS45OTVMNy45MzEgMTkuNWwxMC4wNTYgNC4xNnoiLz48L3N2Zz4%3D +[badge-shield-code-style-inverted]: https://img.shields.io/badge/%20-Code_Style-2E3440.svg?style=flat-square&colorA=ffffff&logo=data%3Aimage%2Fsvg%2Bxml%3Bbase64%2CPHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIzMi41IiBoZWlnaHQ9IjMyLjUiIHZpZXdCb3g9IjAgMCAzMi41IDMyLjUiPjxwYXRoIGZpbGw9Im5vbmUiIHN0cm9rZT0iIzJFMzQ0MCIgc3Ryb2tlLXdpZHRoPSIuNSIgc3Ryb2tlLW1pdGVybGltaXQ9IjEwIiBkPSJNLjI1LjI1aDMydjMyaC0zMnoiLz48cGF0aCBmaWxsPSIjMkUzNDQwIiBkPSJNMTcuNDMzIDIyLjQwNWw1Ljg3Mi0xMS45OGguNTY2bDUuODczIDExLjk4aC0uNDk2bC01LjY1OS0xMS41NTYtNS42NjEgMTEuNTU2aC0uNDk1em0tMi42OTYgMGwtMTEuOTgtNS44NzN2LS41NjZsMTEuOTgtNS44NzJ2LjQ5NUwzLjE4MSAxNi4yNWwxMS41NTYgNS42NnYuNDk1eiIvPjwvc3ZnPg%3D%3D +[badge-shield-code-style-version]: https://img.shields.io/badge/Markdown_Style_Guide-0.1.0-88C0D0.svg?style=flat-square&colorA=2E3440&logo=data%3Aimage%2Fsvg%2Bxml%3Bbase64%2CPHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIzOSIgaGVpZ2h0PSIzOSIgdmlld0JveD0iMCAwIDM5IDM5Ij48cGF0aCBmaWxsPSJub25lIiBzdHJva2U9IiNEOERFRTkiIHN0cm9rZS13aWR0aD0iMyIgc3Ryb2tlLW1pdGVybGltaXQ9IjEwIiBkPSJNMS41IDEuNWgzNnYzNmgtMzZ6Ii8%2BPHBhdGggZmlsbD0iI0Q4REVFOSIgZD0iTTIwLjY4MyAyNS42NTVsNS44NzItMTMuNDhoLjU2Nmw1Ljg3MyAxMy40OGgtMS45OTZsLTQuMTU5LTEwLjA1Ni00LjE2MSAxMC4wNTZoLTEuOTk1em0tMi42OTYgMGwtMTMuNDgtNS44NzJ2LS41NjZsMTMuNDgtNS44NzJ2MS45OTVMNy45MzEgMTkuNWwxMC4wNTYgNC4xNnoiLz48L3N2Zz4%3D +[badge-styleguide-code-style]: https://cdn.rawgit.com/arcticicestudio/styleguide-markdown/develop/assets/styleguide-badge-code-style.svg +[badge-styleguide-markdown]: https://cdn.rawgit.com/arcticicestudio/styleguide-markdown/develop/assets/styleguide-markdown-banner-typography-badge.svg +[google-docguide-gh]: https://github.com/google/styleguide/blob/gh-pages/docguide +[google-developer-doc-style-guide]: https://developers.google.com/style/ +[markdown_style_guide-ciro_santilli]: http://www.cirosantilli.com/markdown-style-guide diff --git a/src/development/requirements.md b/src/development/requirements.md new file mode 100644 index 0000000..8941368 --- /dev/null +++ b/src/development/requirements.md @@ -0,0 +1,10 @@ +## Node.js + +Styleguide Markdown is build with [Node.js][nodejs] which is required to build some of the file formats. + +### npm + +[npm][npm] is used as package manager which comes prebundled 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 new file mode 100644 index 0000000..7880d02 --- /dev/null +++ b/src/rules/accessibility-a11y.md @@ -0,0 +1,25 @@ +This chapter provides rules to improve the accessibility as documented by the [A11Y][a11y] project. + +## Alternative Text + +Add an alternative text for images. + +###### Examples + +⇣ **Incorrect** code for this rule: + +```markdown +![][snowflake] + +[snowflake]: https://raw.githubusercontent.com/arcticicestudio/styleguide-markdown/develop/src/assets/snowflake.png +```` + +⇡ **Correct** code for this rule: + +```markdown +![snowflake icon][snowflake] + +[snowflake]: https://raw.githubusercontent.com/arcticicestudio/styleguide-markdown/develop/src/assets/snowflake.png +```` + +[a11y]: https://a11yproject.com diff --git a/src/rules/blockquotes.md b/src/rules/blockquotes.md new file mode 100644 index 0000000..95f7830 --- /dev/null +++ b/src/rules/blockquotes.md @@ -0,0 +1,60 @@ +## Indentation + +Always separate the marker `>` from the actual content using a single whitespace. + +> remark-lint: [blockquote-indentation][remark-lint-blockquote-indentation] + +###### Examples + +⇣ **Incorrect** code for this rule: + +```markdown +>Winter +``` + +```markdown +> Winter +``` + +⇡ **Correct** code for this rule: + +```markdown +> Winter +``` + +## Multi Line + +Use a `greater than` sign for every line, including wrapped. + +> remark-lint: [no-blockquote-without-marker][remark-lint-no-blockquote-without-marker] + +###### Examples + +⇣ **Incorrect** code for this rule: + +```markdown +> Winter +Snow +``` + +```markdown +> 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. +``` + +⇡ **Correct** code for this rule: + +```markdown +> Winter +> Snow +``` + +```markdown +> 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. +``` + +[remark-lint-blockquote-indentation]: https://github.com/remarkjs/remark-lint/tree/master/packages/remark-lint-blockquote-indentation +[remark-lint-no-blockquote-without-marker]: https://github.com/remarkjs/remark-lint/tree/master/packages/remark-lint-no-blockquote-without-marker diff --git a/src/rules/code.md b/src/rules/code.md new file mode 100644 index 0000000..d444648 --- /dev/null +++ b/src/rules/code.md @@ -0,0 +1,238 @@ +## Blocks + +Avoid indentation based code blocks, use [fenced code blocks][gfm-spec-fenced_code_blocks] 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][gh-help-gfm_code_syntax_highlighting]. + +> remark-lint: [code-block-style][remark-lint-code-block-style] + +###### Examples + +⇣ **Incorrect** code for this rule: + +```markdown + import React, { PureComponent } from "react"; + + class Frost extends PureComponent { + // ... + } + + export default Frost; +``` + +⇡ **Correct** code for this rule: + +`````markdown +```js +import React, { PureComponent } from "react"; + +class Frost extends PureComponent { + // ... +} + +export default Frost; +``` +````` + +## Syntax Highlighting + +Explicitly declare the language for blocks containing code snippets, so that neither the syntax highlighter nor the next editor must guess. + +> remark-lint: [fenced-code-flag][remark-lint-fenced-code-flag] + +###### Examples + +⇣ **Incorrect** code for this rule: + +`````markdown +``` +import React, { PureComponent } from "react"; + +class Frost extends PureComponent { + // ... +} + +export default Frost; +``` +````` + +⇡ **Correct** code for this rule: + +`````markdown +```js +import React, { PureComponent } from "react"; + +class Frost extends PureComponent { + // ... +} + +export default Frost; +``` +````` + +## Escape Newlines In Terminal Commands + +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. + +###### Examples + +⇣ **Incorrect** code for this rule: + +`````markdown +```sh +npx run docs:generate -- --template=winter --description="Sparkling and frozen" --elements="snow,frost,ice" --snowflakes=20 +``` +````` + +⇡ **Correct** code for this rule: + +`````markdown +```sh +npx run docs:generate -- --template=winter --description="Sparkling and frozen" \ +--elements="snow,frost,ice" --snowflakes=20 +``` +````` + +## No Shell Code Dollar Sign + +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. + +> remark-lint: [no-shell-dollars][remark-lint-no-shell-dollars] + +###### Examples + +⇣ **Incorrect** code for this rule: + +`````markdown +```sh +$ echo "The winter is sparkling and frozen!" +``` +````` + +⇡ **Correct** code for this rule: + +`````markdown +```sh +echo "The winter is sparkling and frozen!" +``` +````` + +`````markdown +```sh +winter="The winter is sparkling and frozen!" +echo $winter # The winter is sparkling and frozen! +``` +````` + +## Within Lists + +When using code blocks within lists make sure to use the correct indention to not break the list. + +###### Examples + +⇣ **Incorrect** code for this rule: + +`````markdown +* Winter +```jsx +const Snow = ; +``` +* Frost +````` + +⇡ **Correct** code for this rule: + +`````markdown +* Winter + ```jsx + const Snow = ; + ``` +* Frost +````` + +## Inline + +Use one (1) backtick character `` ` `` to create a `inline code` span which will render all wrapped content literally. + +###### Examples + +⇣ **Incorrect** code for this rule: + +`````markdown +The winter has ```sparkling``` and frozen ```elements```! +````` + +⇡ **Correct** code for this rule: + +```markdown +The winter has `sparkling` and frozen `elements`! +``` + +To learn what content should be wrapped please read the [use cases](#use-cases) chapter. + +## Marker Character Style + +Use backtick characters `` ` `` for both blocks and inline code. + +> remark-lint: [fenced-code-marker][remark-lint-fenced-code-marker] + +###### Examples + +⇣ **Incorrect** code for this rule: + +`````markdown +~~~js +import React, { PureComponent } from "react"; +class Snow extends PureComponent { + // ... +} +export default Snow; +~~~ +````` + +⇡ **Correct** code for this rule: + +`````markdown +```js +import React, { PureComponent } from "react"; +class Snow extends PureComponent { + // ... +} +export default Snow; +``` +````` + +## Use Cases + +[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. + +[Inline code spans](#inline) on the other hand should be used to highlight e.g. + +* **executables** - `gcc`, `npm`, `go`, `python` +* **paths** - `/etc/hosts`, `src/main/java/com/arcticicestudio/icecore/hashids/Hashids.java` +* **version numbers** - `0.2.0`, `1.8.6-frost.2` +* **code e.g. reserved keywords, builtins and operators** - `this`, `true`/`false`, `String`, `=>` + +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] + +[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 +[crates-libc]: https://crates.io/crates/libc +[gcc]: https://gcc.gnu.org +[gfm-spec-fenced_code_blocks]: https://github.github.com/gfm/#fenced-code-blocks +[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 +[libgit2]: https://libgit2.github.com +[nodejs]: https://nodejs.org +[npm-react-dom]: https://www.npmjs.com/package/react-dom +[pypi-snowsaw]: https://pypi.python.org/pypi/snowsaw +[react]: https://reactjs.org +[remark-lint-code-block-style]: https://github.com/remarkjs/remark-lint/tree/master/packages/remark-lint-code-block-style +[remark-lint-fenced-code-flag]: https://github.com/remarkjs/remark-lint/tree/master/packages/remark-lint-fenced-code-flag +[remark-lint-fenced-code-marker]: https://github.com/remarkjs/remark-lint/tree/master/packages/remark-lint-fenced-code-marker +[remark-lint-no-shell-dollars]: https://github.com/remarkjs/remark-lint/tree/master/packages/remark-lint-no-shell-dollars +[rustlang]: https://www.rust-lang.org diff --git a/src/rules/comments.md b/src/rules/comments.md new file mode 100644 index 0000000..49589c5 --- /dev/null +++ b/src/rules/comments.md @@ -0,0 +1,13 @@ +## HTML + +Prefer [HTML comment syntax][w3-html5-spec-comments] to add hidden, non-rendered comments to the code. + +###### Examples + +⇡ **Correct** code for this rule: + +```markdown + +``` + +[w3-html5-spec-comments]: https://www.w3.org/TR/html51/syntax.html#sec-comments diff --git a/src/rules/emphasis.md b/src/rules/emphasis.md new file mode 100644 index 0000000..dabcf3b --- /dev/null +++ b/src/rules/emphasis.md @@ -0,0 +1,151 @@ +## Italic + +Use two (2) underscore `__` marker to generate spans for italic formatted text. + +> remark-lint: [emphasis-marker][remark-lint-emphasis-marker] + +###### Examples + +⇣ **Incorrect** code for this rule: + +```markdown +_Winter_ +```` + +```markdown +___Snow___ +```` + +⇡ **Correct** code for this rule: + +```markdown +__Winter__ +__Snow__ +```` + +## Bold + +Use two (2) asterisk `*` marker to generate spans for bold formatted text. + +> remark-lint: [emphasis-marker][remark-lint-emphasis-marker] and [strong-marker][remark-lint-strong-marker] + +###### Examples + +⇣ **Incorrect** code for this rule: + +```markdown +*Winter* +```` + +```markdown +***Snow*** +```` + +⇡ **Correct** code for this rule: + +```markdown +**Winter** +**Snow** +```` + +## Strikethrough + +> Note that [strikethrough][gfm-spec-strikethrough] is an **extension of GFM** and not implemented by all parsers! + +Use two (2) tilde `~` marker to generate spans for striked through text. + +> remark-lint: [emphasis-marker][remark-lint-emphasis-marker] + +###### Examples + +⇣ **Incorrect** code for this rule: + +```markdown +~Winter~ +```` + +```markdown +~~~Snow~~~ +```` + +⇡ **Correct** code for this rule: + +```markdown +~~Winter~~ +~~Snow~~ +```` + +## No Header Replacement + +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. + +> remark-lint: [no-emphasis-as-heading][remark-lint-no-emphasis-as-heading] + +###### Examples + +⇣ **Incorrect** code for this rule: + +```markdown +**Winter** + +The winter has sparkling and frozen elements! + +__Snow__ + +Snow is falling down! +```` + +⇡ **Correct** code for this rule: + +```markdown +## Winter + +The winter has sparkling and frozen elements! + +## Snow + +Snow is falling down! +```` + +```markdown +###### Winter + +The winter has sparkling and frozen elements! + +###### Snow + +Snow is falling down! +```` + +## No Inner Spacing + +Don't use inner spaces for any markers. + +> remark-lint: [no-inline-padding][remark-lint-no-inline-padding] + +###### Examples + +⇣ **Incorrect** code for this rule: + +```markdown +** Winter ** +__ Snow __ +```` + +```markdown +** Winter ** +__ Snow __ +```` + +⇡ **Correct** code for this rule: + +```markdown +**Winter** +__Snow__ +```` + +[gfm-spec-strikethrough]: https://github.github.com/gfm/#strikethrough-extension- +[remark-lint-emphasis-marker]: https://github.com/remarkjs/remark-lint/tree/master/packages/remark-lint-emphasis-marker +[remark-lint-no-emphasis-as-heading]: https://github.com/remarkjs/remark-lint/tree/master/packages/remark-lint-no-emphasis-as-heading +[remark-lint-no-inline-padding]: https://github.com/remarkjs/remark-lint/tree/master/packages/remark-lint-no-inline-padding +[remark-lint-strong-marker]: https://github.com/remarkjs/remark-lint/tree/master/packages/remark-lint-strong-marker diff --git a/src/rules/headings.md b/src/rules/headings.md new file mode 100644 index 0000000..5c1f34e --- /dev/null +++ b/src/rules/headings.md @@ -0,0 +1,256 @@ +## ATX Style + +Always use [atx-style][atx] headings (not closed) instead of [Setext][setex]. 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. + +> remark-lint: [heading-style][remark-lint-heading-style] + +###### Examples + +⇣ **Incorrect** code for this rule: + +```markdown +Winter +====== + +Frost +----- +``` + +No closed ATX styled headings: + +```markdown +# Winter # + +## Frost ## + +### Snow ### +``` + +⇡ **Correct** code for this rule: + +```markdown +# Winter + +## Frost + +### Snow +``` + +## Empty Lines Before And After + +Always surround headers by a single empty line except at the beginning of the file. + +###### Examples + +⇣ **Incorrect** code for this rule: + +```markdown +... snowflakes are falling. +# Winter +Sparkling and frozen... +``` + +```markdown +... snowflakes are falling. + + +# Winter + + +Sparkling and frozen... +``` + +⇡ **Correct** code for this rule: + +```markdown +... snowflakes are falling. + +# Winter + +Sparkling and frozen... +``` + +## Content Spacing + +Always separate the marker character `#` from the actual header content using a single whitespace. + +> remark-lint: [no-heading-content-indent][remark-lint-no-heading-content-indent] + +###### Examples + +⇣ **Incorrect** code for this rule: + +```markdown +#Winter +``` + +```markdown +# Winter +``` + +⇡ **Correct** code for this rule: + +```markdown +# Winter +``` + +## No Content Before + +Make sure that there are no other characters (including whitespaces) in front of headings. + +> remark-lint: [no-heading-indent][remark-lint-no-heading-indent] + +###### Examples + +Note: The `·` character represents a whitespace character. + +⇣ **Incorrect** code for this rule: + +```markdown +.# Winter +``` + +```markdown +·# Winter +``` + +⇡ **Correct** code for this rule: + +```markdown +# Winter +``` + +## No Duplicate + +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. + +> remark-lint: [no-duplicate-headings][remark-lint-no-duplicate-headings] and [no-duplicate-headings-in-section][remark-lint-no-duplicate-headings-in-section] + +###### Examples + +⇣ **Incorrect** code for this rule: + +```markdown +# Winter + +## Snow + +# Arctic + +## Snow +``` + +⇡ **Correct** code for this rule: + +```markdown +# Winter + +## Winter Snow + +# Arctic + +## Arctic Snow +``` + +## Letter Case + +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. + +As an exception, [title case][wikipedia-title_case] 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. + +###### Examples + +⇣ **Incorrect** code for this rule: + +```markdown +# winter is sparkling and frozen +``` + +Proper names or code snippets: + +```markdown +# react + +# `String` + +# Init +``` + +⇡ **Correct** code for this rule: + +```markdown +# Winter is sparkling and frozen +``` + +Proper names or code snippets: + +```markdown +# React + +# `string` + +# init main +``` + +## Length + +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. + +> remark-lint: [maximum-heading-length][remark-lint-maximum-heading-length] + +###### Examples + +⇣ **Incorrect** code for this rule: + +```markdown +# The winter is sparkling and frozen and soft snowflakes are falling down on the world! +``` + +⇡ **Correct** code for this rule: + +```markdown +# Winter + +The winter is sparkling and frozen and soft snowflakes are falling down on the world! +``` + +## Punctuation After Content + +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. + +> remark-lint: [no-heading-punctuation][remark-lint-no-heading-punctuation] + +###### Examples + +⇣ **Incorrect** code for this rule: + +```markdown +# Winter: Sparkling +``` + +```markdown +# Winter. Frozen. +``` + +```markdown +# Winter # +``` + +⇡ **Correct** code for this rule: + +```markdown +# Winter + +Sparkling and frozen. +``` + +[atx]: http://www.aaronsw.com/2002/atx/intro +[remark-lint-heading-style]: https://github.com/remarkjs/remark-lint/tree/master/packages/remark-lint-heading-style +[remark-lint-maximum-heading-length]: https://github.com/remarkjs/remark-lint/tree/master/packages/remark-lint-maximum-heading-length +[remark-lint-no-duplicate-headings]: https://github.com/remarkjs/remark-lint/tree/master/packages/remark-lint-no-duplicate-headings +[remark-lint-no-duplicate-headings-in-section]: https://github.com/remarkjs/remark-lint/tree/master/packages/remark-lint-no-duplicate-headings-in-section +[remark-lint-no-heading-content-indent]: https://github.com/remarkjs/remark-lint/tree/master/packages/remark-lint-no-heading-content-indent +[remark-lint-no-heading-indent]: https://github.com/remarkjs/remark-lint/tree/master/packages/remark-lint-no-heading-indent +[remark-lint-no-heading-punctuation]: https://github.com/remarkjs/remark-lint/tree/master/packages/remark-lint-no-heading-punctuation +[setex]: http://docutils.sourceforge.net/mirror/setext.html +[wikipedia-title_case]: https://en.wikipedia.org/wiki/Letter_case#Title_case diff --git a/src/rules/horizontal-rules.md b/src/rules/horizontal-rules.md new file mode 100644 index 0000000..8dffc5f --- /dev/null +++ b/src/rules/horizontal-rules.md @@ -0,0 +1,101 @@ +## Marker Character Style + +A horizontal rule must consist of three (3) hyphens (`-`) without spaces. + +> remark-lint: [rule-style][remark-lint-rule-style] + +###### Examples + +⇣ **Incorrect** code for this rule: + +```markdown +- +``` + +```markdown +-- + +- - +``` + +```markdown +-- - + +- -- +``` + +⇡ **Correct** code for this rule: + +```markdown +--- +``` + +## No Prepended Or Appended Content + +Make sure that there are no other prepended or appended characters (including whitespaces). + +###### Examples + +⇣ **Incorrect** code for this rule: + +```markdown +.--- +``` + +```markdown + --- +``` + +```markdown +---x +``` + +```markdown +--- +``` + +⇡ **Correct** code for this rule: + +```markdown +--- +``` + +## Empty Lines Before And After + +Always surround lines by a single empty line except at the beginning of the file. + +###### Examples + +⇣ **Incorrect** code for this rule: + +```markdown +... snowflakes are falling. +--- +Sparkling and frozen... +``` + +```markdown +... snowflakes are falling. + + +--- + + +Sparkling and frozen... +``` + +⇡ **Correct** code for this rule: + +```markdown +... snowflakes are falling. + +--- + +Sparkling and frozen... +``` + +## Use Cases + +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. + +[remark-lint-rule-style]: https://github.com/remarkjs/remark-lint/tree/master/packages/remark-lint-rule-style diff --git a/src/rules/images.md b/src/rules/images.md new file mode 100644 index 0000000..63177ec --- /dev/null +++ b/src/rules/images.md @@ -0,0 +1,41 @@ +## Absolute URLs + +Prefer absolute URLs instead of relative ones to improve the portability of the document. + +###### Examples + +⇣ **Incorrect** code for this rule: + +```markdown +![snowflake icon][snowflake] snowflakes falling down in the winter! + +[snowflake]: ../assets/snowflake.png +``` + +⇡ **Correct** code for this rule: + +```markdown +![snowflake icon][snowflake] snowflakes falling down in the winter! + +[snowflake]: https://raw.githubusercontent.com/arcticicestudio/styleguide-markdown/develop/src/assets/snowflake.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]. + +###### Examples + +⇡ **Correct** code for this rule: + +```markdown +[![Nord GitHub Shield Latest Release][shields-gh-releases-nord]][nord-gh-releases] [![Nord NPM Registry Shield Latest Release Version Number][shields-npm-version-nord]][npm-nord] + +[nord-gh-releases]: https://github.com/arcticicestudio/nord/releases/latest +[npm-nord]: https://www.npmjs.com/package/nord +[shields-npm-version-nord]: https://img.shields.io/npm/v/nord.svg?style=flat-square +[shields-gh-releases-nord]: https://img.shields.io/github/release/arcticicestudio/nord.svg?style=flat-square +``` + +[crates.io]: https://crates.io +[npm]: https://npmjs.com diff --git a/src/rules/index.md b/src/rules/index.md new file mode 100644 index 0000000..22cdf5a --- /dev/null +++ b/src/rules/index.md @@ -0,0 +1,13 @@ +

+ +

This section contains rules for Markdown with support for GitHub Flavored Markdown which is based on the CommonMark specification. + +Markdown is a [lightweight markup language][wikipedia-lightweight_markup_language] with plain text formatting syntax for writing structured documents. It is designed so that it can be converted to HTML and many other formats. + +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. + +Today the most used specifications are [CommonMark][commonmark] and its superset [GitHub Flavored Markdown][gfm] 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. + +[commonmark]: http://commonmark.org +[gfm]: https://github.github.com/gfm +[wikipedia-lightweight_markup_language]: https://en.wikipedia.org/wiki/Lightweight_markup_language diff --git a/src/rules/links.md b/src/rules/links.md new file mode 100644 index 0000000..faaa630 --- /dev/null +++ b/src/rules/links.md @@ -0,0 +1,520 @@ +## Prefer Reference Links + +Always use [reference links][gfm-spec-links-ref] instead of [inline](#inline) links except for inner anchor links ([fragment identifiers][w3-html5-spec-navigate_fragment_identifier]). + +There are three kinds of reference links: full, collapsed, and shortcut. +This can be one of the three reference link types: + +* [full][gfm-spec-links-ref_full] +* [collapsed][gfm-spec-links-ref_collapsed] +* [short][gfm-spec-links-ref_short] + +###### Examples + +⇣ **Incorrect** code for this rule: + +```markdown +[Winter](https://the-winter-is-sparkling-and-frozen.io) +``` + +⇡ **Correct** code for this rule: + +```markdown +[Winter](#winter) + +## Winter +``` + +```markdown +[Winter][winter-info] + +[winter-info]: https://the-winter-is-sparkling-and-frozen.io +``` + +## Inline + +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. + +###### Examples + +⇣ **Incorrect** code for this rule: + +```markdown +[Winter](https://the-winter-is-sparkling-and-frozen-and-snow-falls-down.io) +``` + +⇡ **Correct** code for this rule: + +```markdown +[Winter](https://sho.rt/l1n-k) +``` + +## Definition Placement + +Always place reference links at the bottom of the document. This keeps the focus of the reader on the content and increases the maintainability. + +> remark-lint: [final-definition][remark-lint-final-definition] + +###### Examples + +⇣ **Incorrect** code for this rule: + +```markdown +The [Winter][winter-info] is sparkling and frozen! + +[winter-info]: https://the-winter-is-sparkling-and-frozen.io + +Many snowflakes are falling down. +``` + +⇡ **Correct** code for this rule: + +```markdown +The [Winter][winter-info] is sparkling and frozen! + +Many snowflakes are falling down. + +[winter-info]: https://the-winter-is-sparkling-and-frozen.io +``` + +## Empty Line Before + +Always add a single empty line before the first reference link. + +###### Examples + +⇣ **Incorrect** code for this rule: + +```markdown +The [Winter][winter-info] is sparkling and frozen! [Snowflakes][snowflakes-info] are falling. +[snowflakes-info]: https://in-the-winter-many-snowflakes-are-falling.io +[winter-info]: https://the-winter-is-sparkling-and-frozen.io +``` + +⇡ **Correct** code for this rule: + +```markdown +The [Winter][winter-info] is sparkling and frozen! [Snowflakes][snowflakes-info] are falling. + +[snowflakes-info]: https://in-the-winter-many-snowflakes-are-falling.io +[winter-info]: https://the-winter-is-sparkling-and-frozen.io +``` + +## Letter Case + +Only use lower case letters for reference link IDs. This increases the readability and prevents errors since links are [case-insensitive][gfm-spec-links-case_insensitive]. + +> remark-lint: [definition-case][remark-lint-definition-case] + +###### Examples + +⇣ **Incorrect** code for this rule: + +```markdown +The [Winter][WinterInfo] is sparkling and frozen! [Snowflakes][snowFlakes-Info] are falling. + +[snowFlakes-Info]: https://in-the-winter-many-snowflakes-are-falling.io +[WinterInfo]: https://the-winter-is-sparkling-and-frozen.io +``` + +⇡ **Correct** code for this rule: + +```markdown +The [Winter][winter-info] is sparkling and frozen! [Snowflakes][snowflakes-info] are falling. + +[snowflakes-info]: https://in-the-winter-many-snowflakes-are-falling.io +[winter-info]: https://the-winter-is-sparkling-and-frozen.io +``` + +## No ID Inner Spacing + +Don't use inner spaces within link IDs. + +> remark-lint: [no-inline-padding][remark-lint-no-inline-padding] + +###### Examples + +⇣ **Incorrect** code for this rule: + +```markdown +The [Winter][ winter-info ] is sparkling and frozen! + +[Snowflakes][ snowflakes-info ] are falling. + +[ snowflakes-info ]: https://in-the-winter-many-snowflakes-are-falling.io +[ winter-info ]: https://the-winter-is-sparkling-and-frozen.io +``` + +⇡ **Correct** code for this rule: + +```markdown +The [Winter][winter-info] is sparkling and frozen! + +[Snowflakes][snowflakes-info] are falling. + +[snowflakes-info]: https://in-the-winter-many-snowflakes-are-falling.io +[winter-info]: https://the-winter-is-sparkling-and-frozen.io +``` + +## No Trailing Or Leading Title Spaces + +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. + +###### Examples + +⇣ **Incorrect** code for this rule: + +```markdown +The[ Winter ][winter-info]is sparkling and frozen![ Snowflakes ][snowflakes-info]are falling. + +[snowflakes-info]: https://in-the-winter-many-snowflakes-are-falling.io +[winter-info]: https://the-winter-is-sparkling-and-frozen.io +``` + +⇡ **Correct** code for this rule: + +```markdown +The [Winter][winter-info] is sparkling and frozen! [Snowflakes][snowflakes-info] are falling. + +[snowflakes-info]: https://in-the-winter-many-snowflakes-are-falling.io +[winter-info]: https://the-winter-is-sparkling-and-frozen.io +``` + +## Spacing After Colon + +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. + +> remark-lint: [definition-spacing][remark-lint-definition-spacing] + +###### Examples + +⇣ **Incorrect** code for this rule: + +```markdown +The [Winter][winter-info] is sparkling and frozen! [Snowflakes][snowflakes-info] are falling. + +[snowflakes-info]: https://in-the-winter-many-snowflakes-are-falling.io +[winter-info]: https://the-winter-is-sparkling-and-frozen.io +``` + +```markdown +The [Winter][winter-info] is sparkling and frozen! [Snowflakes][snowflakes-info] are falling. + +[snowflakes-info]:https://in-the-winter-many-snowflakes-are-falling.io +[winter-info]:https://the-winter-is-sparkling-and-frozen.io +``` + +⇡ **Correct** code for this rule: + +```markdown +The [Winter][winter-info] is sparkling and frozen! [Snowflakes][snowflakes-info] are falling. + +[snowflakes-info]: https://in-the-winter-many-snowflakes-are-falling.io +[winter-info]: https://the-winter-is-sparkling-and-frozen.io +``` + +## Sorting + +Always sort reference links alphabetically by their IDs. Each [reference link group](#reference-link-groups) must be sorted independent of others! + +It is home for many beautiful animals like snowy owls, arctic foxes, and grizzly bears + +###### Examples + +⇣ **Incorrect** code for this rule: + +```markdown +[Snowflakes][snowflakes-info] are falling. + +The [Winter][winter-info] is sparkling and frozen! + +The [Arctic][arctic-animals] is home for many beautiful animals. + +Snowballs are made of [1000s of snowflakes][1000-snowball_flakes]. + +[snowflakes-info]: https://in-the-winter-many-snowflakes-are-falling.io +[winter-info]: https://the-winter-is-sparkling-and-frozen.io +[arctic-animals]: https://arctic-home-for.animals +[1000-snowball_flakes]: https://1000-snowball.flakes +``` + +⇡ **Correct** code for this rule: + +```markdown +[Snowflakes][snowflakes-info] are falling. + +The [Winter][winter-info] is sparkling and frozen! + +The [Arctic][arctic-animals] is home for many beautiful animals. + +Snowballs are made of [1000s of snowflakes][1000-snowball_flakes]. + +[1000-snowball_flakes]: https://1000-snowball.flakes +[arctic-animals]: https://arctic-home-for.animals +[snowflakes-info]: https://in-the-winter-many-snowflakes-are-falling.io +[winter-info]: https://the-winter-is-sparkling-and-frozen.io +``` + +## Reference Link Groups + +Use blocks for internal and external reference links separated by one (1) empty line. + +###### Examples + +⇣ **Incorrect** code for this rule: + +```markdown +The [Winter][winter-info] is sparkling and frozen! [Snowflakes][snowflakes-info] are falling. + +[winter-info]: winter/info.md +[snowflakes-info]: https://in-the-winter-many-snowflakes-are-falling.io +``` + +```markdown +The [Winter][winter-info] is sparkling and frozen! [Snowflakes][snowflakes-info] are falling. + +[winter-info]: winter/info.md + + + + +[snowflakes-info]: https://in-the-winter-many-snowflakes-are-falling.io +``` + +⇡ **Correct** code for this rule: + +```markdown +The [Winter][winter-info] is sparkling and frozen! [Snowflakes][snowflakes-info] are falling. + +[winter-info]: winter/info.md + +[snowflakes-info]: https://in-the-winter-many-snowflakes-are-falling.io +``` + +## Reference Link Group Ordering + +It is more convenient to always follow the same organization for reference link order to easier find internal and external targets. + +1. Internal links group + 1.1 [full reference links][gfm-spec-links-ref_full] + 1.2 [collapsed reference links][gfm-spec-links-ref_collapsed] + 1.2 [short reference links][gfm-spec-links-ref_short] +2. External links group + +###### Examples + +⇣ **Incorrect** code for this rule: + +```markdown +The [Winter][winter-info] is sparkling and frozen! + +[Snowflakes][] are falling. + +The [Arctic][arctic-animals] is home for many beautiful animals. + +[snowflakes]: https://in-the-winter-many-snowflakes-are-falling.io + +[arctic-animals]: arctic-animals.md +[winter-info]: winter/info.md +``` + +⇡ **Correct** code for this rule: + +```markdown +The [Winter][winter-info] is sparkling and frozen! + +[Snowflakes][] are falling. + +The [Arctic][arctic-animals] is home for many beautiful animals. + +[arctic-animals]: arctic-animals.md +[winter-info]: winter/info.md + +[snowflakes]: https://in-the-winter-many-snowflakes-are-falling.io +``` + +## No Unused + +Remove unused reference links to improve the overview and maintainability. + +> remark-lint: [no-unused-definitions][remark-lint-no-unused-definitions] + +###### Examples + +⇣ **Incorrect** code for this rule: + +```markdown +The [Winter][winter-info] is sparkling and frozen! + +[arctic-animals]: arctic-animals.md +[snowflakes]: snow/flakes.md +[winter-info]: winter/info.md +``` + +⇡ **Correct** code for this rule: + +```markdown +The [Winter][winter-info] is sparkling and frozen! + +[winter-info]: winter/info.md +``` + +## No Undefined + +Never use references that are not defined. + +> remark-lint: [no-undefined-references][remark-lint-no-undefined-references] + +###### Examples + +⇣ **Incorrect** code for this rule: + +```markdown +The [Winter][winter] is sparkling and frozen! +``` + +⇡ **Correct** code for this rule: + +```markdown +The [Winter][winter] is sparkling and frozen! + +[winter]: https://the-winter-is-sparkling-and-frozen.io +``` + +## Autolink Protocol + +Always add a valid protocol when using [autolinks][gfm-spec-links-autolinks]. + +> remark-lint: [no-auto-link-without-protocol][remark-lint-no-auto-link-without-protocol] + +###### Examples + +⇣ **Incorrect** code for this rule: + +```markdown +www.arcticicestudio.com + +arcticicestudio.com +``` + +⇡ **Correct** code for this rule: + +```markdown +https://arcticicestudio.com + +https://www.arcticicestudio.com + +http://arcticicestudio.com + +http://www.arcticicestudio.com +``` + +```markdown +mailto:code@arcticicestudio.com +``` + +## Unique IDs + +Reference link IDs must be unique within a document file. + +> remark-lint: [no-duplicate-definitions][remark-lint-no-duplicate-definitions] + +###### Examples + +⇣ **Incorrect** code for this rule: + +```markdown +[snow]: snow/flakes.md +[snow]: snow/index.md +``` + +⇡ **Correct** code for this rule: + +```markdown +[snow]: snow/index.md +[snowflakes]: snow/flakes.md +``` + +## No Empty URL + +Don't use links or images with empty URLs. + +> remark-lint: [no-empty-url][remark-lint-no-empty-url] + +###### Examples + +⇣ **Incorrect** code for this rule: + +```markdown +The [winter][winter] is sparkling and frozen! + +![snowflake image][snowflake] + +[snowflake]: +[winter]: +``` + +```markdown +The [winter]() is sparkling and frozen! + +![snowflake image]() +``` + +⇡ **Correct** code for this rule: + +```markdown +The [winter][winter] is sparkling and frozen! + +![snowflake image][snowflake] + +[snowflake]: https://snow-is-falling-down.io/snowflake.png +[winter]: https://the-winter-is-sparkling-and-frozen.io +``` + +```markdown +The [winter](https://the-winter-is-sparkling-and-frozen.io) is sparkling and frozen! + +![snowflake image](https://snow-is-falling-down.io/snowflake.png) +``` + +## No Reference Like URL + +Never use URLs that are also defined reference link identifiers. + +> remark-lint: [no-reference-like-url][remark-lint-no-reference-like-url] + +###### Examples + +⇣ **Incorrect** code for this rule: + +```markdown +The [winter](winter) is sparkling and frozen! + +[winter]: https://the-winter-is-sparkling-and-frozen.io +``` + +⇡ **Correct** code for this rule: + +```markdown +The [winter](https://the-winter-is-sparkling-and-frozen.io) is sparkling and frozen! + +[winter]: https://the-winter-is-sparkling-and-frozen.io +``` + +[gfm-spec-links-autolinks]: https://github.github.com/gfm/#autolinks +[gfm-spec-links-case_insensitive]: https://github.github.com/gfm/#example-170 +[gfm-spec-links-ref]: https://github.github.com/gfm/#reference-link +[gfm-spec-links-ref_collapsed]: https://github.github.com/gfm/#collapsed-reference-link +[gfm-spec-links-ref_full]: https://github.github.com/gfm/#full-reference-link +[gfm-spec-links-ref_short]: https://github.github.com/gfm/#shortcut-reference-link +[remark-lint-definition-case]: https://github.com/remarkjs/remark-lint/tree/master/packages/remark-lint-definition-case +[remark-lint-definition-spacing]: https://github.com/remarkjs/remark-lint/tree/master/packages/remark-lint-definition-spacing +[remark-lint-final-definition]: https://github.com/remarkjs/remark-lint/tree/master/packages/remark-lint-final-definition +[remark-lint-no-auto-link-without-protocol]: https://github.com/remarkjs/remark-lint/tree/master/packages/remark-lint-no-auto-link-without-protocol +[remark-lint-no-duplicate-definitions]: https://github.com/remarkjs/remark-lint/tree/master/packages/remark-lint-no-duplicate-definitions +[remark-lint-no-empty-url]: https://github.com/remarkjs/remark-lint/tree/master/packages/remark-lint-no-empty-url +[remark-lint-no-inline-padding]: https://github.com/remarkjs/remark-lint/tree/master/packages/remark-lint-no-inline-padding +[remark-lint-no-reference-like-url]: https://github.com/remarkjs/remark-lint/tree/master/packages/remark-lint-no-reference-like-url +[remark-lint-no-undefined-references]: https://github.com/remarkjs/remark-lint/tree/master/packages/remark-lint-no-undefined-references +[remark-lint-no-unused-definitions]: https://github.com/remarkjs/remark-lint/tree/master/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/lists.md b/src/rules/lists.md new file mode 100644 index 0000000..ea46bfd --- /dev/null +++ b/src/rules/lists.md @@ -0,0 +1,422 @@ +## Unordered Marker + +Use asterisk `*` marker. + +> remark-lint: [unordered-list-marker-style][remark-lint-unordered-list-marker-style] + +###### Examples + +⇣ **Incorrect** code for this rule: + +```markdown +- Winter +- Snow +- Frost +```` + +```markdown ++ Winter ++ Snow ++ Frost +```` + +⇡ **Correct** code for this rule: + +```markdown +* Winter +* Snow +* Frost +```` + +## Ordered Marker + +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. + +The only disadvantage is that references break when a new list item is added. This problem can be reduced by + +* using an unordered list until the final structure and layout has been determined. +* keeping references close to the list so authors are less likely to forget to update them. +* always specify an specific version of the markdown file when referring from an external document. + +> remark-lint: [ordered-list-marker-style][remark-lint-ordered-list-marker-style] and [ordered-list-marker-value][remark-lint-ordered-list-marker-value] + +###### Examples + +⇣ **Incorrect** code for this rule: + +```markdown +1. Winter +1. Snow + 1.1 Snowflakes +1. Frost +```` + +```markdown +1) Winter +1) Snow + 1.1) Snowflakes +1) Frost +```` + +```markdown +1) Winter +2) Snow + 2.1) Snowflakes +3) Frost +```` + +⇡ **Correct** code for this rule: + +```markdown +1. Winter +2. Snow + 2.1 Snowflakes +3. Frost +```` + +## No Content Before + +Make sure that there are no other characters (including whitespaces) in front of each list item. + +> remark-lint: [list-item-bullet-indent][remark-lint-list-item-bullet-indent] + +###### Examples + +Note: The `·` character represents a whitespace character. + +⇣ **Incorrect** code for this rule: + +```markdown +x* Winter + * Snow + .* Snowflakes +"* Frost +·* Frost +``` + +```markdown +x1. Winter + 2. Snow + .2.1 Snowflakes +"3. Frost +·3. Frost +``` + +⇡ **Correct** code for this rule: + +```markdown +* Winter +* Snow + * Snowflakes +* Frost +``` + +```markdown +1. Winter +2. Snow + 2.1 Snowflakes +3. Frost +``` + +## Continuous Indentation + +Use two (2) whitespaces for continuous indentation of nested items and their content. + +> remark-lint: [list-item-content-indent][remark-lint-list-item-content-indent] and [list-item-indent][remark-lint-list-item-indent] + +###### Examples + +⇣ **Incorrect** code for this rule: + +```markdown +* Winter + * Snow +* Snowflakes + * Frost +* Arctic + * Sparkling + * Frozen +``` + +```markdown +* Winter + Sparkling and frozen! +* Snowflakes + Made of snow! +* Snow + Falls down! + Arctic beauty +``` + +`````markdown +* Winter + ```js + import React, { PureComponent } from "react"; + class Frost extends PureComponent { + // ... + } + export default Frost; + ``` + * Snow + ```java + import static winter.Snow; + String[] flakes = Snow.getFlakes(); + ``` + * Frost + > Sparkling and frozen! +````` + +⇡ **Correct** code for this rule: + +```markdown +* Winter + * Snow +* Snowflakes + * Frost +* Arctic + * Sparkling + * Frozen +``` + +```markdown +* Winter + Sparkling and frozen! +* Snowflakes + Made of snow! +* Snow + Falls down! + Arctic beauty +``` + +`````markdown +* Winter + ```js + import React, { PureComponent } from "react"; + class Frost extends PureComponent { + // ... + } + export default Frost; + ``` + * Snow + ```java + import winter.Snow; + String[] flakes = Snow.getFlakes(); + ``` + * Frost + > Sparkling and frozen! +````` + +## Empty Lines + +A list must not contain blank lines between each list item. + +> remark-lint: [list-item-spacing][remark-lint-list-item-spacing] + +###### Examples + +⇣ **Incorrect** code for this rule: + +```markdown +* Winter + +* Snow + + * Snowflakes + +* Frost +``` + +⇡ **Correct** code for this rule: + +```markdown +* Winter +* Snow + * Snowflakes +* Frost +``` + +## Empty Lines Before And After + +Always surround lists by a single empty line except at the beginning of the file. + +###### Examples + +⇣ **Incorrect** code for this rule: + +```markdown +... snowflakes are falling. +* Winter +* Snow + * Snowflakes +* Frost +Sparkling and frozen... +``` + +```markdown +... snowflakes are falling. + + +* Winter +* Snow + * Snowflakes +* Frost + + +Sparkling and frozen... +``` + +⇡ **Correct** code for this rule: + +```markdown +... snowflakes are falling. + +* Winter +* Snow + * Snowflakes +* Frost + +Sparkling and frozen... +``` + +## Letter Case + +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. + +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. + +###### Examples + +⇣ **Incorrect** code for this rule: + +```markdown +The winter has + +* Many snowflakes that are falling down. +* Sparkling and frozen elements! +* A lot of beautiful animals like snowy owls, arctic foxes, and grizzly bears. +``` + +Enumerations or context-dependent: + +```markdown +The winter has + +* **snowflakes** - They are falling down. +* **elements** - They are sparkling and frozen! +* **beautiful animals** - Like e.g a lot of snowy owls, arctic foxes, and grizzly bears. +``` + +Proper names or code snippets: + +```markdown +A list for + +* react +* `string` +``` + +⇡ **Correct** code for this rule: + +```markdown +The winter has + +* many snowflakes that are falling down. +* sparkling and frozen elements! +* a lot of beautiful animals like snowy owls, arctic foxes, and grizzly bears. +``` + +Enumerations or context-dependent: + +```markdown +The winter has + +* **Snowflakes** - They are falling down. +* **Elements** - They are sparkling and frozen! +* **Beautiful animals** - e.g a lot of snowy owls, arctic foxes, and grizzly bears. +``` + +Proper names or code snippets: + +```markdown +A list for + +* React +* `String` +``` + +## Punctuation After Items + +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. + +###### Examples + +⇣ **Incorrect** code for this rule: + +```markdown +* Winter. +* Snow. +* Frost. +``` + +```markdown +The Winter is + +* sparkling and frozen +* cold and snowy +* bright and enlightened +``` + +⇡ **Correct** code for this rule: + +```markdown +* Winter +* Snow +* Frost +``` + +```markdown +The Winter is + +* sparkling and frozen. +* cold and snowy. +* bright and enlightened. +``` + +## Checkbox Character Style + +Use `x` for ticked checkboxes and a single space ` ` for non ticked checkboxes. + +> remark-lint: [checkbox-character-style][remark-lint-checkbox-character-style] + +###### Examples + +⇣ **Incorrect** code for this rule: + +```markdown +* [!] Winter +* [~] Snow +* [»] Frost +``` + +```markdown +* [] Winter +* [ ] Snow +* [ ] Frost +``` + +⇡ **Correct** code for this rule: + +```markdown +* [x] Winter +* [ ] Snow +* [x] Frost +``` + +[remark-lint-checkbox-character-style]: https://github.com/remarkjs/remark-lint/tree/master/packages/remark-lint-checkbox-character-style +[remark-lint-list-item-bullet-indent]: https://github.com/remarkjs/remark-lint/tree/master/packages/remark-lint-list-item-bullet-indent +[remark-lint-list-item-content-indent]: https://github.com/remarkjs/remark-lint/tree/master/packages/remark-lint-list-item-content-indent +[remark-lint-list-item-indent]: https://github.com/remarkjs/remark-lint/tree/master/packages/remark-lint-list-item-indent +[remark-lint-list-item-spacing]: https://github.com/remarkjs/remark-lint/tree/master/packages/remark-lint-list-item-spacing +[remark-lint-ordered-list-marker-style]: https://github.com/remarkjs/remark-lint/tree/master/packages/remark-lint-ordered-list-marker-style +[remark-lint-ordered-list-marker-value]: https://github.com/remarkjs/remark-lint/tree/master/packages/remark-lint-ordered-list-marker-value +[remark-lint-unordered-list-marker-style]: https://github.com/remarkjs/remark-lint/tree/master/packages/remark-lint-unordered-list-marker-style diff --git a/src/rules/naming-conventions.md b/src/rules/naming-conventions.md new file mode 100644 index 0000000..e7d2704 --- /dev/null +++ b/src/rules/naming-conventions.md @@ -0,0 +1,62 @@ +## File Extension + +Always use `.md` file extension also for files with [GFM syntax][gfm]. + +> remark-lint: [file-extension][remark-lint-file-extension] + +###### Examples + +⇣ **Incorrect** code for this rule: + +```raw +ice.gfm +snow.mdk +frost.markdown +```` + +⇡ **Correct** code for this rule: + +```markdown +ice.md +snow.md +frost.md +```` + +## File Naming + +Always prefer [spinal-case][wikipedia-letter_case-special_styles] (also named [*kebab-case* or *hyphen-separated*][stackoverflow-11273282]) for file names and use [snake_case][wikipedia-snake_case] only if it contributes to a better understanding of the content. + +> remark-lint: [no-file-name-mixed-case][remark-lint-no-file-name-mixed-case] + +###### Examples + +⇣ **Incorrect** code for this rule: + +```raw +winterSeason.md +IceCold.md +snow fall.md +```` + +⇡ **Correct** code for this rule: + +```raw +winter_season.md +ice_cold.md +snow_fall.md +```` + +⇢ **Recommended** code for this rule: + +```raw +winter-season.md +ice-cold.md +snow-fall.md +```` + +[gfm]: https://github.github.com/gfm +[remark-lint-file-extension]: https://github.com/remarkjs/remark-lint/tree/master/packages/remark-lint-file-extension +[remark-lint-no-file-name-mixed-case]: https://github.com/remarkjs/remark-lint/tree/master/packages/remark-lint-no-file-name-mixed-case +[stackoverflow-11273282]: https://stackoverflow.com/questions/11273282/whats-the-name-for-hyphen-separated-case/12273101 +[wikipedia-letter_case-special_styles]: https://en.wikipedia.org/wiki/Letter_case#Special_case_styles +[wikipedia-snake_case]: https://en.wikipedia.org/wiki/Snake_case diff --git a/src/rules/paragraphs.md b/src/rules/paragraphs.md new file mode 100644 index 0000000..819ca47 --- /dev/null +++ b/src/rules/paragraphs.md @@ -0,0 +1,30 @@ +## No Indentation + +Never indent the content of paragraphs. + +> remark-lint: [no-paragraph-content-indent][remark-lint-no-paragraph-content-indent] + +###### Examples + +Note: The `·` character represents a whitespace. + +⇣ **Incorrect** code for this rule: + +```markdown +·The winter has sparkling and frozen elements! +·Many snowflakes are falling down. +``` + +```markdown +······The winter has sparkling and frozen elements! +········Many snowflakes are falling down. +``` + +⇡ **Correct** code for this rule: + +```markdown +The winter has sparkling and frozen elements! +Many snowflakes are falling down. +``` + +[remark-lint-no-paragraph-content-indent]: https://github.com/remarkjs/remark-lint/tree/master/packages/remark-lint-no-paragraph-content-indent diff --git a/src/rules/raw-html.md b/src/rules/raw-html.md new file mode 100644 index 0000000..e4a3266 --- /dev/null +++ b/src/rules/raw-html.md @@ -0,0 +1,75 @@ +> 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. +> Anyway, consider to **use raw HTML sparingly and only if necessary**! + +## Aligned Content + +Use a [HTML paragraph `

`][mdn-html-element-p] tag with the `align` attribute. Although if the [HTML 5 specification][w3-html5-spec-element-p] states that the `align` attribute is obsolete it is the only possible solution because the [`style` tag is disallowed raw HTML][gfm-spec-disallowed_raw_html] within Markdown so the CSS [`text-align`][mdn-css-text-align] property can not be used. + +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. + +###### Examples + +⇣ **Incorrect** code for this rule: + +```markdown +

The winter is winter is sparkling and frozen!

+```` + +⇡ **Correct** code for this rule: + +```markdown +

The winter is winter is sparkling and frozen!

+```` + +## Inline Content + +Use a [HTML ``][mdn-html-element-img] 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. + +Although MDN states that the `width` and `height` attributes are deprecated and [advises to replace them with the corresponding CSS attributes][mdn-html-attributes], but it is the only possible solution because the [`style` tag is disallowed raw HTML][gfm-spec-disallowed_raw_html] within Markdown so the CSS [`width`][mdn-css-width] and [`height`][mdn-css-height] property can not be used. + +###### Examples + +⇣ **Incorrect** code for this rule: + +```markdown +Sparkling snowflakes falling down in the winter! +```` + +No way to define the size: +```markdown +Sparkling ![snowflake icon](https://raw.githubusercontent.com/arcticicestudio/styleguide-markdown/develop/src/assets/snowflake.png) snowflakes falling down in the winter! +```` + +⇡ **Correct** code for this rule: + +```markdown +Sparkling snowflakes falling down in the winter! +```` + +## Collapsed Content + +Use the HTML [`
`][mdn-html-element-details] 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 [``][mdn-html-element-summary] element. + +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. + +###### Examples + +⇡ **Correct** code for this rule: + +```markdown +
+ Winter +

Sparkling and frozen!

+
+```` + +[gfm-spec-disallowed_raw_html]: https://github.github.com/gfm/#disallowed-raw-html-extension- +[mdn-css-height]: https://developer.mozilla.org/en-US/docs/Web/CSS/height +[mdn-css-text-align]: https://developer.mozilla.org/en-US/docs/Web/CSS/text-align +[mdn-css-width]: https://developer.mozilla.org/en-US/docs/Web/CSS/width +[mdn-html-attributes]: https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes +[mdn-html-element-details]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/details +[mdn-html-element-img]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img +[mdn-html-element-p]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/p +[mdn-html-element-summary]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/summary +[w3-html5-spec-element-p]: https://www.w3.org/TR/html5/grouping-content.html#the-p-element diff --git a/src/rules/strings.md b/src/rules/strings.md new file mode 100644 index 0000000..a5f1733 --- /dev/null +++ b/src/rules/strings.md @@ -0,0 +1,53 @@ +## Quotes + +Use double quotes `""` for strings: + +* **Double quotes can be used for inline HTML**. +* **Consistency to other style guides**. Double quotes are used by many code styles like e.g. [Java][styleguide-java-ghio] and [JavaScript][styleguide-javascript-ghio]. +* **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. + +> remark-lint: [link-title-style][remark-lint-link-title-style] + +###### Examples + +⇣ **Incorrect** code for this rule: + +```markdown +'The winter is sparkling and frozen!' +``` + +⇡ **Correct** code for this rule: + +```markdown +"The winter is sparkling and frozen!" +``` + +## Line Length + +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. + +###### Examples + +⇣ **Incorrect** code for this rule: + +```markdown +"Cupcake ipsum candy pudding soufflé chocolate. Croissant \ +muffin biscuit brownie caramels pudding toffee pie. Tiramisu cookie ice cream \ +cake dessert icing donut." +``` + +```markdown +"Cupcake ipsum candy pudding soufflé chocolate. Croissant" + + "muffin biscuit brownie caramels pudding toffee pie. Tiramisu cookie ice cream " + + "cake dessert icing donut." +``` + +⇡ **Correct** code for this rule: + +```markdown +"Cupcake ipsum candy pudding soufflé chocolate. Croissant muffin biscuit brownie caramels pudding toffee pie. Tiramisu cookie ice cream cake dessert icing donut." +``` + +[remark-lint-link-title-style]: https://github.com/remarkjs/remark-lint/tree/master/packages/remark-lint-link-title-style +[styleguide-java-ghio]: https://arcticicestudio.github.io/styleguide-java +[styleguide-javascript-ghio]: https://arcticicestudio.github.io/styleguide-javascript diff --git a/src/rules/tables.md b/src/rules/tables.md new file mode 100644 index 0000000..2c8133d --- /dev/null +++ b/src/rules/tables.md @@ -0,0 +1,295 @@ +## Prefer Lists + +Prefer [lists][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] +* [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. + +###### Examples + +⇣ **Incorrect** code for this rule: + +```markdown +| Element | URL | Note | Attributes | Types | +| :------: | --- | ---- | ---------- | ----- | +| 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 | +| 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 | +``` + +⇡ **Correct** code for this rule: + +```markdown +## Elements + +### Snow + +* [Wikipedia][wikipedia-snow] +* It falls down in winter! +* Attributes: + * soft + * damp + * crystal-like +* Types: + * powder snow + * wet snow + * lazy snow + +## Frost + +* [Knowledge Base][knowledge_base-frost] +* Sparkling and frozen! +* Attributes: + * cold + * grainy +* Types: + * permafrost + * hard rime + * ground frost + +[knowledge_base-frost]: http://this-is-a-very-long-url-for-information-about-frost-and-the-winter-season.com +[wikipedia-snow]: http://this-is-a-very-long-url-for-information-about-snow.com +``` + +For small, non-complex and single line content: + +```markdown +| Element | Attribute | +| ------- | --------- | +| Frost | Sparkling | +| Ice | Frozen | +``` + +## Empty Lines Before And After + +Always surround tables by a single empty line except at the beginning of the file. + +###### Examples + +⇣ **Incorrect** code for this rule: + +```markdown +... snowflakes are falling. +| Element | Attribute | +| ------- | --------- | +| Snow | Falling | +| Frost | Sparkling | +| Ice | Cold | +Sparkling and frozen... +``` + +```markdown +... snowflakes are falling. + + +| Element | Attribute | +| ------- | --------- | +| Snow | Falling | +| Frost | Sparkling | +| Ice | Cold | + + +Sparkling and frozen... +``` + +⇡ **Correct** code for this rule: + +```markdown +... snowflakes are falling. + +| Element | Attribute | +| ------- | --------- | +| Snow | Falling | +| Frost | Sparkling | +| Ice | Cold | + +Sparkling and frozen... +``` + +## Content Spacing + +Surround the content of headers and cells with at least one (1) single whitespace. + +###### Examples + +⇣ **Incorrect** code for this rule: + +```markdown +|Element|Attribute| +| ----- | ------- | +|Frost|Sparkling | +``` + +```markdown +| Element | Attribute | +| ------- | --------- | +| Frost | Sparkling | +``` + +⇡ **Correct** code for this rule: + +```markdown +| Element | Attribute | +| ------- | --------- | +| Frost | Sparkling | +``` + +## Header Delimiter Row Spacing + +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. + +> remark-lint: [table-cell-padding][remark-lint-table-cell-padding] and [table-pipe-alignment][remark-lint-table-pipe-alignment] + +###### Examples + +⇣ **Incorrect** code for this rule: + +```markdown +| Element | Attribute | +|---------|-----------| +| Frost | Sparkling | +``` + +```markdown +| Element | Attribute | +|---------|-----------| +| Frost | Sparkling | +``` + +```markdown +| Element | Attribute | +|--- | --- | +| Frost | Sparkling | +``` + +```markdown +| Element | Attribute | +|:-------:|----------:| +| Frost | Sparkling | +``` + +⇡ **Correct** code for this rule: + +```markdown +| Element | Attribute | +| ------- | --------- | +| Frost | Sparkling | +``` + +```markdown +| Element | Attribute | +| :-----: | --------: | +| Frost | Sparkling | +``` + +## Minimum Column Width + +The minimum column width is determined by the cell with the longest content in the column. + +> remark-lint: [table-pipe-alignment][remark-lint-table-pipe-alignment] + +###### Examples + +⇣ **Incorrect** code for this rule: + +```markdown +| Element | Attribute | +| ------- | --------- | +| Frost | Sparkling and frozen! | +| Snow | Falling down! | +``` + +⇡ **Correct** code for this rule: + +```markdown +| Element | Attribute | +| ------- | --------- | +| Frost | Sparkling and frozen! | +| Snow | Falling down! | +``` + +## Alignment + +Always align tables vertically. + +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. + +> remark-lint: [table-pipes][remark-lint-table-pipes] + +###### Examples + +⇣ **Incorrect** code for this rule: + +```markdown +| Element | Attribute | +| --- | --- | +| Frost | Sparkling and frozen! | +| Snow | Falling down! | +| Ice | Everything is smooth and slippery in winter! | +``` + +⇡ **Correct** code for this rule: + +```markdown +| Element | Attribute | +| ------- | --------- | +| Frost | Sparkling and frozen! | +| Snow | Falling down! | +| Ice | Everything is smooth and slippery in winter! | +``` + +## No Indentation + +Never indent tables. + +> remark-lint: [no-table-indentation][remark-lint-no-table-indentation] + +###### Examples + +Note: The `·` character represents a whitespace. + +⇣ **Incorrect** code for this rule: + +```markdown +·| Element | Attribute | +·| ------- | --------- | +·| Frost | Sparkling and frozen! | +·| Snow | Falling down! | +``` + +```markdown +··| Element | Attribute | +··| ------- | --------- | +··| Frost | Sparkling and frozen! | +··| Snow | Falling down! | +``` + +```markdown +·········| Element | Attribute | +·········| ------- | --------- | +·········| Frost | Sparkling and frozen! | +·········| Snow | Falling down! | +``` + +⇡ **Correct** code for this rule: + +```markdown +| Element | Attribute | +| ------- | --------- | +| Frost | Sparkling and frozen! | +| Snow | Falling down! | +``` + +[blockquotes]: blockquotes.md +[code-blocks]: code.md#blocks +[lists]: lists.md +[links-inline]: links.md#inline + +[remark-lint-no-table-indentation]: https://github.com/remarkjs/remark-lint/tree/master/packages/remark-lint-no-table-indentation +[remark-lint-table-cell-padding]: https://github.com/remarkjs/remark-lint/tree/master/packages/remark-lint-table-cell-padding +[remark-lint-table-pipe-alignment]: https://github.com/remarkjs/remark-lint/tree/master/packages/remark-lint-table-pipe-alignment +[remark-lint-table-pipes]: https://github.com/remarkjs/remark-lint/tree/master/packages/remark-lint-table-pipes diff --git a/src/rules/whitespace.md b/src/rules/whitespace.md new file mode 100644 index 0000000..6739d14 --- /dev/null +++ b/src/rules/whitespace.md @@ -0,0 +1,222 @@ +## Indentation Character + +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. + +> remark-lint: [no-tabs][remark-lint-no-tabs] + +###### Examples + +Note: The `»` character represents a tab. + +⇣ **Incorrect** code for this rule: + +```markdown +The winter has sparkling and frozen elements! + » This line contains a tab character. +} +``` + +```markdown +The winter has sparkling and frozen elements! + This line contains 4 space characters. +} +``` + +```markdown +The winter has sparkling and frozen elements! + This line contains only 1 space character. +} +``` + +⇡ **Correct** code for this rule: + +```markdown +The winter has sparkling and frozen elements! + This line contains 2 space characters. +} +``` + +## Newline + +End files with a single [newline][wikipedia-newline] character. Always use unix-style _LF_ linebreaks (`\n`, denoted as `␊`) and avoid the usage of Microsoft Windows _CRLF_ characters (`\r\n`, denoted as `␍␊`). + +> remark-lint: [final-newline][remark-lint-final-newline] and [linebreak-style][remark-lint-linebreak-style] + +###### Examples + +Note: The `¬` character represents a line break. + +⇣ **Incorrect** code for this rule: + +```markdown +The winter has sparkling and frozen elements! +Many snowflakes are falling down. +``` + +```markdown +The winter has sparkling and frozen elements! +Many snowflakes are falling down.¬ +¬ + +``` + +⇡ **Correct** code for this rule: + +```markdown +The winter has sparkling and frozen elements! +Many snowflakes are falling down.¬ + +``` + +###### References + +* [Wikipedia: _Control Character_][wikipedia-control_character] + +## Before Blocks + +Always add one (1) blank line before blocks except the first line of the file. + +> remark-lint: [no-consecutive-blank-lines][remark-lint-no-consecutive-blank-lines] and [no-missing-blank-lines][remark-lint-no-missing-blank-lines] + +###### Examples + +Note: The `¬` character represents a line break. + +⇣ **Incorrect** code for this rule: + +```markdown +The winter has sparkling and frozen elements! +Many snowflakes are falling down. +``` + +⇡ **Correct** code for this rule: + +```markdown +The winter has sparkling and frozen elements! +¬ +Many snowflakes are falling down. +``` + +## After Sentences + +Use a single space after sentences. + +###### Examples + +⇣ **Incorrect** code for this rule: + +```markdown +Many snowflakes are falling down. The winter has sparkling and frozen elements! +``` + +```markdown +Many snowflakes are falling down.The winter has sparkling and frozen elements! +``` + +⇡ **Correct** code for this rule: + +```markdown +Many snowflakes are falling down. The winter has sparkling and frozen elements! +``` + +## Maximum Line Length + +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. + +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][gfm-spec-soft_line_breaks]. Therefore, this guide advices to **avoid using a character limit per line for flowing text**, but try to use a maximum line length of 120 characters (including whitespaces) for all other document elements. + +Instead of enforcing a maximum line length, users should use [soft line wrapping][wikipedia-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 [Atom][atom-doc-soft_wrap] or [VSCode][vscode-doc-soft_wrap], IDEs like [JetBrains IntelliJ IDEA][jetbrains-intellij-doc-soft_wrap], word processors, and email clients like [Thunderbird][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. + +Note that the [rule for long strings][strings-line_length] is related to this rule, and should not be broken up. + +> remark-lint: [maximum-line-length][remark-lint-maximum-line-length] + +###### Examples + +⇣ **Incorrect** code for this rule: + +`````markdown +> The winter and all of its fascinating, sparkling and +frozen elements and lively, diverse and beautiful wildlife. + +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. + +```js +const season = winter && winter.elements && winter.elements.snow && winter.elements.snow.state && winter.elements.snow.state.temperature && winter.elements.snow.state.temperature.celsius; +``` +````` + +⇡ **Correct** code for this rule: + +`````markdown +> The winter and all of its fascinating, sparkling and frozen elements and lively, diverse and beautiful wildlife. + +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. + +```js +const season = winter + && winter.elements + && winter.elements.snow + && winter.elements.snow.state + && winter.elements.snow.state.temperature + && winter.elements.snow.state.temperature.celsius; +``` +````` + +## Trailing + +Don't use trailing whitespace to generate a line break, use flowing text style or a blank line to create a new paragraph. + +> remark-lint: [hard-break-spaces][remark-lint-hard-break-spaces] + +###### Examples + +Note: The `·` character represents a whitespace and the `¬` character represents a line break. + +⇣ **Incorrect** code for this rule: + +```markdown +The winter has sparkling and frozen elements!··¬ +Many snowflakes are falling down. +``` + +```markdown +The winter has sparkling and frozen elements!¬ +Many snowflakes are falling down. +``` + +⇡ **Correct** code for this rule: + +```markdown +The winter has sparkling and frozen elements! Many snowflakes are falling down. +``` + +```markdown +The winter has sparkling and frozen elements!¬ + +Many snowflakes are falling down. +``` + +[strings-line_length]: strings.md#line-length + +[atom-doc-soft_wrap]: http://flight-manual.atom.io/getting-started/sections/atom-basics/#soft-wrap +[gfm-spec-soft_line_breaks]: https://github.github.com/gfm/#soft-line-breaks +[jetbrains-intellij-doc-soft_wrap]: https://www.jetbrains.com/help/idea/general.html +[remark-lint-final-newline]: https://github.com/remarkjs/remark-lint/tree/master/packages/remark-lint-final-newline +[remark-lint-hard-break-spaces]: https://github.com/remarkjs/remark-lint/tree/master/packages/remark-lint-hard-break-spaces +[remark-lint-linebreak-style]: https://github.com/remarkjs/remark-lint/tree/master/packages/remark-lint-linebreak-style +[remark-lint-maximum-line-length]: https://github.com/remarkjs/remark-lint/tree/master/packages/remark-lint-maximum-line-length +[remark-lint-no-consecutive-blank-lines]: https://github.com/remarkjs/remark-lint/tree/master/packages/remark-lint-no-consecutive-blank-lines +[remark-lint-no-missing-blank-lines]: https://github.com/remarkjs/remark-lint/tree/master/packages/remark-lint-no-missing-blank-lines +[remark-lint-no-tabs]: https://github.com/remarkjs/remark-lint/tree/master/packages/remark-lint-no-tabs +[thunderbird]: https://www.mozilla.org/thunderbird +[vscode-doc-soft_wrap]: https://code.visualstudio.com/docs/editor/codebasics#_common-questions +[wikipedia-control_character]: https://en.wikipedia.org/wiki/Control_character +[wikipedia-line_wrap]: https://en.wikipedia.org/wiki/Line_wrap_and_word_wrap +[wikipedia-newline]: https://en.wikipedia.org/wiki/Newline diff --git a/src/styles/website.css b/src/styles/website.css new file mode 100644 index 0000000..5d7a0eb --- /dev/null +++ b/src/styles/website.css @@ -0,0 +1,35 @@ +/* + * Copyright (c) 2018-present Arctic Ice Studio + * Copyright (c) 2018-present Sven Greb + * + * Project: Styleguide Markdown + * Repository: https://github.com/arcticicestudio/styleguide-markdown + * License: MIT + * References: + * https://www.gitbook.com + */ + +/* Remove the sidebar link to the hosted gitbook service */ +.gitbook-link { + display: none !important; +} + +/* Sidebar links */ +.book .book-summary nav ul.summary li a { + color: #444; + text-decoration: none; +} + +.book .book-summary nav ul.summary li a:hover, +.book .book-summary nav ul.summary li a:focus { + color: #000; +} + +.book .book-summary nav ul.summary li.active > a { + color: #008cff; +} + +/* anchor.js hover icons */ +.book .book-body .page-wrapper .page-inner section.normal a.anchorjs-link { + color: #008cff; +}