From 6cc4a43967b028e9fbc1d2e9549d9472c27dbf5e Mon Sep 17 00:00:00 2001 From: Adam Kudrna Date: Mon, 25 Nov 2024 13:15:41 +0100 Subject: [PATCH] Chore(web): Allow duplicate headings in docs --- .remarkrc.mjs | 19 ++++++++++++++ .../src/scss/components/Accordion/README.md | 14 +++++----- .../scss/components/FileUploader/README.md | 2 +- .../web/src/scss/components/Header/README.md | 26 +++++++------------ .../web/src/scss/components/Modal/README.md | 12 ++++----- .../web/src/scss/components/Toast/README.md | 4 +-- 6 files changed, 44 insertions(+), 33 deletions(-) diff --git a/.remarkrc.mjs b/.remarkrc.mjs index e9d4f73df2..afcca290e0 100644 --- a/.remarkrc.mjs +++ b/.remarkrc.mjs @@ -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', diff --git a/packages/web/src/scss/components/Accordion/README.md b/packages/web/src/scss/components/Accordion/README.md index a92930b804..58a8c5709a 100644 --- a/packages/web/src/scss/components/Accordion/README.md +++ b/packages/web/src/scss/components/Accordion/README.md @@ -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: ``` -### 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. diff --git a/packages/web/src/scss/components/FileUploader/README.md b/packages/web/src/scss/components/FileUploader/README.md index fbf8a5ecf6..ed418c3391 100644 --- a/packages/web/src/scss/components/FileUploader/README.md +++ b/packages/web/src/scss/components/FileUploader/README.md @@ -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: diff --git a/packages/web/src/scss/components/Header/README.md b/packages/web/src/scss/components/Header/README.md index 14dd360b28..b5d26e8fa2 100644 --- a/packages/web/src/scss/components/Header/README.md +++ b/packages/web/src/scss/components/Header/README.md @@ -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. ``` - - -#### Desktop-Only Actions Navigation - - +#### Header Navigation Navigation is designed to live in either of the action slots (just remember you should use the ` ``` - - -#### Primary and Secondary Actions Navigation - - +#### 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 diff --git a/packages/web/src/scss/components/Modal/README.md b/packages/web/src/scss/components/Modal/README.md index 40de96b04a..65223c3487 100644 --- a/packages/web/src/scss/components/Modal/README.md +++ b/packages/web/src/scss/components/Modal/README.md @@ -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 [`` element][mdn-dialog] which provides several accessibility advantages. @@ -39,7 +39,7 @@ Example: ``` -## 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 ``` -## ModalHeader Component +## ModalHeader ModalHeader contains the title of the dialog and the close button. @@ -130,7 +130,7 @@ the `aria-label` attribute on the `` element: ``` -## ModalBody Component +## ModalBody ModalBody holds the actual content of the Modal. @@ -144,7 +144,7 @@ ModalBody holds the actual content of the Modal. ``` -## 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. diff --git a/packages/web/src/scss/components/Toast/README.md b/packages/web/src/scss/components/Toast/README.md index 36a7662e91..7f9ae8aa42 100644 --- a/packages/web/src/scss/components/Toast/README.md +++ b/packages/web/src/scss/components/Toast/README.md @@ -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).