Add a `not-content` CSS class for opting out of default styles (#313)

Co-authored-by: Paul Valladares <85648028+dreyfus92@users.noreply.github.com>

6 files changed, 74 insertions, 42 deletions

diff --git a/.changeset/clean-lamps-juggle.md b/.changeset/clean-lamps-juggle.md
new file mode 100644
index 00000000..cbbc92ad
--- /dev/null
+++ b/.changeset/clean-lamps-juggle.md
@@ -0,0 +1,5 @@
+---
+'@astrojs/starlight': minor
+---
+
+Add a `not-content` CSS class that allows users to opt out of Starlight’s default content styling
diff --git a/docs/src/components/about-astro.astro b/docs/src/components/about-astro.astro
index fb1815a1..4d661444 100644
--- a/docs/src/components/about-astro.astro
+++ b/docs/src/components/about-astro.astro
@@ -6,7 +6,7 @@ interface Props {
 const { title } = Astro.props;
 ---
 
-<article class="flex" aria-labelledby="about-astro-heading">
+<article class="flex not-content" aria-labelledby="about-astro-heading">
   <small id="about-astro-heading">
     {title}
     <span class="sr-only">Astro</span>
@@ -36,7 +36,6 @@ const { title } = Astro.props;
     gap: 0.5rem;
   }
   article > :global(*) {
-    margin-top: 0 !important;
     max-width: 50ch;
   }
   small {
diff --git a/docs/src/components/file-tree.astro b/docs/src/components/file-tree.astro
index b2158bdd..238fa7cb 100644
--- a/docs/src/components/file-tree.astro
+++ b/docs/src/components/file-tree.astro
@@ -17,7 +17,11 @@ const processedContent = await fileTreeProcessor.process({
 });
 ---
 
-<file-tree set:html={processedContent} data-pagefind-ignore />
+<file-tree
+  set:html={processedContent}
+  class="not-content"
+  data-pagefind-ignore
+/>
 
 <style is:global>
   file-tree {
@@ -36,7 +40,6 @@ const processedContent = await fileTreeProcessor.process({
   file-tree .directory > details,
   file-tree .directory > details:hover,
   file-tree .directory > details[open] {
-    margin: 0 !important;
     border: 0;
     padding: 0;
     padding-inline-start: var(--x-space);
@@ -65,9 +68,8 @@ const processedContent = await fileTreeProcessor.process({
     fill: var(--sl-color-text-accent);
   }
 
-  file-tree ul:is(ul),
-  file-tree .directory > details ul:is(ul) {
-    margin: 0;
+  file-tree ul,
+  file-tree .directory > details ul {
     margin-inline-start: 0.6875rem;
     border-inline-start: 1px solid var(--sl-color-gray-5);
     padding: 0;
@@ -79,14 +81,13 @@ const processedContent = await fileTreeProcessor.process({
     border-color: var(--sl-color-gray-4);
   }
 
-  file-tree > ul:is(ul) {
+  file-tree > ul {
     margin: 0;
     border: 0;
     padding: 0;
   }
 
-  file-tree li:is(li) {
-    margin: 0;
+  file-tree li {
     padding: var(--y-pad) 0;
   }
 
diff --git a/docs/src/content/docs/guides/components.mdx b/docs/src/content/docs/guides/components.mdx
index 0ed73557..227692e5 100644
--- a/docs/src/content/docs/guides/components.mdx
+++ b/docs/src/content/docs/guides/components.mdx
@@ -33,6 +33,20 @@ import AnotherComponent from '../../components/AnotherComponent.astro';
 Because Starlight is powered by Astro, you can add support for components built with any [supported UI framework (React, Preact, Svelte, Vue, Solid, Lit, and Alpine)](https://docs.astro.build/en/core-concepts/framework-components/) in your MDX files.
 Learn more about [using components in MDX](https://docs.astro.build/en/guides/markdown-content/#using-components-in-mdx) in the Astro docs.
 
+### Compatibility with Starlight’s styles
+
+Starlight applies default styling to your Markdown content, for example adding margin between elements.
+If these styles conflict with your component’s appearance, set the `not-content` class on your component to disable them.
+
+```astro
+---
+// src/components/Example.astro
+---
+<div class="not-content">
+  <p>Not impacted by Starlight’s default content styling.</p>
+</div>
+```
+
 ## Built-in components
 
 Starlight provides some built-in components for common documentation use cases.
diff --git a/packages/starlight/components/MarkdownContent.astro b/packages/starlight/components/MarkdownContent.astro
index af98fde1..85d7d692 100644
--- a/packages/starlight/components/MarkdownContent.astro
+++ b/packages/starlight/components/MarkdownContent.astro
@@ -2,78 +2,94 @@
 
 <style>
   .content
-    :global(
+    > :global(
       :not(a, strong, em, del, span, input)
-        + :not(a, strong, em, del, span, input)
+        + :not(a, strong, em, del, span, input, :where(.not-content *))
     ) {
     margin-top: 1.5rem;
   }
 
   /* Headings after non-headings have more spacing. */
-  .content :global(:not(h1, h2, h3, h4, h5, h6) + :is(h1, h2, h3, h4, h5, h6)) {
+  .content
+    :global(
+      :not(h1, h2, h3, h4, h5, h6)
+        + :is(h1, h2, h3, h4, h5, h6):not(:where(.not-content *))
+    ) {
     margin-top: 2.5rem;
   }
 
-  .content :global(li + li),
-  .content :global(dt + dt),
-  .content :global(dt + dd),
-  .content :global(dd + dd) {
+  .content :global(li + li:not(:where(.not-content *))),
+  .content :global(dt + dt:not(:where(.not-content *))),
+  .content :global(dt + dd:not(:where(.not-content *))),
+  .content :global(dd + dd:not(:where(.not-content *))) {
     margin-top: 0.25rem;
   }
 
   .content
     :global(
-      li > :last-child:not(li, ul, ol):not(a, strong, em, del, span, input)
+      li
+        > :last-child:not(li, ul, ol):not(
+          a,
+          strong,
+          em,
+          del,
+          span,
+          input,
+          :where(.not-content *)
+        )
     ) {
     margin-bottom: 1.25rem;
   }
 
-  .content :global(dt) {
+  .content :global(dt:not(:where(.not-content *))) {
     font-weight: 700;
   }
-  .content :global(dd) {
+  .content :global(dd:not(:where(.not-content *))) {
     padding-inline-start: 1rem;
   }
 
-  .content :global(:is(h1, h2, h3, h4, h5, h6)) {
+  .content :global(:is(h1, h2, h3, h4, h5, h6):not(:where(.not-content *))) {
     color: var(--sl-color-white);
     line-height: var(--sl-line-height-headings);
     font-weight: 600;
   }
 
-  .content :global(:is(img, picture, video, canvas, svg, iframe)) {
+  .content
+    :global(
+      :is(img, picture, video, canvas, svg, iframe):not(:where(.not-content *))
+    ) {
     display: block;
     max-width: 100%;
     height: auto;
   }
 
-  .content :global(h1) {
+  .content :global(h1:not(:where(.not-content *))) {
     font-size: var(--sl-text-h1);
   }
-  .content :global(h2) {
+  .content :global(h2:not(:where(.not-content *))) {
     font-size: var(--sl-text-h2);
   }
-  .content :global(h3) {
+  .content :global(h3:not(:where(.not-content *))) {
     font-size: var(--sl-text-h3);
   }
-  .content :global(h4) {
+  .content :global(h4:not(:where(.not-content *))) {
     font-size: var(--sl-text-h4);
   }
-  .content :global(h5) {
+  .content :global(h5:not(:where(.not-content *))) {
     font-size: var(--sl-text-h5);
   }
-  .content :global(h6) {
+  .content :global(h6:not(:where(.not-content *))) {
     font-size: var(--sl-text-h6);
   }
 
-  .content :global(a) {
+  .content :global(a:not(:where(.not-content *))) {
     color: var(--sl-color-text-accent);
   }
-  .content :global(a:hover) {
+  .content :global(a:hover:not(:where(.not-content *))) {
     color: var(--sl-color-white);
   }
 
-  .content :global(code) {
+  .content :global(code:not(:where(.not-content *))) {
     background-color: var(--sl-color-bg-inline-code);
     margin-block: -0.125rem;
     padding: 0.125rem 0.375rem;
@@ -83,36 +99,36 @@
     font-size: inherit;
   }
 
-  .content :global(pre) {
+  .content :global(pre:not(:where(.not-content *))) {
     border: 1px solid var(--sl-color-gray-5);
     padding: 0.75rem 1rem;
     font-size: var(--sl-text-code);
   }
 
-  .content :global(pre code) {
+  .content :global(pre code:not(:where(.not-content *))) {
     all: unset;
     font-family: var(--__sl-font-mono);
   }
 
-  .content :global(blockquote) {
+  .content :global(blockquote:not(:where(.not-content *))) {
     border-inline-start: 1px solid var(--sl-color-gray-5);
     padding-inline-start: 1rem;
   }
 
-  .content :global(table) {
+  .content :global(table:not(:where(.not-content *))) {
     display: block;
     overflow: auto;
     border-collapse: collapse;
   }
-  .content :global(tr:nth-child(2n)) {
+  .content :global(tr:nth-child(2n):not(:where(.not-content *))) {
     background-color: var(--sl-color-gray-7, var(--sl-color-gray-6));
   }
-  .content :global(:is(th, td)) {
+  .content :global(:is(th, td):not(:where(.not-content *))) {
     border: 1px solid var(--sl-color-hairline);
     padding: 0.375rem 0.8125rem;
   }
 
-  .content :global(hr) {
+  .content :global(hr:not(:where(.not-content *))) {
     border: 0;
     border-bottom: 1px solid var(--sl-color-hairline);
   }
diff --git a/packages/starlight/user-components/Tabs.astro b/packages/starlight/user-components/Tabs.astro
index 3dc7f096..b0a2c5a5 100644
--- a/packages/starlight/user-components/Tabs.astro
+++ b/packages/starlight/user-components/Tabs.astro
@@ -8,7 +8,7 @@ const { html, panels } = processPanels(panelHtml);
 <starlight-tabs>
   {
     panels && (
-      <div class="tablist-wrapper">
+      <div class="tablist-wrapper not-content">
         <ul role="tablist">
           {panels.map(({ label, panelId, tabId }, idx) => (
             <li role="presentation" class="tab">
@@ -46,9 +46,6 @@ const { html, panels } = processPanels(panelHtml);
     padding: 0;
   }
 
-  [role='tablist'] .tab + .tab {
-    margin-top: 0;
-  }
   .tab {
     margin-bottom: -2px;
   }