diff --git a/scss/content/_prose.scss b/scss/content/_prose.scss new file mode 100644 index 0000000000..bc9b40e39f --- /dev/null +++ b/scss/content/_prose.scss @@ -0,0 +1,137 @@ +@use "../config" as *; +@use "../mixins/transition" as *; + +@layer content { + .prose { + --#{$prefix}content-font-size: 16px; + --#{$prefix}content-gap: 24px; + --#{$prefix}heading-color: light-dark(var(--bs-gray-900), var(--bs-white)); + + position: relative; + max-width: 1000px; + margin-inline: auto; + font-size: var(--#{$prefix}content-font-size); + line-height: var(--#{$prefix}content-gap); + + p, + ul, + ol, + dl, + pre, + table, + blockquote { + margin-bottom: var(--#{$prefix}content-gap); + } + + li:not(:last-child) { + margin-bottom: calc(var(--#{$prefix}content-gap) / 4); + } + + li ul, + li ol { + margin-top: calc(var(--#{$prefix}content-gap) / 4); + } + + hr { + margin: calc(var(--#{$prefix}content-gap) * 1.5) 0; + border: 0; + border-top: 1px solid var(--#{$prefix}border-color); + } + + h1, + h2, + h3, + h4, + h5, + h6 { + --bs-heading-color: var(--bs-emphasis-color); + + margin-top: 0; + margin-bottom: calc(var(--#{$prefix}content-gap) / 2); + font-weight: 500; + line-height: 1.25; + } + + h1, + h2 { + &:not(:first-child) { + margin-top: calc(var(--#{$prefix}content-gap) * 1.5); + } + } + + h3, + h4, + h5, + h6 { + &:not(:first-child) { + margin-top: calc(var(--#{$prefix}content-gap) * 1.25); + } + } + + h1 { + font-size: 2.25em; + line-height: 1.1; + } + h2 { + font-size: 1.75em; + } + h3 { + margin-bottom: calc(var(--#{$prefix}content-gap) / 4); + font-size: 1.5em; + } + h4 { + font-size: 1.25em; + } + h5 { + font-size: 1.125em; + } + h6 { + font-size: 1em; + } + + a:not([class]) { + color: var(--#{$prefix}link-color); + text-decoration: underline; + text-decoration-color: color-mix(in srgb, var(--#{$prefix}link-color) 25%, transparent); + text-underline-offset: 4px; + @include transition(.1s text-decoration-color ease-in-out); + } + + a:not([class]):hover { + text-decoration-color: var(--#{$prefix}link-hover-color); + } + + img { + max-width: 100%; + } + + blockquote { + padding-left: calc(var(--#{$prefix}content-gap) / 2); + margin: 0; + border-left: 4px solid var(--#{$prefix}border-color); + } + + table { + width: 100%; + border-spacing: 0; + border-collapse: collapse; + } + + td, + th { + padding: 6px 12px; + text-align: inherit; + border: 1px solid var(--#{$prefix}border-color); + } + + + dt { + font-weight: 500; + } + + video, + img { + max-width: 100%; + } + } +} diff --git a/scss/content/index.scss b/scss/content/index.scss index e643f1b393..8b141c949c 100644 --- a/scss/content/index.scss +++ b/scss/content/index.scss @@ -2,3 +2,4 @@ @forward "type"; @forward "tables"; @forward "images"; +@forward "prose"; diff --git a/site/data/sidebar.yml b/site/data/sidebar.yml index c9857989f0..61cfd55260 100644 --- a/site/data/sidebar.yml +++ b/site/data/sidebar.yml @@ -54,6 +54,7 @@ - title: Images - title: Tables - title: Figures + - title: Prose - title: Forms icon: ui-radios diff --git a/site/src/content/docs/content/prose.mdx b/site/src/content/docs/content/prose.mdx new file mode 100644 index 0000000000..4eb60c613b --- /dev/null +++ b/site/src/content/docs/content/prose.mdx @@ -0,0 +1,127 @@ +--- +title: Prose +description: Use the `.prose` wrapper class to make long form content more easily without the need for specifying Bootstrap classes on every element. Especially useful for converting Markdown or MDX to HTML, or simply for making content heavy pages more readable. +toc: true +--- + +## How it works + +Wrap your content in the `.prose` class to get modified font-size, line-height, and spacing specifically designed for long form content that originals from source Markdown files or WYSIWYG editors. Here's what we do with that class: + +- Set a base `font-size`, `line-height`, and some local CSS variables on the parent element. +- Normalize the spacing of lists +- Set a default `margin-bottom` for headings. +- Some headings get an additional `margin-top` to ensure proper spacing between headings and other content. +- Style blockquotes, code, and other inline elements. + +## Example + +This is an example of source Markdown that shows several types of HTML content supported in this `.prose` wrapper class. + +
+ +
+# Getting started with documentation +Writing clear and effective documentation is essential for any project. When you create content that others will read and use, [proper formatting](#) makes all the difference. *Good documentation* helps users understand complex concepts quickly and efficiently. + +> Documentation is a love letter that you write to your future self. Clear writing today saves countless hours of confusion tomorrow. + +The foundation of great documentation starts with **understanding your audience** and their needs. Writers should focus on clarity, consistency, and providing practical examples that readers can follow. + +## Inline HTML elements + +HTML defines a long list of available inline tags, a complete list of which can be found on the [Mozilla Developer Network](https://developer.mozilla.org/en-US/docs/Web/HTML/Element). + +- **To bold text**, use ``. +- *To italicize text*, use ``. +- To highlight, use ``. +- Abbreviations, like HTML should use ``, with an optional `title` attribute for the full phrase. +- Citations, like — Mark Otto, should use ``. +- Deleted text should use `` and inserted text should use ``. +- Superscript text uses `` and subscript text uses ``. + +Most of these elements are styled by browsers with few modifications on our part. + +## Heading + +Effective documentation requires careful attention to structure and flow. When organizing content, consider how readers will navigate through your material and what information they need first. Clear headings help users scan quickly and find relevant sections. + +### Code + +Inline code is available with the `` element. Snippets of multiple lines of code are supported through Rouge. Longer lines will automatically scroll horizontally when needed. You may also use code fencing (triple backticks) for rendering code. + +```js +// Example can be run directly in your JavaScript console + +// Create a function that takes two arguments and returns the sum of those arguments +var adder = new Function("a", "b", "return a + b"); + +// Call the function +adder(2, 6); +// > 8 +``` + +Code examples should be practical and directly related to the concepts being explained. Always test your code snippets to ensure they work as expected before including them in documentation. + +### Lists + +When presenting information in lists, consider whether the order matters. Use numbered lists for sequential steps and bullet points for related items that don't require a specific order. + +- Write clear, concise list items that focus on one concept each. +- Use parallel structure across all items in your list. +- Keep list items roughly the same length when possible. + +Consistency in formatting helps readers process information more efficiently. + +1. Start with the most important information first. +2. Provide context before diving into technical details. +3. Include practical examples that readers can apply immediately. + +Well-structured content makes complex topics more accessible to readers with varying levels of expertise. + +- Document your processes and decisions for future reference. + - Include reasoning behind important choices you made. + - Note any alternative approaches you considered. + - Record lessons learned during implementation. +- Update documentation regularly as your project evolves. +- Test documentation with actual users to identify gaps. + +Regular maintenance ensures your documentation remains accurate and helpful over time. + +
+
HyperText Markup Language (HTML)
+
The language used to describe and define the content of a Web page
+ +
Cascading Style Sheets (CSS)
+
Used to describe the appearance of Web content
+ +
JavaScript (JS)
+
The programming language used to build advanced Web sites and applications
+
+ +Technical definitions should be clear and accessible to your target audience. Avoid jargon when simpler terms will convey the same meaning effectively. + +### Images + +Visual elements enhance understanding by providing concrete examples of abstract concepts. Choose images that directly support your written content rather than serving as mere decoration. + + + + + + + +### Tables + +Tables work best for comparing related data points or presenting structured information that benefits from a grid layout. + +| Name | Up-votes | Down-votes | +|---------|---------|-----------| +| Alice | 10 | 11 | +| Bob | 4 | 3 | +| Charlie | 7 | 9 | +| Totals | 21 | 23 | + +Keep table headers descriptive and consider the reading order when arranging columns. Simple tables are easier to understand and maintain than complex ones. + +