Releases · svengreb/styleguide-markdown

27 Apr 10:48

svengreb

v0.5.0

04e5ae3

v0.5.0 Latest

Latest

⇅ [Show all commits][34]

This version [migrates this repository to the @svengreb GitHub account and npm package scope][58] and updates to [remark-cli major version 11][59].

Improvements

Update to tmpl template repository version 0.11.0 — #61 ⇄ #62 (⊶ 1641a0b)

→ Updated to [tmpl version 0.11.0][35], including the versions in between starting from [0.10.0][36]:

[Optimized GitHub action workflow scope][37].
[Updated Node.js packages & GitHub actions][38] [^2] [^3].
[Opts-in the Dependabot version update configuration][39].

This also includes changes required for any linter matches.

svengreb GitHub account and @svengreb npm package scope migration — #63 ⇄ #64 (⊶ a49a808)

→ With [the retirement of the Arctic Ice Studio personal & Nord project brand][40] this project also moved to the real-in-person identity “Sven Greb“ both in the context of the repository to [the svengreb GitHub account][41] and the @svengreb npm package scope.
During this migration the only npm package [@arcticicestudio/remark-preset-lint][25] has been deprecated in favor of the new and upcoming [@svengreb/remark-preset-lint][43] that has been published afterwards.

Also [the previous visual representation of this style guide][45] through the way too outdated and deprecated [GitBook][44] major version 2 has been unpublished and removed. The documentations and references have been updated to use the GitHub repository with the Markdown rendering instead for now until a custom website has been implemented using a modern TechStack like [Next.js][46].

Update to remark-cli version 11.0.0 — #65 ⇄ #66 (⊶ 57d2f2c)

→ Updated to the [currently latest remark-cli major version 11][47] which comes with minimal breaking changes and does not require rules-based migration steps.
This includes updates to the used packages…

[remark-footnotes][14] — ^1.0.0 → [major version 4][53]
- Now [supports ESM][51].
[remark-frontmatter][52] — ^1.0.0 → [major version 4][54]
- Now [supports ESM][51].
[remark-gfm][15] — ^1.0.0 → [major version 3][49]
- Now [supports ESM][51].
- Added support for [GFM footnotes][50].
[remark-lint][21] — ^8.0.0 → [major version 9][56]
- Now [supports ESM][51].

The following plugins now also [support ESM][51]:

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

Support for remark-lint-strikethrough-marker — #67 ⇄ #68 (⊶ 154b026)

→ To warn when the number of strikethrough markers is inconsistent and does not use two strikethrough markers (~~) the [remark-lint-strikethrough-marker][57] has been added to support such checks.

The full changelog is available in the repository

...

Assets 2

05 Apr 19:29

arcticicestudio

v0.4.0

2199bb5

0.4.0

Changelog for the official Arctic Ice Studio Markdown code style.

⇅ [Show all commits][gh-compare-tag-v0.2.0_v0.4.0]

Detailed information can be found in the [project documentation][docs].

This version changes this repository into a [monorepo][trbdev-monorepo], deprecates the [remark-preset-lint-arcticicestudio][gh-arcticicestudio/remark-preset-lint-arcticicestudio] package in favour of the new [@arcticicestudio/remark-preset-lint][gh-tree-pkgs-@ais-remark-preset-lint] package and adds support for [remark 13.0.0][gh-remarkjs/remark-rel-v13.0.0].

Feature

Monorepo with remark packages — #10 ⇄ #12 (⊶ 0c21fab)

↠ 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][gh-arcticicestudio/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.

Monorepo Comparison

[Monorepos][trbdev-monorepo] are a fantastic way to manage such a project structure, but there are also some points that must be taken into account:

No more scoped code — the developer experience with Git is slightly worse because commits can contains changes to multiple scopes of the code. Since there is only a “transparent separation” of code, that was previously located in a dedicated repository but is not aggregated into a parent (e.g. packages) with other modules, commits can now contain changes to multiple code scopes spread over the entire code base.
No more assignment of commits to single modules — like described in the bullet point above, commit can contain changes to multiple modules, it is harder to detect which commit targeted a specific module.
Steeper learning curve for new contributors — in a dedicated repository that only hosts a specific module it is easier for new developers to contribute to the project, but in a monorepo they might need to change code in multiple places within other modules or the root code/documentation of the entire project.
Uniform version number — in order to keep conform to [SemVer][], the entire project must use a uniform version number. This means that a module that has not been changed since the last version must also be incremented in order to keep compatible with the other modules.
Using different version numbers prefixed/suffixed with an individual version number is a not an option, increases the maintenance overhead and and drastically reduces the project overview and quality! This would result in multiple Git tags on the main branch as well as “empty” changelogs and release notes with placeholder logs that only refer to changes of other modules.

Project Future

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][gh-arcticicestudio/remark-preset-lint-arcticicestudio] Node package has been migrated into this repository by adapting to [Yarn workspaces][yarn-docs-ws]. 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.

Scoped Packages

Before [remark-preset-lint-arcticicestudio][gh-arcticicestudio/remark-preset-lint-arcticicestudio] was not a [scoped package][npm-docs-scopes] 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][npm-docs-cli-depr] where the provided message points out to migrate to the new scoped packages.

Versioning

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.

Update to remark 13.0.0 (micromark) — #28 ⇄ #29 (⊶ 9ff968f)

↠ [remark 13.0.0][gh-remarkjs/remark-rel-v13.0.0] is a giant change for remark that replaced the 5+ year old internals with a new low-level parser called [micromark][gh-micromark/micromark]. It comes with 100% CommonMark (and GFM as an extension) compliance and is a good base for the future of remark and Markdown.

Migration

This projects uses remark through the [remark-lint][gh-remarkjs/remark-lint] plugin, which introduced support for remark 13.0.0 in its [package version 8.0.0][gh-remarkjs/remark-lint-rel-v8.0.0], and the [remark-cli][gh-remarkjs/remark] package, which comes with support for remark 13.0.0 in its [package version 9.0.0][gh-remarkjs/[email protected]].

Updated remark-cli — bumped minimum version from [5.0.0 to 9.0.0][gh-remarkjs/[email protected][email protected]]
Updated remark-lint — bumped minimum version from [6.0.1 to 8.0.0][gh-remarkjs/remark-lint-comp-6.0.0_8.0.0]
Updated all remark-lint-* packages — the [@arcticicestudio/remark-preset-lint][gh-tree-pkgs-@ais-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.
Added [remark-gfm plugin][gh-remarkjs/remark-gfm] — the support for [GitHub Flavored Markdown][gfm] has been moved into the remark-gfm plugin.
Added [remark-footnotes plugin][gh-remarkjs/remark-footnotes] — adds support for [Pandoc][] footnotes.
Validated the code base with new linter rules — Run checks with updated packages afterwards to fix and improve results found by linters.

Features

Because most package versions that are currently used were not up-to-date before, support ...

Assets 2

16 Nov 05:50

arcticicestudio

v0.2.0

33e080a

0.2.0

The Arctic Ice Studio Markdown Code Style.

Detailed information can be found in the project documentation.

Improvements

Rules

❯ 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, fea20a6)

The full changelog is available in the repository

Assets 2