Implementation of ScssDocs.astro (#19)

julien-deramond · Mar 24, 2023 · c3bf637 · c3bf637
1 parent a93e888
commit c3bf637
Show file tree

Hide file tree

Showing 69 changed files with 258 additions and 189 deletions.
diff --git a/site-new/src/components/shortcodes/ScssDocs.astro b/site-new/src/components/shortcodes/ScssDocs.astro
@@ -0,0 +1,70 @@
+---
+import fs from 'node:fs'
+import { Prism } from '@astrojs/prism'
+
+// Prints everything between `// scss-docs-start "name"` and `// scss-docs-end "name"`
+// comments in the docs.
+
+interface Props {
+  /**
+   * Reference name used to find the content to display within `file`
+   * @default ""
+   */
+  name: string
+
+  /**
+   * File name that contains the content to display
+   * @default ""
+   */
+  file: string
+
+  /**
+   * Remove the ` !default` flag from variable assignments
+   * @default true
+   */
+  strip_default?: boolean
+}
+
+const { name, file, strip_default = true } = Astro.props
+
+if (!name || !file) {
+  throw new Error(`Missing required parameters! Got: name=${name} file=${file}`)
+}
+
+let content;
+try {
+  content = fs.readFileSync(file, 'utf8')
+
+  content = content.substring(
+    content.indexOf(`// scss-docs-start ${name}`), 
+    content.lastIndexOf(`// scss-docs-end ${name}`)
+  )
+} catch (error) {
+  throw new Error(`Failed to read ${file}`, { cause: error })
+}
+---
+
+{/*
+  TODO: handle ALL the first part of this file with Hugo treatments
+  TODO: double-check everything in this file but this first basic rendering could do the job temporarily
+*/}
+
+<div class="bd-example-snippet bd-code-snippet bd-scss-docs">
+  <div class="d-flex align-items-center highlight-toolbar ps-3 pe-2 py-1 border-bottom">
+    {/* TODO: Not yet handled ---> | replaceRE `\\` "/" */}
+    <a class="font-monospace text-body-secondary text-decoration-none small" href={`[[param:repo]]/blob/v[[param:current_version]]/${file}`}>
+      {file}
+    </a>
+    <div class="d-flex ms-auto">
+      <button type="button" class="btn-clipboard mt-0 me-0" title="Copy to clipboard">
+        <svg class="bi" aria-hidden="true"><use xlink:href="#clipboard"/></svg>
+      </button>
+    </div>
+  </div>
+  {/* TODO: Not yet handled ---> highlight $match "scss" "" */}
+  {/* TODO: Use <Code> ? */}
+  {/* TODO: Remove some extra-spaces */}
+  <div class="highlight">
+    <Prism code={content} lang="scss" />
+  </div>
+</div>
diff --git a/site-new/src/content/docs/components/accordion.mdx b/site-new/src/content/docs/components/accordion.mdx
@@ -159,8 +159,8 @@ Please read the [collapse accessibility section]([[docsref:/components/collapse#
 
 As part of Bootstrap's evolving CSS variables approach, accordions now use local CSS variables on `.accordion` for enhanced real-time customization. Values for the CSS variables are set via Sass, so Sass customization is still supported, too.
 
-{/* {{< scss-docs name="accordion-css-vars" file="scss/_accordion.scss" >}} */}
+<ScssDocs name="accordion-css-vars" file="scss/_accordion.scss" />
 
 ### Sass variables
 
-{/* {{< scss-docs name="accordion-variables" file="scss/_variables.scss" >}} */}
+<ScssDocs name="accordion-variables" file="scss/_variables.scss" />
diff --git a/site-new/src/content/docs/components/alerts.mdx b/site-new/src/content/docs/components/alerts.mdx
@@ -164,25 +164,25 @@ When an alert is dismissed, the element is completely removed from the page stru
 
 As part of Bootstrap's evolving CSS variables approach, alerts now use local CSS variables on `.alert` for enhanced real-time customization. Values for the CSS variables are set via Sass, so Sass customization is still supported, too.
 
-{/* {{< scss-docs name="alert-css-vars" file="scss/_alert.scss" >}} */}
+<ScssDocs name="alert-css-vars" file="scss/_alert.scss" />
 
 ### Sass variables
 
-{/* {{< scss-docs name="alert-variables" file="scss/_variables.scss" >}} */}
+<ScssDocs name="alert-variables" file="scss/_variables.scss" />
 
 ### Sass mixin
 
 <DeprecatedIn version="5.3.0" />
 
 Used in combination with `$theme-colors` to create contextual modifier classes for our alerts.
 
-{/* {{< scss-docs name="alert-variant-mixin" file="scss/mixins/_alert.scss" >}} */}
+<ScssDocs name="alert-variant-mixin" file="scss/mixins/_alert.scss" />
 
 ### Sass loop
 
 Loop that generates the modifier classes with the `alert-variant()` mixin.
 
-{/* {{< scss-docs name="alert-modifiers" file="scss/_alert.scss" >}} */}
+<ScssDocs name="alert-modifiers" file="scss/_alert.scss" />
 
 ## JavaScript behavior
 

diff --git a/site-new/src/content/docs/components/badge.mdx b/site-new/src/content/docs/components/badge.mdx
@@ -96,8 +96,8 @@ Use the `.rounded-pill` utility class to make badges more rounded with a larger
 
 As part of Bootstrap's evolving CSS variables approach, badges now use local CSS variables on `.badge` for enhanced real-time customization. Values for the CSS variables are set via Sass, so Sass customization is still supported, too.
 
-{/* {{< scss-docs name="badge-css-vars" file="scss/_badge.scss" >}} */}
+<ScssDocs name="badge-css-vars" file="scss/_badge.scss" />
 
 ### Sass variables
 
-{/* {{< scss-docs name="badge-variables" file="scss/_variables.scss" >}} */}
+<ScssDocs name="badge-variables" file="scss/_variables.scss" />
diff --git a/site-new/src/content/docs/components/breadcrumb.mdx b/site-new/src/content/docs/components/breadcrumb.mdx
@@ -101,8 +101,8 @@ For more information, see the [ARIA Authoring Practices Guide breadcrumb pattern
 
 As part of Bootstrap's evolving CSS variables approach, breadcrumbs now use local CSS variables on `.breadcrumb` for enhanced real-time customization. Values for the CSS variables are set via Sass, so Sass customization is still supported, too.
 
-{/* {{< scss-docs name="breadcrumb-css-vars" file="scss/_breadcrumb.scss" >}} */}
+<ScssDocs name="breadcrumb-css-vars" file="scss/_breadcrumb.scss" />
 
 ### Sass variables
 
-{/* {{< scss-docs name="breadcrumb-variables" file="scss/_variables.scss" >}} */}
+<ScssDocs name="breadcrumb-variables" file="scss/_variables.scss" />
diff --git a/site-new/src/content/docs/components/buttons.mdx b/site-new/src/content/docs/components/buttons.mdx
@@ -223,7 +223,7 @@ document.querySelectorAll('.btn').forEach(buttonElement => {
 
 As part of Bootstrap's evolving CSS variables approach, buttons now use local CSS variables on `.btn` for enhanced real-time customization. Values for the CSS variables are set via Sass, so Sass customization is still supported, too.
 
-{/* {{< scss-docs name="btn-css-vars" file="scss/_buttons.scss" >}} */}
+<ScssDocs name="btn-css-vars" file="scss/_buttons.scss" />
 
 Each `.btn-*` modifier class updates the appropriate CSS variables to minimize additional CSS rules with our `button-variant()`, `button-outline-variant()`, and `button-size()` mixins.
 
@@ -233,24 +233,24 @@ Here's an example of building a custom `.btn-*` modifier class like we do for th
   <button type="button" class="btn btn-bd-primary">Custom button</button>
 </div>
 
-{/* {{< scss-docs name="btn-css-vars-example" file="site/assets/scss/_buttons.scss" >}} */}
+<ScssDocs name="btn-css-vars-example" file="site/assets/scss/_buttons.scss" />
 
 ### Sass variables
 
-{/* {{< scss-docs name="btn-variables" file="scss/_variables.scss" >}} */}
+<ScssDocs name="btn-variables" file="scss/_variables.scss" />
 
 ### Sass mixins
 
 There are three mixins for buttons: button and button outline variant mixins (both based on `$theme-colors`), plus a button size mixin.
 
-{/* {{< scss-docs name="btn-variant-mixin" file="scss/mixins/_buttons.scss" >}} */}
+<ScssDocs name="btn-variant-mixin" file="scss/mixins/_buttons.scss" />
 
-{/* {{< scss-docs name="btn-outline-variant-mixin" file="scss/mixins/_buttons.scss" >}} */}
+<ScssDocs name="btn-outline-variant-mixin" file="scss/mixins/_buttons.scss" />
 
-{/* {{< scss-docs name="btn-size-mixin" file="scss/mixins/_buttons.scss" >}} */}
+<ScssDocs name="btn-size-mixin" file="scss/mixins/_buttons.scss" />
 
 ### Sass loops
 
 Button variants (for regular and outline buttons) use their respective mixins with our `$theme-colors` map to generate the modifier classes in `scss/_buttons.scss`.
 
-{/* {{< scss-docs name="btn-variant-loops" file="scss/_buttons.scss" >}} */}
+<ScssDocs name="btn-variant-loops" file="scss/_buttons.scss" />
diff --git a/site-new/src/content/docs/components/card.mdx b/site-new/src/content/docs/components/card.mdx
@@ -732,8 +732,8 @@ In `v4` we used a CSS-only technique to mimic the behavior of [Masonry](https://
 
 As part of Bootstrap's evolving CSS variables approach, cards now use local CSS variables on `.card` for enhanced real-time customization. Values for the CSS variables are set via Sass, so Sass customization is still supported, too.
 
-{/* {{< scss-docs name="card-css-vars" file="scss/_card.scss" >}} */}
+<ScssDocs name="card-css-vars" file="scss/_card.scss" />
 
 ### Sass variables
 
-{/* {{< scss-docs name="card-variables" file="scss/_variables.scss" >}} */}
+<ScssDocs name="card-variables" file="scss/_variables.scss" />
diff --git a/site-new/src/content/docs/components/carousel.mdx b/site-new/src/content/docs/components/carousel.mdx
@@ -353,11 +353,11 @@ The transition duration of `.carousel-item` can be changed with the `$carousel-t
 
 Variables for all carousels:
 
-{/* {{< scss-docs name="carousel-variables" file="scss/_variables.scss" >}} */}
+<ScssDocs name="carousel-variables" file="scss/_variables.scss" />
 
 Variables for the [dark carousel](#dark-variant):
 
-{/* {{< scss-docs name="carousel-dark-variables" file="scss/_variables.scss" >}} */}
+<ScssDocs name="carousel-dark-variables" file="scss/_variables.scss" />
 
 ## Usage
 

diff --git a/site-new/src/content/docs/components/close-button.mdx b/site-new/src/content/docs/components/close-button.mdx
@@ -45,8 +45,8 @@ Add `data-bs-theme="dark"` to the `.btn-close`, or to its parent element, to inv
 
 As part of Bootstrap's evolving CSS variables approach, close button now uses local CSS variables on `.btn-close` for enhanced real-time customization. Values for the CSS variables are set via Sass, so Sass customization is still supported, too.
 
-{/* {{< scss-docs name="close-css-vars" file="scss/_close.scss" >}} */}
+<ScssDocs name="close-css-vars" file="scss/_close.scss" />
 
 ### Sass variables
 
-{/* {{< scss-docs name="close-variables" file="scss/_variables.scss" >}} */}
+<ScssDocs name="close-variables" file="scss/_variables.scss" />
diff --git a/site-new/src/content/docs/components/collapse.mdx b/site-new/src/content/docs/components/collapse.mdx
@@ -104,13 +104,13 @@ Note that Bootstrap's current implementation does not cover the various *optiona
 
 ### Sass variables
 
-{/* {{< scss-docs name="collapse-transition" file="scss/_variables.scss" >}} */}
+<ScssDocs name="collapse-transition" file="scss/_variables.scss" />
 
 ### Classes
 
 Collapse transition classes can be found in `scss/_transitions.scss` as these are shared across multiple components (collapse and accordion).
 
-{/* {{< scss-docs name="collapse-classes" file="scss/_transitions.scss" >}} */}
+<ScssDocs name="collapse-classes" file="scss/_transitions.scss" />
 
 ## Usage
 

diff --git a/site-new/src/content/docs/components/dropdowns.mdx b/site-new/src/content/docs/components/dropdowns.mdx
@@ -1000,7 +1000,7 @@ By default, the dropdown menu is closed when clicking inside or outside the drop
 
 As part of Bootstrap's evolving CSS variables approach, dropdowns now use local CSS variables on `.dropdown-menu` for enhanced real-time customization. Values for the CSS variables are set via Sass, so Sass customization is still supported, too.
 
-{/* {{< scss-docs name="dropdown-css-vars" file="scss/_dropdown.scss" >}} */}
+<ScssDocs name="dropdown-css-vars" file="scss/_dropdown.scss" />
 
 <Callout>
 Dropdown items include at least one variable that is not set on `.dropdown`. This allows you to provide a new value while Bootstrap defaults to a fallback value.
@@ -1010,27 +1010,27 @@ Dropdown items include at least one variable that is not set on `.dropdown`. Thi
 
 Customization through CSS variables can be seen on the `.dropdown-menu-dark` class where we override specific values without adding duplicate CSS selectors.
 
-{/* {{< scss-docs name="dropdown-dark-css-vars" file="scss/_dropdown.scss" >}} */}
+<ScssDocs name="dropdown-dark-css-vars" file="scss/_dropdown.scss" />
 
 ### Sass variables
 
 Variables for all dropdowns:
 
-{/* {{< scss-docs name="dropdown-variables" file="scss/_variables.scss" >}} */}
+<ScssDocs name="dropdown-variables" file="scss/_variables.scss" />
 
 Variables for the [dark dropdown](#dark-dropdowns):
 
-{/* {{< scss-docs name="dropdown-dark-variables" file="scss/_variables.scss" >}} */}
+<ScssDocs name="dropdown-dark-variables" file="scss/_variables.scss" />
 
 Variables for the CSS-based carets that indicate a dropdown's interactivity:
 
-{/* {{< scss-docs name="caret-variables" file="scss/_variables.scss" >}} */}
+<ScssDocs name="caret-variables" file="scss/_variables.scss" />
 
 ### Mixins
 
 Mixins are used to generate the CSS-based carets and can be found in `scss/mixins/_caret.scss`.
 
-{/* {{< scss-docs name="caret-mixins" file="scss/mixins/_caret.scss" >}} */}
+<ScssDocs name="caret-mixins" file="scss/mixins/_caret.scss" />
 
 ## Usage
 

diff --git a/site-new/src/content/docs/components/list-group.mdx b/site-new/src/content/docs/components/list-group.mdx
@@ -311,25 +311,25 @@ You can use `.stretched-link` on `<label>`s to make the whole list group item cl
 
 As part of Bootstrap's evolving CSS variables approach, list groups now use local CSS variables on `.list-group` for enhanced real-time customization. Values for the CSS variables are set via Sass, so Sass customization is still supported, too.
 
-{/* {{< scss-docs name="list-group-css-vars" file="scss/_list-group.scss" >}} */}
+<ScssDocs name="list-group-css-vars" file="scss/_list-group.scss" />
 
 ### Sass variables
 
-{/* {{< scss-docs name="list-group-variables" file="scss/_variables.scss" >}} */}
+<ScssDocs name="list-group-variables" file="scss/_variables.scss" />
 
 ### Sass mixins
 
 <DeprecatedIn version="5.3.0" />
 
 Used in combination with `$theme-colors` to generate the [contextual variant classes](#variants) for `.list-group-item`s.
 
-{/* {{< scss-docs name="list-group-mixin" file="scss/mixins/_list-group.scss" >}} */}
+<ScssDocs name="list-group-mixin" file="scss/mixins/_list-group.scss" />
 
 ### Sass loop
 
 Loop that generates the modifier classes with an overriding of CSS variables.
 
-{/* {{< scss-docs name="list-group-modifiers" file="scss/_list-group.scss" >}} */}
+<ScssDocs name="list-group-modifiers" file="scss/_list-group.scss" />
 
 ## JavaScript behavior
 

diff --git a/site-new/src/content/docs/components/modal.mdx b/site-new/src/content/docs/components/modal.mdx
@@ -779,19 +779,19 @@ Another override is the option to pop up a modal that covers the user viewport,
 
 As part of Bootstrap's evolving CSS variables approach, modals now use local CSS variables on `.modal` and `.modal-backdrop` for enhanced real-time customization. Values for the CSS variables are set via Sass, so Sass customization is still supported, too.
 
-{/* {{< scss-docs name="modal-css-vars" file="scss/_modal.scss" >}} */}
+<ScssDocs name="modal-css-vars" file="scss/_modal.scss" />
 
-{/* {{< scss-docs name="modal-backdrop-css-vars" file="scss/_modal.scss" >}} */}
+<ScssDocs name="modal-backdrop-css-vars" file="scss/_modal.scss" />
 
 ### Sass variables
 
-{/* {{< scss-docs name="modal-variables" file="scss/_variables.scss" >}} */}
+<ScssDocs name="modal-variables" file="scss/_variables.scss" />
 
 ### Loop
 
 [Responsive fullscreen modals](#fullscreen-modal) are generated via the `$breakpoints` map and a loop in `scss/_modal.scss`.
 
-{/* {{< scss-docs name="modal-fullscreen-loop" file="scss/_modal.scss" >}} */}
+<ScssDocs name="modal-fullscreen-loop" file="scss/_modal.scss" />
 
 ## Usage
 

diff --git a/site-new/src/content/docs/components/navbar.mdx b/site-new/src/content/docs/components/navbar.mdx
@@ -791,28 +791,28 @@ When using offcanvas in a dark navbar, be aware that you may need to have a dark
 
 As part of Bootstrap's evolving CSS variables approach, navbars now use local CSS variables on `.navbar` for enhanced real-time customization. Values for the CSS variables are set via Sass, so Sass customization is still supported, too.
 
-{/* {{< scss-docs name="navbar-css-vars" file="scss/_navbar.scss" >}} */}
+<ScssDocs name="navbar-css-vars" file="scss/_navbar.scss" />
 
 Some additional CSS variables are also present on `.navbar-nav`:
 
-{/* {{< scss-docs name="navbar-nav-css-vars" file="scss/_navbar.scss" >}} */}
+<ScssDocs name="navbar-nav-css-vars" file="scss/_navbar.scss" />
 
 Customization through CSS variables can be seen on the `.navbar-dark` class where we override specific values without adding duplicate CSS selectors.
 
-{/* {{< scss-docs name="navbar-dark-css-vars" file="scss/_navbar.scss" >}} */}
+<ScssDocs name="navbar-dark-css-vars" file="scss/_navbar.scss" />
 
 ### Sass variables
 
 Variables for all navbars:
 
-{/* {{< scss-docs name="navbar-variables" file="scss/_variables.scss" >}} */}
+<ScssDocs name="navbar-variables" file="scss/_variables.scss" />
 
 Variables for the [dark navbar](#color-schemes):
 
-{/* {{< scss-docs name="navbar-dark-variables" file="scss/_variables.scss" >}} */}
+<ScssDocs name="navbar-dark-variables" file="scss/_variables.scss" />
 
 ### Sass loop
 
 [Responsive navbar expand/collapse classes](#responsive-behaviors) (e.g., `.navbar-expand-lg`) are combined with the `$breakpoints` map and generated through a loop in `scss/_navbar.scss`.
 
-{/* {{< scss-docs name="navbar-expand-loop" file="scss/_navbar.scss" >}} */}
+<ScssDocs name="navbar-expand-loop" file="scss/_navbar.scss" />
diff --git a/site-new/src/content/docs/components/navs-tabs.mdx b/site-new/src/content/docs/components/navs-tabs.mdx
@@ -336,25 +336,25 @@ As part of Bootstrap's evolving CSS variables approach, navs now use local CSS v
 
 On the `.nav` base class:
 
-{/* {{< scss-docs name="nav-css-vars" file="scss/_nav.scss" >}} */}
+<ScssDocs name="nav-css-vars" file="scss/_nav.scss" />
 
 On the `.nav-tabs` modifier class:
 
-{/* {{< scss-docs name="nav-tabs-css-vars" file="scss/_nav.scss" >}} */}
+<ScssDocs name="nav-tabs-css-vars" file="scss/_nav.scss" />
 
 On the `.nav-pills` modifier class:
 
-{/* {{< scss-docs name="nav-pills-css-vars" file="scss/_nav.scss" >}} */}
+<ScssDocs name="nav-pills-css-vars" file="scss/_nav.scss" />
 
 <AddedIn version="5.3.0" />
 
 On the `.nav-underline` modifier class:
 
-{/* {{< scss-docs name="nav-underline-css-vars" file="scss/_nav.scss" >}} */}
+<ScssDocs name="nav-underline-css-vars" file="scss/_nav.scss" />
 
 ### Sass variables
 
-{/* {{< scss-docs name="nav-variables" file="scss/_variables.scss" >}} */}
+<ScssDocs name="nav-variables" file="scss/_variables.scss" />
 
 ## JavaScript behavior