Style(docs): Fix docs using markdown linter

refs #DS-1100

.remarkignore

@@ -8,7 +8,6 @@ build
 
 # Temporary disabled packages
 # we will fix them incrementally
-docs
 form-validations
 # Codemods transforms directory
 transforms

docs/contribution/experimental-code.md

@@ -79,6 +79,9 @@ documented in each package's main README file in the section `Feature Flags`.
 
 All feature flags follow a prefix naming convention that indicates status.
 
+<!-- @see: https://jira.almacareer.tech/browse/DS-1604 -->
+<!--lint ignore heading-capitalization-->
+
 #### Flags Prefixed with `enable-*`
 
 - Contain new features that we'd like consuming projects to test
@@ -92,6 +95,9 @@ All feature flags follow a prefix naming convention that indicates status.
 If you use these flags, make sure to check our release notes where we'll outline
 any changes to them across our releases.
 
+<!-- @see: https://jira.almacareer.tech/browse/DS-1604 -->
+<!--lint ignore heading-capitalization-->
+
 #### Flags Prefixed with `enable-v#-*`
 
 As the usage of an existing flag increases or we determine a feature to be of high
@@ -147,6 +153,8 @@ if it can be moved (most of the time the team will initiate this move).
 The issue should contain the following criteria that need to
 be met to move a component from experimental to stable:
 
+<!--lint disable no-undefined-references-->
+
 - [ ] All components are exported through main package export file and should not be `UNSTABLE_`
       prefixed
 - [ ] The component should be well documented according to the documentation
@@ -175,5 +183,6 @@ be met to move a component from experimental to stable:
     - [ ] Stories should mirror the intended usage of the component
   - [ ] The component has unit/integration/snapshot tests written using the project's unit testing library for testing the component API
   - [ ] The component has visual tests written using the project's End-to-End testing library for testing the component design
+  <!--lint enable no-undefined-references-->
 
 [docs-feature-flags]: https://github.com/lmc-eu/spirit-design-system/blob/main/docs/contribution/feature-flags.md

docs/decisions/002-node-version.md

@@ -31,7 +31,3 @@ We'll need to update the Node.js version in the packages whenever the active LTS
 version changes.
 
 [node-releases]: https://nodejs.org/en/about/releases/
-
-```
-
-```

docs/decisions/007-release-names.md

@@ -67,17 +67,23 @@ For a better understanding of the release names and used versions, we will stick
 
 ### Terminology
 
+<!--lint ignore no-emphasis-as-heading-->
+
 **Version**
 
 A _version_ refers to a specific state of a package in our design system.
 Each package has its own version number, which we update whenever we make changes to that package.
 
+<!--lint ignore no-emphasis-as-heading-->
+
 **Release**
 
 A _release_ refers to the process of publishing a new version of a package or the entire design system.
 When we make a release, we run tests, build the software, and then publish the new version so that you can use it.
 We provide release notes with each release that explain what changes were made.
 
+<!--lint ignore no-emphasis-as-heading-->
+
 **Distribution/Edition**
 
 A _distribution_ or _edition_ refers to a specific state of the entire design system.

docs/decisions/009-tokens-structure.md

@@ -43,21 +43,21 @@ With Figma Variables, we unified the structure of our tokens in Figma and in the
 
 These are decisions related to the color tokens:
 
-1.  We decided to create a `component` group which contains tokens for unique components. This way, we can easily find the colors
-    that are used in a specific component and we know that these colors are not used anywhere else. And if they are, we
-    know it's an issue.
-2.  We decided to add the `-state-` infix to the interaction state tokens before the state name. This way, we know which tokens
-    are used for states and are related to each other.
-3.  We decided to have suffixes `-basic` and `-subtle` for tokens for components which need two different contrast levels.
-4.  We decided to have `form-field` group which contains tokens for form fields. This group has a subgroup `filled` for
-    tokens which are used for filled part of the form field. In the future, we can add more subgroups for different form field types.
-5.  We decided to have a `disabled` group which covers the disabled state and is used for all components that can be disabled.
-6.  We decided to have a `neutral` group which contains tokens for neutral colors.
-7.  We decided to have a `selected` group which contains tokens for selected items.
-8.  We decided to have a single-purpose groups for tokens that are used only in one place. For example, we have a `text`, `background`,
-    `link`, etc. groups.
-9.  We decided to create color tokens for gradients and shadows. These tokens are used in the `Gradients` and `Shadows` categories.
-    To support multiple shadow or gradients colors in one `Gradients` or `Shadows` token, we use `-color-01`, `-color-02`, etc. suffixes.
+1. We decided to create a `component` group which contains tokens for unique components. This way, we can easily find the colors
+   that are used in a specific component and we know that these colors are not used anywhere else. And if they are, we
+   know it's an issue.
+2. We decided to add the `-state-` infix to the interaction state tokens before the state name. This way, we know which tokens
+   are used for states and are related to each other.
+3. We decided to have suffixes `-basic` and `-subtle` for tokens for components which need two different contrast levels.
+4. We decided to have `form-field` group which contains tokens for form fields. This group has a subgroup `filled` for
+   tokens which are used for filled part of the form field. In the future, we can add more subgroups for different form field types.
+5. We decided to have a `disabled` group which covers the disabled state and is used for all components that can be disabled.
+6. We decided to have a `neutral` group which contains tokens for neutral colors.
+7. We decided to have a `selected` group which contains tokens for selected items.
+8. We decided to have a single-purpose groups for tokens that are used only in one place. For example, we have a `text`, `background`,
+   `link`, etc. groups.
+9. We decided to create color tokens for gradients and shadows. These tokens are used in the `Gradients` and `Shadows` categories.
+   To support multiple shadow or gradients colors in one `Gradients` or `Shadows` token, we use `-color-01`, `-color-02`, etc. suffixes.
 10. In `Shadows` tokens, we also have a `focus-ring` token which is used for focus rings.
 11. Based on our [Dictionaries](../DICTIONARIES.md), we structure our tokens in groups and subgroups. For example, `emotion` colors
     contains `success`, `warning`, `error` and `informative` subgroups or `button` colors contains `primary`, `secondary`, `tertiary`.

docs/decisions/010-deprecations.md

@@ -46,7 +46,7 @@ Migration to new versions will be easier with clear upgrade paths.
 Testing environments may need to handle warning suppression.
 Additional maintenance effort is required to keep deprecation documentation up to date.
 
-### Breaking Changes without Deprecation
+### Breaking Changes Without Deprecation
 
 When delivering a new Major version, deprecating some features may not be possible or there will be a very short period to adapt.
 In such cases, the breaking changes can be introduced without deprecation as a standard part of the major version upgrade.

docs/decisions/README.md

@@ -1,8 +1,12 @@
 # Decisions
 
-## I've been around.
+<!--lint ignore no-heading-punctuation-->
 
-### And I've got opinions...
+## I've Been Around.
+
+<!--lint ignore no-heading-punctuation-->
+
+### And I've Got Opinions...
 
 ![][opinions-image]
 

docs/migrations/web-react/MIGRATION-v1.md

@@ -1,3 +1,6 @@
+<!-- @see: https://jira.almacareer.tech/browse/DS-1604 -->
+<!--lint disable heading-capitalization-->
+
 # Migration Guide
 
 Introducing version 1 of the _spirit-web-react_ package

docs/migrations/web-react/MIGRATION-v2.md

@@ -1,3 +1,6 @@
+<!-- @see: https://jira.almacareer.tech/browse/DS-1604 -->
+<!--lint disable heading-capitalization-->
+
 # Migration Guide
 
 Introducing version 2 of the _spirit-web-react_ package.
@@ -548,6 +551,5 @@ Please refer back to these instructions or reach out to our team if you encounte
 [readme-codemods]: https://github.com/lmc-eu/spirit-design-system/blob/main/packages/codemods/README.md
 [dictionary-placement]: https://github.com/lmc-eu/spirit-design-system/blob/main/docs/DICTIONARIES.md#placement
 [dropdown-readme]: https://github.com/lmc-eu/spirit-design-system/blob/main/packages/web-react/src/components/Dropdown/README.md
-[readme-deprecations]: https://github.com/lmc-eu/spirit-design-system/blob/main/packages/web-react/README.md#deprecations
 [tooltip-readme]: https://github.com/lmc-eu/spirit-design-system/blob/main/packages/web-react/src/components/Tooltip/README.md
 [floating-ui]: https://floating-ui.com

docs/migrations/web-react/MIGRATION-v3.md

@@ -1,3 +1,6 @@
+<!-- @see: https://jira.almacareer.tech/browse/DS-1604 -->
+<!--lint disable heading-capitalization-->
+
 # Migration Guide
 
 Introducing version 3 of the _spirit-web-react_ package.

docs/migrations/web-twig/MIGRATION-v2.md

@@ -1,3 +1,6 @@
+<!-- @see: https://jira.almacareer.tech/browse/DS-1604 -->
+<!--lint disable heading-capitalization-->
+
 # Migration Guide
 
 Introducing version 2 of the _spirit-web-twig_ package

docs/migrations/web-twig/MIGRATION-v3.md

@@ -1,3 +1,6 @@
+<!-- @see: https://jira.almacareer.tech/browse/DS-1604 -->
+<!--lint disable heading-capitalization-->
+
 # Migration Guide
 
 Introducing version 3 of the _spirit-web-twig_ package.
@@ -447,9 +450,7 @@ Please refer back to this guide or reach out to our team if you encounter any is
 [migration-guide-web]: https://github.com/lmc-eu/spirit-design-system/blob/main/docs/migrations/web/MIGRATION-v2.md
 [alert-role-documentation]: https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/alert_role
 [dictionary-placement]: https://github.com/lmc-eu/spirit-design-system/blob/main/docs/DICTIONARIES.md#placement
-[dropdown-readme]: https://github.com/lmc-eu/spirit-design-system/blob/main/packages/web-twig/src/Resources/components/Dropdown/README.md
 [mdn-anchor-target]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#target
 [readme-additional-attributes]: https://github.com/lmc-eu/spirit-design-system/blob/main/packages/web-twig/README.md#additional-attributes
-[readme-deprecations]: https://github.com/lmc-eu/spirit-design-system/blob/main/packages/web-twig/README.md#deprecations
 [tooltip-readme]: https://github.com/lmc-eu/spirit-design-system/blob/main/packages/web-twig/src/Resources/components/Tooltip/README.md
 [floating-ui]: https://floating-ui.com

docs/migrations/web-twig/MIGRATION-v4.md

@@ -1,3 +1,6 @@
+<!-- @see: https://jira.almacareer.tech/browse/DS-1604 -->
+<!--lint disable heading-capitalization-->
+
 # Migration Guide
 
 Introducing version 4 of the _spirit-web-twig_ package.

docs/migrations/web/MIGRATION-v1.md

@@ -1,3 +1,6 @@
+<!-- @see: https://jira.almacareer.tech/browse/DS-1604 -->
+<!--lint disable heading-capitalization-->
+
 # Migration Guide
 
 Introducing version 1 of the _spirit-web_ package

docs/migrations/web/MIGRATION-v2.md

@@ -1,3 +1,6 @@
+<!-- @see: https://jira.almacareer.tech/browse/DS-1604 -->
+<!--lint disable heading-capitalization-->
+
 # Migration Guide
 
 Introducing version 2 of the _spirit-web_ package.
@@ -319,7 +322,5 @@ Instead of using `.Tooltip--top` or `.Tooltip--topLeft`, use a data attribute li
 Please refer back to these instructions or reach out to our team if you encounter any issues during migration.
 
 [dictionary-placement]: https://github.com/lmc-eu/spirit-design-system/blob/main/docs/DICTIONARIES.md#placement
-[readme-deprecations]: https://github.com/lmc-eu/spirit-design-system/blob/main/packages/web/README.md#deprecations
-[readme-feature-flags]: https://github.com/lmc-eu/spirit-design-system/blob/main/packages/web/README.md#feature-flags
 [readme-tooltip]: https://github.com/lmc-eu/spirit-design-system/blob/main/packages/web/src/scss/components/Tooltip/README.md
 [floating-ui]: https://floating-ui.com

docs/migrations/web/MIGRATION-v3.md

@@ -1,3 +1,6 @@
+<!-- @see: https://jira.almacareer.tech/browse/DS-1604 -->
+<!--lint disable heading-capitalization-->
+
 # Migration Guide
 
 Introducing version 3 of the _spirit-web_ package.