lmc-eu · literat · Dec 11, 2024 · Nov 25, 2024
@@ -12,6 +12,25 @@ export default {
     // @see: https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-list-item-spacing
     ['remark-lint-list-item-spacing', false],
 
+    /**
+     * There are generic headings which can be repeated across sections.
+     * For example "API", "Options", "Theming".
+     * If we are describing a few subcomponents in the same document, that's the case.
+     * In Header, there were two "Navigation" headings for example.
+     *
+     * It turns out that IDEs and Git hosts handle the duplicate headings the same way,
+     *  that is, in case of conflict when generating HTML, they add a number suffix
+     *  to their ID (at least PhpStorm and GH do it).
+     *
+     * Tt's more a question of linking the headings than the duplication itself.
+     * The question is whether it's more comfortable and sustainable for us to link to headings like `#card-1`
+     *  (and, for a human reading the document, "Card" is what we want to see), or to be
+     *  more specific and future proof in cases like `#cardbody-api` instead of #api-4
+     */
+    // Allow duplicate headings as it is completely valid to have headings of the same name in a document.
+    // @see: https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-no-duplicate-headings
+    ['remark-lint-no-duplicate-headings', false],
+
     // @see: https://github.com/ilyatitovich/remark-lint-heading-capitalization
     [
       'remark-lint-heading-capitalization',

@@ -7,14 +7,14 @@ Depending on your needs, one or more Accordion items can be open at a time.
 
 Building blocks:
 
-- Accordion
-  - Accordion item (one or – typically – more)
-    - Accordion item header
-      - Accordion item header slot (optional)
-    - Collapse
+- [Accordion](#accordion-1)
+  - [Accordion Item](#accordion-item) (one or – typically – more)
+    - [Accordion Item Header](#accordion-item-header)
+      - Accordion Item Header slot (optional)
+    - [Collapse](#collapse-and-accordion-content)
       - Accordion content
 
-### Accordion Component
+### Accordion
 
 Common wrapper for all items:
 
@@ -172,7 +172,7 @@ When you put it all together:
 <!-- Accordion: end -->
 ```
 
-### Open Inly One Item at a Time
+### Open Only One Item at a Time
 
 Link individual **Collapse items** to their **Accordion parent** via
 `data-spirit-parent` attribute to allow just a single item being open at a time.

@@ -25,7 +25,7 @@ Please consult the [main README][web-readme] for how to include JavaScript plugi
 
 Or, feel free to write the controlling script yourself.
 
-## FileUploader Component
+## FileUploader
 
 This is the main wrapper for the whole composition. It provides proper spacing
 for its subcomponents:

@@ -9,16 +9,16 @@ The Header is a composition of several subcomponents:
 - [Header](#minimal-header)
   - [HeaderMobileActions](#mobile-only-actions)
   - [HeaderDesktopActions](#desktop-only-actions)
-    - [HeaderNav](#navigation)
-      - [HeaderNavItem](#navigation)
-        - [HeaderLink](#navigation)
+    - [HeaderNav](#header-navigation)
+      - [HeaderNavItem](#header-navigation)
+        - [HeaderLink](#header-navigation)
 - [HeaderDialog](#header-dialog)
   - [HeaderDialogCloseButton](#close-button)
   - [HeaderDialogActions](#primary-and-secondary-actions)
-    - [HeaderDialogNav](#navigation-1)
-      - [HeaderDialogNavItem](#navigation-1)
-        - [HeaderDialogLink](#navigation-1)
-        - [HeaderDialogText](#navigation-1)
+    - [HeaderDialogNav](#header-dialog-navigation)
+      - [HeaderDialogNavItem](#header-dialog-navigation)
+        - [HeaderDialogLink](#header-dialog-navigation)
+        - [HeaderDialogText](#header-dialog-navigation)
 
 ## JavaScript Plugin
 
@@ -170,11 +170,7 @@ control here.
 </nav>
 ```
 
-<!--lint disable no-duplicate-headings -->
-
-#### Desktop-Only Actions Navigation
-
-<!--lint enable no-duplicate-headings -->
+#### Header Navigation
 
 Navigation is designed to live in either of the action slots (just remember you
 should use the `<nav>` element with the appropriate `aria-label` for that slot,
@@ -286,11 +282,7 @@ necessary).
 </nav>
 ```
 
-<!--lint disable no-duplicate-headings -->
-
-#### Primary and Secondary Actions Navigation
-
-<!--lint enable no-duplicate-headings -->
+#### Header Dialog Navigation
 
 Navigation capabilities are very similar to those of Header. All principles
 apply here as well, with the only difference in class names starting with

@@ -5,10 +5,10 @@ Modal is a composition of several subcomponents:
 - [Modal](#modal-1)
   - [ModalDialog](#modaldialog)
     - [ModalHeader](#modalheader)
-    - [ModalBody](#modalfooter)
+    - [ModalBody](#modalbody)
     - [ModalFooter](#modalfooter)
 
-## Modal Component
+## Modal
 
 Modal establishes the top layer with a backdrop. Under the hood it uses the [`<dialog>` element][mdn-dialog] which
 provides several accessibility advantages.
@@ -39,7 +39,7 @@ Example:
 </dialog>
 ```
 
-## ModalDialog Component
+## ModalDialog
 
 ModalDialog is the actual dialog window, a place for the header, body, and footer of the dialog.
 
@@ -93,7 +93,7 @@ By default, the docked dialog on mobile screens shrinks to fit the height of its
 </article>
 ```
 
-## ModalHeader Component
+## ModalHeader
 
 ModalHeader contains the title of the dialog and the close button.
 
@@ -130,7 +130,7 @@ the `aria-label` attribute on the `<dialog>` element:
 </dialog>
 ```
 
-## ModalBody Component
+## ModalBody
 
 ModalBody holds the actual content of the Modal.
 
@@ -144,7 +144,7 @@ ModalBody holds the actual content of the Modal.
 </div>
 ```
 
-## ModalFooter Component
+## ModalFooter
 
 ModalFooter is the place for actions represented by the Button component. While there always must be a primary Button,
 secondary actions are optional.

@@ -4,7 +4,7 @@ Toast displays a brief, temporary notification that appears at a prescribed loca
 
 Toast is a composition of a few subcomponents:
 
-- [Toast](#toast)
+- [Toast](#toast-1)
   - [ToastBar](#toastbar)
     - [ToastBarMessage](#toastbarmessage)
     - [ToastBarLink](#toastbarlink)
@@ -23,7 +23,7 @@ Please consult the [main README][web-readme] for how to include JavaScript plugi
 
 Or, feel free to write the controlling script yourself.
 
-## Toast Component
+## Toast
 
 The Toast component is a container responsible for positioning the [ToastBar](#toastbar) component. It is capable of
 handling even multiple toast messages at once, stacking them in a [queue](#toast-queue).