svengreb / styleguide-markdown Goto Github PK

Current Project State

Currently this repository only contains the actual styleguide documentation while specific projects that implement the guidelines for linters and code style analyzer live in separate repositories. This is the best approach for modularity and a small and clear code base, but it increases the maintenance overhead by 1(n) since changes to the development workflow or toolbox, general project documentations as well as dependency management requires 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 styleguide is currently implemented by the remark-preset-lint-arcticicestudio Node package living in its own repository. The development workflow is clean using most of GitHub's awesome features like project boards, codeowner assignments, issue & PR automation and so on, but changes often require multiple actions when packages depend on each other or they use the same development tooling and documentation standards.

Monorepo Comparison

Monorepos 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 requires 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 will be 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 will be the main package for the entire project setup including shared development dependencies, tools and documentations while the packages will only contain specific configurations and (dev)dependencies.

Scoped Packages

Currently remark-preset-lint-arcticicestudio is not a scoped package but suffixed with -arcticicestudio. To simplify the naming and improving the usage of user/organization specific packages, it will be scoped to @arcticicestudio resulting in the new name @arcticicestudio/remark-preset-lint.
The currently released public version will be deprecated using the npm deprecate command where the provided message will point out to migrate to the new scoped packages.

Versioning

The styleguide itself and all packages will use a shared/fixed/locked version. This helps all packages to keep in sync and ensure the compatibility with the latest style guide version.

Subtask of svengreb/styleguide-git#9

Adapt to GitHub Flow like documented in detail in the main task issue svengreb/styleguide-git#9.

Update 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
  • Now supports ESM.
• remark-frontmatter — ^1.0.0 → major version 4
  • Now supports ESM.
• remark-gfm — ^1.0.0 → major version 3
  • Now supports ESM.
  • Added support for GFM footnotes.
• remark-lint — ^8.0.0 → major version 9
  • Now supports ESM.

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

The currently used asterisk * should be changed to dashes -. The main reason is that asterisks * can be confused for bold/italic markers. There was also a very long discussion for Prettier to also change the default to dashes to same reasons which was then adapted.
There are some other reasons like the alignment with the YAML spec which uses dashes for list items.

This guide will now also adapt to this improvement by changing the default unordered list marker from asterisks * to dashes -.

Update to tmpl version 0.11.0, including the versions in between starting from 0.10.0:

1. Optimized GitHub action workflow scope.
2. Updated Node.js packages & GitHub actions ^{1 2}.
3. Opts-in the Dependabot version update configuration.

This will also include changes required for any linter matches.

Design and write the base rule set.

Chapters

• Accessibility A11Y
• Blockquotes
• Code
• Comments
• Emphasis
• Headings
• Horizontal Rules
• Images
• Index
• Links
• Lists
• Naming-conventions
• Raw HTML
• Strings
• Tables
• Whitespaces

Subtask of svengreb/styleguide-git#11

Adapt to the default branch renaming from master to main like documented in detail in the main task issue svengreb/styleguide-git#11.

With the retirement of the Arctic Ice Studio personal & Nord project brand this project will also move 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 currently only npm package @arcticicestudio/remark-preset-lint will be deprecated in favor of the new and upcoming @svengreb/remark-preset-lint that will be published afterwards.

Also the current visual representation of this style guide through the way too outdated and deprecated GitBook major version 2 will be unpublished and removed. The documentations and references will be 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. A simple HTTP redirection page will be published through the gh-pages Git branch that redirects to https://github.com/svengreb/styleguide-markdown to catch possible users and make them aware of the migration.

https://github.com/arcticicestudio/styleguide-markdown/blob/880c5fbfec22ae2e4ad71699f497e2c8105189b5/package.json#L40

Hi, hate to go Dependabot on you 🤖 but this package's dependency tree contains a low risk dependency issue. Upgrading it to 8.0.0 on my side works perfectly fine, but gives a slightly annoying warning about this Remark preset's peer dependency

I am opening a PR to fix this for you 🙆‍♂️

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.

Migration

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.

• Update remark-cli — bump minimum version from 5.0.0 to 9.0.0
• Update remark-lint — bump minimum version from 6.0.1 to 8.0.0
• Update all remark-lint-* packages — the @arcticicestudio/remark-preset-lint packages supports all remark-lint-* core rule packages whose minimum versions must bumped to the major version that introduced support for remark 13.0.0.
• Add remark-gfm plugin — the support for GitHub Flavored Markdown has been moved into the remark-gfm plugin.
• Add remark-footnotes plugin — adds support for Pandoc footnotes.
• Validate 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 for new features like core rules will also be added:

• Support for remark-lint-no-duplicate-defined-urls — the core rule warns when definitions define the same URL.
• Support for remark-lint-no-unneeded-full-reference-image — the core rule warns when full reference images are used that could be collapsed.
• Support for remark-lint-no-unneeded-full-reference-link — the core rule warns when full reference links are used that could be collapsed.

To warn when the number of strikethrough markers is inconsistent and does not use two strikethrough markers (~~) the remark-lint-strikethrough-marker will be added to support such checks.

Migrate 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 will be replaced and documentations like the README and GitHub issue/PR templates will be adjusted.