An opinionated, yet universally applicable Markdown code style guide
This version migrates this repository to the @svengreb
GitHub account and npm package scope and updates to remark-cli
major version 11
.
tmpl
template repository version 0.11.0
— #61 ⇄ #62 (⊶ 1641a0b1)→ Updated to tmpl
version 0.11.0
, including the versions in between starting from 0.10.0:
This also includes changes required for any linter matches.
svengreb
GitHub account and @svengreb
npm package scope migration — #63 ⇄ #64 (⊶ a49a8084)→ With the retirement of the Arctic Ice Studio personal & Nord project brand this project also moved to the real-in-person identity “Sven Greb“ both in the context of the repository to the svengreb
GitHub account and the @svengreb
npm package scope.
During this migration the only npm package @arcticicestudio/remark-preset-lint
has been deprecated in favor of the new and upcoming @svengreb/remark-preset-lint
that has been published afterwards.
Also the previous visual representation of this style guide through the way too outdated and deprecated GitBook major version 2
has been unpublished and removed. The documentations and references have been updated to use the GitHub repository with the Markdown rendering instead for now until a custom website has been implemented using a modern TechStack like Next.js.
remark-cli
version 11.0.0
— #65 ⇄ #66 (⊶ 57d2f2c8)
→ Updated to the currently latest remark-cli
major version 11
which comes with minimal breaking changes and does not require rules-based migration steps.
This includes updates to the used packages…
remark-footnotes
— ^1.0.0
→ major version 4
remark-frontmatter
— ^1.0.0
→ major version 4
remark-gfm
— ^1.0.0
→ major version 3
remark-lint
— ^8.0.0
→ major version 9
The following plugins now also support ESM:
remark-lint-blockquote-indentation
remark-lint-checkbox-character-style
remark-lint-checkbox-content-indent
remark-lint-code-block-style
remark-lint-definition-case
remark-lint-definition-spacing
remark-lint-emphasis-marker
remark-lint-fenced-code-flag
remark-lint-fenced-code-marker
remark-lint-file-extension
remark-lint-final-definition
remark-lint-final-newline
remark-lint-first-heading-level
remark-lint-hard-break-spaces
remark-lint-heading-increment
remark-lint-heading-style
remark-lint-linebreak-style
remark-lint-link-title-style
remark-lint-list-item-bullet-indent
remark-lint-list-item-content-indent
remark-lint-list-item-indent
remark-lint-list-item-spacing
remark-lint-maximum-heading-length
remark-lint-maximum-line-length
remark-lint-no-auto-link-without-protocol
remark-lint-no-blockquote-without-marker
remark-lint-no-consecutive-blank-lines
remark-lint-no-duplicate-defined-urls
remark-lint-no-duplicate-definitions
remark-lint-no-duplicate-headings-in-section
remark-lint-no-duplicate-headings
remark-lint-no-emphasis-as-heading
remark-lint-no-empty-url
remark-lint-no-file-name-articles
remark-lint-no-file-name-consecutive-dashes
remark-lint-no-file-name-irregular-characters
remark-lint-no-file-name-mixed-case
remark-lint-no-file-name-outer-dashes
remark-lint-no-heading-content-indent
remark-lint-no-heading-indent
remark-lint-no-heading-like-paragraph
remark-lint-no-heading-punctuation
remark-lint-no-html
remark-lint-no-inline-padding
remark-lint-no-literal-urls
remark-lint-no-missing-blank-lines
remark-lint-no-multiple-toplevel-headings
remark-lint-no-paragraph-content-indent
remark-lint-no-reference-like-url
remark-lint-no-shell-dollars
remark-lint-no-shortcut-reference-image
remark-lint-no-shortcut-reference-link
remark-lint-no-table-indentation
remark-lint-no-tabs
remark-lint-no-undefined-references
remark-lint-no-unneeded-full-reference-image
remark-lint-no-unneeded-full-reference-link
remark-lint-no-unused-definitions
remark-lint-ordered-list-marker-style
remark-lint-ordered-list-marker-value
remark-lint-rule-style
remark-lint-strikethrough-marker
remark-lint-strong-marker
remark-lint-table-cell-padding
remark-lint-table-pipe-alignment
remark-lint-table-pipes
remark-lint-unordered-list-marker-style
remark-lint-strikethrough-marker
— #67 ⇄ #68 (⊶ 154b026e)→ To warn when the number of strikethrough markers is inconsistent and does not use two strikethrough markers (~~
) the remark-lint-strikethrough-marker
has been added to support such checks.
The full changelog is available in the repository
Copyright © 2016-present Sven Greb
Changelog for the official Arctic Ice Studio Markdown code style.
Detailed information can be found in the project documentation.
This version changes this repository into a monorepo, deprecates the remark-preset-lint-arcticicestudio package in favour of the new @arcticicestudio/remark-preset-lint package and adds support for remark 13.0.0
.
↠ Before this change this repository only contained the actual style guide documentation while specific projects that implement the guidelines for linters and code style analyzer lived in separate repositories. This was the best approach for modularity and a small and clear code base, but it increased the maintenance overhead by 1(n)
since changes to the development workflow or toolbox, general project documentations as well as dependency management required changes in every repository with dedicated tickets/issues and PRs. In particular, Node packages require frequent dependency management due to their fast development cycles to keep up-to-date with the latest package changes like (security) bug fixes.
This style guide was implemented by the remark-preset-lint-arcticicestudio Node package that lived in its own repository. The development workflow was clean using most of GitHub's awesome features like project boards, codeowner assignments, issue & PR automation and so on, but changes often required multiple actions when packages depend on each other or they use the same development tooling and documentation standards.
Monorepos are a fantastic way to manage such a project structure, but there are also some points that must be taken into account:
packages
) with other modules, commits can now contain changes to multiple code scopes spread over the entire code base.main
branch as well as “empty” changelogs and release notes with placeholder logs that only refer to changes of other modules.Even though a monorepo required some special thoughts, it also comes with a lot of benefits and makes sense for specific project modules that are slightly coupled and where using dedicated repositories only increases the maintenance overhead when changes must be reflected in multiple modules anyway.
In order to reduce the maintenance overhead, the remark-preset-lint-arcticicestudio Node package has been migrated into this repository by adapting to Yarn workspaces. This simplifies the development tooling setup and allows to use a unified documentation base as well as a smoother development and testing workflow.
This change also implies that the root of the repository is the main package for the entire project setup including shared development dependencies, tools and documentations while the packages only contain specific configurations and (dev)dependencies.
Before remark-preset-lint-arcticicestudio was not a scoped package but suffixed with -arcticicestudio
. To simplify the naming and improving the usage of user/organization specific packages, it is now scoped to @arcticicestudio
resulting in the new name @arcticicestudio/remark-preset-lint
.
The currently released public version has been deprecated using the npm deprecate
command where the provided message points out to migrate to the new scoped packages.
The style guide itself and all packages use a shared/fixed/locked version. This helps all packages to keep in sync and ensure the compatibility with the latest style guide version.
13.0.0
(micromark) — #28 ⇄ #29 (⊶ 9ff968f6)↠ remark 13.0.0 is a giant change for remark that replaced the 5+ year old internals with a new low-level parser called micromark. It comes with 100% CommonMark (and GFM as an extension) compliance and is a good base for the future of remark and Markdown.
This projects uses remark through the remark-lint plugin, which introduced support for remark 13.0.0
in its package version 8.0.0
, and the remark-cli package, which comes with support for remark 13.0.0
in its package version 9.0.0
.
remark-cli
— bumped minimum version from 5.0.0
to 9.0.0
remark-lint
— bumped minimum version from 6.0.1
to 8.0.0
remark-lint-*
packages — the @arcticicestudio/remark-preset-lint
packages supports all remark-lint-*
core rule packages whose minimum versions are now bumped to the major version that introduced support for remark 13.0.0
.remark-gfm
plugin — the support for GitHub Flavored Markdown has been moved into the remark-gfm
plugin.remark-footnotes
plugin — adds support for Pandoc footnotes.Because most package versions that are currently used were not up-to-date before, support for new features like core rules has also been added:
remark-lint-no-duplicate-defined-urls
— the core rule warns when definitions define the same URL.remark-lint-no-unneeded-full-reference-image
— the core rule warns when full reference images are used that could be collapsed.remark-lint-no-unneeded-full-reference-link
— the core rule warns when full reference links are used that could be collapsed.↠ Refactored the LICENSE.md
file to use plain text instead of Markdown syntax and removed the .md
file extension leaving the file named as LICENSE
.
Therefore the linting ignore statements have also been removed as well as adjusting the actual text to match exactly the one of the MIT license.
This allows GitHub to display “MIT“ as the license instead of just showing a “View license“ placeholder text.
↠ Migrated the project setup, structure and development workflow from version 0.9.0 of the “tmpl“ template repository. Additionally specific assets like the repository hero image have been replaced and documentations like the README and GitHub issue/PR templates adjusted.
↠ Changed the invalid list entry character from *
to -
in the summary of the documentation to adhere to the style guide and fix failing CI builds.
master
→ main
branch renaming — #7 (⊶ 23130286) by @outloudvi↠ Updated the default branch name from master
to main
which is a global change due to recent humanity movements. Also see #21 (or the entry in this version changelog) for more details about how this projects also adapted this change.
Subtask of arcticicestudio/styleguide-git#9
↠ Adapted to GitHub Flow like documented in detail in the main task issue arcticicestudio/styleguide-git#9.
master
to main
— #21 ⇄ #22 (⊶ c7946f2e)Subtask of arcticicestudio/styleguide-git#11
↠ Adapted to the default branch renaming from master
to main
like documented in detail in the main task issue arcticicestudio/styleguide-git#11.
The full changelog is available in the repository
Copyright © 2018-present Arctic Ice Studio and Sven Greb
The Arctic Ice Studio Markdown Code Style.
Detailed information can be found in the project documentation.
❯ Changed unordered list marker from asterisk *
to dash -
because asterisks can be confused for bold/italic markers. This also aligns with the default format of Prettier. (#3 in PR #4, fea20a63)
The full changelog is available in the repository
The Arctic Ice Studio Markdown Code Style.
Detailed information can be found in the project documentation.
❯ Added the initial style guide with the comprehensive base rule set with support for GitHub Flavored Markdown which is based on the CommonMark specification. (#1 in PR #2, 261fe4cb)
The full changelog is available in the repository