diff --git a/scss/_utilities.scss b/scss/_utilities.scss index 153a02eddf..03e3b107e5 100644 --- a/scss/_utilities.scss +++ b/scss/_utilities.scss @@ -704,12 +704,14 @@ $utilities: map.merge( class: text, values: wrap nowrap balance pretty, ), + // scss-docs-start utils-text-break "word-wrap": ( property: word-wrap word-break, class: text, values: (break: break-word), rtl: false ), + // scss-docs-end utils-text-break // scss-docs-end utils-text // scss-docs-start utils-color // "color-attr": ( diff --git a/site/src/components/ReferenceTable.astro b/site/src/components/ReferenceTable.astro index 4578a66d22..c98d1528ad 100644 --- a/site/src/components/ReferenceTable.astro +++ b/site/src/components/ReferenceTable.astro @@ -1,7 +1,6 @@ --- import { readFileSync } from 'node:fs'; -import { fileURLToPath } from 'node:url'; -import { dirname, join } from 'node:path'; +import { join } from 'node:path'; interface ReferenceItem { class: string; @@ -31,9 +30,8 @@ const referenceData = reference || data || []; // Parse CSS variables from _root.scss at build time function parseCSSVariables(): Record { try { - const __filename = fileURLToPath(import.meta.url); - const __dirname = dirname(__filename); - const rootScssPath = join(__dirname, '../../../scss/_root.scss'); + const projectRoot = process.cwd(); + const rootScssPath = join(projectRoot, 'scss/_root.scss'); const scssContent = readFileSync(rootScssPath, 'utf-8'); const cssVarValues: Record = {}; diff --git a/site/src/components/UtilityReferenceTable.astro b/site/src/components/UtilityReferenceTable.astro index 134ac217b3..b41902aeaf 100644 --- a/site/src/components/UtilityReferenceTable.astro +++ b/site/src/components/UtilityReferenceTable.astro @@ -1,7 +1,6 @@ --- import { readFileSync } from 'node:fs'; -import { fileURLToPath } from 'node:url'; -import { dirname, join } from 'node:path'; +import { join } from 'node:path'; interface Props { utility: string | string[]; // The utility key(s) from the metadata (e.g., "font-size" or ["font-size", "text-size"]) @@ -19,9 +18,8 @@ const utilities = Array.isArray(utility) ? utility : [utility]; // Parse CSS variables from _root.scss at build time function parseCSSVariables(): Record { try { - const __filename = fileURLToPath(import.meta.url); - const __dirname = dirname(__filename); - const rootScssPath = join(__dirname, '../../../scss/_root.scss'); + const projectRoot = process.cwd(); + const rootScssPath = join(projectRoot, 'scss/_root.scss'); const scssContent = readFileSync(rootScssPath, 'utf-8'); const cssVarValues: Record = {}; @@ -49,9 +47,8 @@ function parseCSSVariables(): Record { // Load utilities metadata function loadUtilitiesMetadata(): any { try { - const __filename = fileURLToPath(import.meta.url); - const __dirname = dirname(__filename); - const metadataPath = join(__dirname, '../../../dist/css/bootstrap-utilities.metadata.json'); + const projectRoot = process.cwd(); + const metadataPath = join(projectRoot, 'dist/css/bootstrap-utilities.metadata.json'); const metadataContent = readFileSync(metadataPath, 'utf-8'); return JSON.parse(metadataContent); } catch (error) { @@ -63,9 +60,8 @@ function loadUtilitiesMetadata(): any { // Parse compiled CSS to extract styles for given class selectors function parseCompiledCSS(classNames: string[]): Record { try { - const __filename = fileURLToPath(import.meta.url); - const __dirname = dirname(__filename); - const bootstrapCssPath = join(__dirname, '../../../dist/css/bootstrap.css'); + const projectRoot = process.cwd(); + const bootstrapCssPath = join(projectRoot, 'dist/css/bootstrap.css'); const cssContent = readFileSync(bootstrapCssPath, 'utf-8'); const classStyles: Record = {}; diff --git a/site/src/components/home/ComponentUtilities.astro b/site/src/components/home/ComponentUtilities.astro index b54d4e4084..8571627f03 100644 --- a/site/src/components/home/ComponentUtilities.astro +++ b/site/src/components/home/ComponentUtilities.astro @@ -28,7 +28,7 @@ import Code from '@shortcodes/Code.astro' Apply any of our included utility classes to our components to customize their appearance, like the navigation example below. There are hundreds of classes available—from positioning and sizing to and sizing to colors and effects. Mix them with CSS variable overrides for even more control. diff --git a/site/src/components/shortcodes/DETAILS_README.md b/site/src/components/shortcodes/DETAILS_README.md new file mode 100644 index 0000000000..f7d10eaf94 --- /dev/null +++ b/site/src/components/shortcodes/DETAILS_README.md @@ -0,0 +1,126 @@ +# Details Component + +The Details component is an expandable/collapsible content component that looks similar to the Callout component but requires a click to reveal the full content. It uses the native HTML `
` and `` elements under the hood. + +## Features + +- **Expandable/Collapsible**: Content is hidden by default and expands when the summary is clicked +- **Markdown Support**: Can reference external `.md` files using the `name` prop +- **Flexible Content**: Accepts inline content via slot or named markdown files +- **Simple Styling**: Single, unified design that works everywhere + +## Usage + +### Basic Usage with Inline Content + +```astro +
+ This is the content that will be hidden until the user clicks the summary. +
+``` + +### With Named Content (External Markdown File) + +Create a markdown file in `site/src/content/details/` with a `title` in the frontmatter: + +```markdown + +--- +title: Click to see more +--- + +**This is the content** from an external markdown file. + +It supports full markdown formatting including: +- Lists +- Links +- **Bold** and *italic* text +``` + +Then use it in your component (the title from frontmatter will be used as the summary): + +```astro +
+``` + +You can also override the title with a custom summary: + +```astro +
+``` + +### With Markdown Formatting in Slot + +```astro +
+ You can use **markdown** formatting, including: + + - Lists + - [Links](#) + - `code` + - And more! +
+``` + +## Props + +| Prop | Type | Default | Description | +|------|------|---------|-------------| +| `summary` | `string` | *Optional* | The text displayed in the summary (always visible). If not provided, uses the `title` from the markdown frontmatter when `name` is set. | +| `name` | `string` | `undefined` | Reference to a markdown file in `src/content/details/` | + +**Note:** Either `summary` must be provided, or `name` must reference a markdown file with a `title` in its frontmatter. + +## Creating Named Content Files + +1. Create a new `.md` file in `site/src/content/details/` +2. Add a `title` in the frontmatter for the summary text +3. Write your markdown content +4. Reference it using the `name` prop (without the `.md` extension) + +Example: + +```bash +# Create the file +cat > site/src/content/details/api-notes.md << EOF +--- +title: API Authentication Notes +--- + +**API Note:** This endpoint requires authentication. +EOF +``` + +```astro + +
+ + +
+``` + +## Styling + +The Details component has a simple, unified style: +- `.bd-details` - Base class with neutral, theme-aware styling +- Uses Bootstrap's tertiary background color +- Automatically adapts to light and dark modes + +The styling is defined in `site/src/scss/_details.scss`. + +## Examples + +See the [Docs Reference](/docsref/) page for live examples of the Details component in action. + +## When to Use + +**Use Details when:** +- Content is supplementary and doesn't need to be immediately visible +- You want to reduce visual clutter on the page +- Information is relevant but not critical to understanding the main content +- You're documenting edge cases, advanced tips, or optional information + +**Use Callout instead when:** +- Information must be immediately visible +- Content is critical to user success +- You want to draw immediate attention to important information diff --git a/site/src/content/docs/components/card.mdx b/site/src/content/docs/components/card.mdx index 9f2fa7d1eb..5ba69abe5e 100644 --- a/site/src/content/docs/components/card.mdx +++ b/site/src/content/docs/components/card.mdx @@ -208,7 +208,7 @@ Using the grid, wrap cards in columns and rows as needed. ### Using utilities -Use our handful of [available sizing utilities]([[docsref:/utilities/sizing]]) to quickly set a card’s width. +Use our handful of [available sizing utilities]([[docsref:/utilities/width]]) to quickly set a card’s width.
@@ -240,7 +240,7 @@ Use custom CSS in your stylesheets or as inline styles to set a width. ## Text alignment -You can quickly change the text alignment of any card—in its entirety or specific parts—with our [text align classes]([[docsref:/utilities/text#text-alignment]]). +You can quickly change the text alignment of any card—in its entirety or specific parts—with our [text align classes]([[docsref:/utilities/text-alignment]]).
diff --git a/site/src/content/docs/components/collapse.mdx b/site/src/content/docs/components/collapse.mdx index 8124c492f3..168e5e46c0 100644 --- a/site/src/content/docs/components/collapse.mdx +++ b/site/src/content/docs/components/collapse.mdx @@ -36,7 +36,7 @@ Generally, we recommend using a `
-
- -
- -
- ## Code example ```scss diff --git a/site/src/content/docs/utilities/api.mdx b/site/src/content/docs/utilities/api.mdx index 1604a91d97..0b3e67c012 100644 --- a/site/src/content/docs/utilities/api.mdx +++ b/site/src/content/docs/utilities/api.mdx @@ -85,7 +85,7 @@ Output: Use the `values` key to specify which values for the specified `property` should be used in the generated class names and rules. Can be a list or map (set in the utilities or in a Sass variable). -As a list, like with [`text-decoration` utilities]([[docsref:/utilities/text#text-decoration]]): +As a list, like with [`text-decoration` utilities]([[docsref:/utilities/text-decoration]]): ```scss values: none underline line-through diff --git a/site/src/content/docs/utilities/border-color.mdx b/site/src/content/docs/utilities/border-color.mdx index de6b8458d4..b33cfae059 100644 --- a/site/src/content/docs/utilities/border-color.mdx +++ b/site/src/content/docs/utilities/border-color.mdx @@ -6,7 +6,6 @@ alias: - /docs/5.3/utilities/border-color/ mdn: https://developer.mozilla.org/en-US/docs/Web/CSS/border-color utility: - - border-attr - border-color - border-color-subtle - border-opacity diff --git a/site/src/content/docs/utilities/sizing.mdx b/site/src/content/docs/utilities/sizing.mdx deleted file mode 100644 index d06c3c7f6c..0000000000 --- a/site/src/content/docs/utilities/sizing.mdx +++ /dev/null @@ -1,63 +0,0 @@ ---- -title: Sizing -description: Easily make an element as wide or as tall with our width and height utilities. -toc: true -utility: - - width - - height - - max-width - - max-height - - min-width - - min-height - - viewport-width - - viewport-height - - min-viewport-width - - min-viewport-height ---- - -## Relative to the parent - -Width and height utilities are generated from the utility API in `_utilities.scss`. Includes support for `25%`, `50%`, `75%`, `100%`, and `auto` by default. Modify those values as you need to generate different utilities here. - -Width 25% -
Width 50%
-
Width 75%
-
Width 100%
-
Width auto
`} /> - - -
Height 25%
-
Height 50%
-
Height 75%
-
Height 100%
-
Height auto
- `} /> - -You can also use `max-width: 100%;` and `max-height: 100%;` utilities as needed. - - -
Max-width 100%
- `} /> - - -
Max-height 100%
- `} /> - -## Relative to the viewport - -You can also use utilities to set the width and height relative to the viewport. - -```html -
Min-width 100vw
-
Min-height 100vh
-
Width 100vw
-
Height 100vh
-``` - -## CSS - -### Sass utilities API - -Sizing utilities are declared in our utilities API in `scss/_utilities.scss`. [Learn how to use the utilities API.]([[docsref:/utilities/api#using-the-api]]) - - diff --git a/site/src/content/docs/utilities/word-break.mdx b/site/src/content/docs/utilities/word-break.mdx index 73f69adfd9..f583be9d07 100644 --- a/site/src/content/docs/utilities/word-break.mdx +++ b/site/src/content/docs/utilities/word-break.mdx @@ -3,7 +3,7 @@ title: Word break description: Prevent long strings of text from breaking your components' layout by using word break utilities. toc: true utility: - - text-break + - word-wrap --- Prevent long strings of text from breaking your components' layout by using `.text-break` to set `word-wrap: break-word` and `word-break: break-word`. We use `word-wrap` instead of the more common `overflow-wrap` for wider browser support, and add the deprecated `word-break: break-word` to avoid issues with flex containers.