@minidocs/astro 0.0.0-stage → 0.1.0

package/src/styles/layout.css

@@ -0,0 +1,406 @@
+/* Page layout: where the header, sidebar, content and aside go, and how that changes with the screen width. */
+@layer minidocs {
+  /* The page itself takes the minidocs look only when it uses Layout.Root */
+  :root:has(.md-layout) {
+    color-scheme: light dark;
+    background: var(--md-color-bg);
+    color: var(--md-color-text);
+    font-family: var(--md-font-sans);
+    -webkit-font-smoothing: antialiased;
+  }
+
+  :root:has(.md-layout) body {
+    margin: 0;
+  }
+
+  /* The outer columns center the content and let the header background span the whole width */
+  /* Biome's noInvalidGridAreas reports these area templates as inconsistent although they are not, so biome.json turns it off for this file */
+  /* The aside column stays on pages without a table of contents, so the sidebar and the content never move between pages */
+  .md-layout {
+    --md-layout-gap: 3.5rem;
+    display: grid;
+    grid-template-columns:
+      [full-start] minmax(0, 1fr)
+      [content-start] var(--md-layout-sidebar-width) minmax(0, var(--md-layout-main-width)) var(--md-layout-aside-width)
+      [content-end] minmax(0, 1fr) [full-end];
+    grid-template-rows: auto 1fr;
+    grid-template-areas:
+      "header header header header header"
+      ". sidebar main aside .";
+    column-gap: var(--md-layout-gap);
+    min-height: 100dvh;
+  }
+
+  .md-layout-header {
+    position: sticky;
+    top: 0;
+    z-index: 40;
+    grid-area: header;
+    display: grid;
+    grid-template-columns: subgrid;
+    height: var(--md-header-height);
+    border-block-end: 1px solid var(--md-color-border);
+    background: color-mix(in srgb, var(--md-color-bg) 88%, transparent);
+    backdrop-filter: blur(12px);
+  }
+
+  .md-layout-header-inner {
+    grid-column: content-start / content-end;
+    display: flex;
+    align-items: center;
+    gap: 0.75rem;
+    min-width: 0;
+  }
+
+  .md-layout-title {
+    display: inline-flex;
+    align-items: center;
+    gap: 0.5rem;
+    color: var(--md-color-heading);
+    font-size: 1.0625rem;
+    font-weight: 650;
+    letter-spacing: -0.02em;
+    text-decoration: none;
+  }
+
+  .md-layout-title:focus-visible {
+    border-radius: 2px;
+    outline: var(--md-focus-ring);
+    outline-offset: 4px;
+  }
+
+  .md-layout-header-end {
+    display: flex;
+    align-items: center;
+    gap: 0.5rem;
+    margin-inline-start: auto;
+  }
+
+  /* The trigger is only needed where the sidebar is a drawer */
+  .md-layout .md-sidebar-trigger {
+    display: none;
+  }
+
+  .md-layout-sidebar,
+  .md-layout-aside {
+    position: sticky;
+    top: var(--md-header-height);
+    align-self: start;
+    box-sizing: border-box;
+    max-height: calc(100dvh - var(--md-header-height));
+    padding-block: 2rem;
+    overflow-y: auto;
+  }
+
+  /* Pulls sidebar items out by their own padding, so their text lines up with the header */
+  .md-layout-sidebar {
+    grid-area: sidebar;
+    margin-inline: calc(-1 * var(--md-sidebar-item-padding-inline));
+    padding-inline: 0.125rem;
+  }
+
+  .md-layout-main {
+    grid-area: main;
+    min-width: 0;
+    padding-block: 2.5rem 5rem;
+  }
+
+  /* Lowest specificity, so the spacing of the parts inside always wins */
+  :where(.md-layout-main) > :where(* + *) {
+    margin-block-start: 2rem;
+  }
+
+  .md-layout .md-prose :is(h1, h2, h3, h4, h5, h6) {
+    scroll-margin-top: calc(var(--md-header-height) + 1.5rem);
+  }
+
+  /* attachAside reads this to tell whether the aside can collapse, so widths are only defined here */
+  .md-layout-aside {
+    --md-layout-aside-collapsible: 0;
+    grid-area: aside;
+  }
+
+  .md-layout-aside-title {
+    display: block;
+    margin-block-end: 0.75rem;
+    color: var(--md-color-heading);
+    font-size: 0.8125rem;
+    font-weight: 600;
+    list-style: none;
+    pointer-events: none;
+  }
+
+  .md-layout-aside-title::-webkit-details-marker {
+    display: none;
+  }
+
+  .md-layout-aside-current {
+    display: none;
+  }
+
+  /*
+   * Without room beside the content, the aside becomes a floating pill on the end side, stuck under the header and showing the section being read.
+   * Sticky items only stick within their grid area, so the pill shares the content's area and the content leaves room for it.
+   */
+  @media (width <= 75rem) {
+    .md-layout {
+      --md-layout-gap: 2.5rem;
+      /* One offset for where the pill sits and where it sticks, so it never shifts before sticking. Set here so the content can leave room for it too. */
+      --md-layout-aside-offset: 1rem;
+      grid-template-columns:
+        [full-start] minmax(0, 1fr)
+        [content-start] var(--md-layout-sidebar-width) minmax(0, var(--md-layout-main-width))
+        [content-end] minmax(0, 1fr) [full-end];
+      grid-template-areas:
+        "header header header header"
+        ". sidebar main .";
+    }
+
+    .md-layout-aside {
+      --md-layout-aside-collapsible: 1;
+      position: sticky;
+      top: calc(var(--md-header-height) + var(--md-layout-aside-offset));
+      z-index: 30;
+      grid-area: main;
+      justify-self: end;
+      max-width: 100%;
+      max-height: none;
+      margin-block-start: var(--md-layout-aside-offset);
+      padding: 0;
+      overflow: visible;
+    }
+
+    .md-layout:has(> .md-layout-aside) .md-layout-main {
+      padding-block-start: calc(var(--md-layout-aside-offset) + var(--md-layout-aside-button-height) + 1.75rem);
+    }
+
+    /* Headings land below the pill too, and the table of contents reads this as its reading line */
+    .md-layout:has(> .md-layout-aside) .md-prose :is(h1, h2, h3, h4, h5, h6) {
+      scroll-margin-top: calc(var(--md-header-height) + var(--md-layout-aside-button-height) + 2rem);
+    }
+
+    .md-layout-aside-title {
+      display: flex;
+      align-items: center;
+      gap: 0.5rem;
+      box-sizing: border-box;
+      max-width: 100%;
+      height: var(--md-layout-aside-button-height);
+      margin: 0;
+      padding-inline: 0.75rem 0.875rem;
+      border: 1px solid var(--md-color-border);
+      border-radius: 999px;
+      background: var(--md-color-bg);
+      box-shadow: 0 1px 2px rgb(0 0 0 / 0.05);
+      color: var(--md-color-heading);
+      font-size: 0.8125rem;
+      font-weight: 500;
+      cursor: pointer;
+      pointer-events: auto;
+      transition: box-shadow 0.2s;
+    }
+
+    .md-layout-aside-title:hover,
+    .md-layout-aside[open] > .md-layout-aside-title {
+      box-shadow: 0 4px 14px -4px rgb(0 0 0 / 0.14);
+    }
+
+    .md-layout-aside-title:focus-visible {
+      outline: var(--md-focus-ring);
+      outline-offset: 2px;
+    }
+
+    /* Reading progress as a ring, from --md-reading-progress set by attachAside */
+    .md-layout-aside-title::before {
+      content: "";
+      flex: none;
+      width: 0.875rem;
+      height: 0.875rem;
+      border-radius: 50%;
+      background: conic-gradient(
+        var(--md-color-accent) calc(var(--md-reading-progress, 0) * 1turn),
+        var(--md-color-border) 0
+      );
+      mask: radial-gradient(farthest-side, transparent calc(100% - 2px), #000 calc(100% - 1.5px));
+    }
+
+    .md-layout-aside-label,
+    .md-layout-aside-current {
+      overflow: hidden;
+      text-overflow: ellipsis;
+      white-space: nowrap;
+    }
+
+    .md-layout-aside-current {
+      display: block;
+    }
+
+    /* Once the section being read is known it takes the label's place, which stays for screen readers */
+    .md-layout-aside-title:has(.md-layout-aside-current:not(:empty)) .md-layout-aside-label {
+      position: absolute;
+      width: 1px;
+      height: 1px;
+      overflow: hidden;
+      clip-path: inset(50%);
+      white-space: nowrap;
+    }
+
+    /* Same chevron as sidebar groups */
+    .md-layout-aside-title::after {
+      content: "";
+      flex: none;
+      width: 0.3125rem;
+      height: 0.3125rem;
+      margin-inline-start: 0.125rem;
+      border-block-end: 1.5px solid currentColor;
+      border-inline-end: 1.5px solid currentColor;
+      opacity: 0.45;
+      transform: translateY(-0.125rem) rotate(45deg);
+      transition: transform 0.2s;
+    }
+
+    .md-layout-aside[open] > .md-layout-aside-title::after {
+      transform: translateY(0.125rem) rotate(-135deg);
+    }
+
+    /* The open table of contents drops down from the pill like a menu, over the content */
+    .md-layout-aside > :not(summary) {
+      position: absolute;
+      inset-block-start: 100%;
+      inset-inline-end: 0;
+      box-sizing: border-box;
+      width: min(20rem, calc(100vw - 2 * var(--md-layout-gap)));
+      max-height: calc(100dvh - var(--md-header-height) - var(--md-layout-aside-button-height) - 3rem);
+      margin-block-start: 0.5rem;
+      padding: 1rem 1.125rem;
+      overflow-y: auto;
+      overscroll-behavior: contain;
+      border: 1px solid var(--md-color-border);
+      border-radius: 0.75rem;
+      background: var(--md-color-bg);
+      box-shadow:
+        0 16px 40px -12px rgb(0 0 0 / 0.2),
+        0 2px 6px -2px rgb(0 0 0 / 0.06);
+    }
+  }
+
+  /* Narrow screens: one column, and the sidebar becomes a drawer opened by Sidebar.Trigger */
+  @media (width <= 50rem) {
+    .md-layout {
+      --md-layout-gap: 1.25rem;
+      grid-template-columns:
+        [full-start] minmax(0, 1fr)
+        [content-start] minmax(0, var(--md-layout-main-width))
+        [content-end] minmax(0, 1fr) [full-end];
+      grid-template-areas:
+        "header header header"
+        ". main .";
+    }
+
+    .md-layout .md-sidebar-trigger {
+      display: inline-flex;
+    }
+
+    /* A trigger placed directly in Layout.Root becomes a pill on the start side, mirroring the sidebar's place */
+    .md-layout > .md-sidebar-trigger {
+      position: sticky;
+      top: calc(var(--md-header-height) + var(--md-layout-aside-offset));
+      z-index: 30;
+      grid-area: main;
+      justify-self: start;
+      align-self: start;
+      justify-content: center;
+      box-sizing: border-box;
+      width: var(--md-layout-aside-button-height);
+      height: var(--md-layout-aside-button-height);
+      margin-block-start: var(--md-layout-aside-offset);
+      padding: 0;
+      border-radius: 999px;
+      background: var(--md-color-bg);
+      box-shadow: 0 1px 2px rgb(0 0 0 / 0.05);
+      transition: box-shadow 0.2s;
+    }
+
+    .md-layout > .md-sidebar-trigger:hover {
+      box-shadow: 0 4px 14px -4px rgb(0 0 0 / 0.14);
+    }
+
+    /* Room for the menu pill beside the table of contents pill */
+    .md-layout:has(> .md-sidebar-trigger) > .md-layout-aside {
+      max-width: calc(100% - var(--md-layout-aside-button-height) - 0.75rem);
+    }
+
+    /* Pages without a table of contents still leave room for the menu pill */
+    .md-layout:has(> .md-sidebar-trigger) .md-layout-main {
+      padding-block-start: calc(var(--md-layout-aside-offset) + var(--md-layout-aside-button-height) + 1.75rem);
+    }
+
+    .md-layout:has(> .md-sidebar-trigger) .md-prose :is(h1, h2, h3, h4, h5, h6) {
+      scroll-margin-top: calc(var(--md-header-height) + var(--md-layout-aside-button-height) + 2rem);
+    }
+
+    .md-layout-sidebar {
+      position: fixed;
+      inset-block: 0;
+      inset-inline-start: 0;
+      z-index: 50;
+      grid-area: auto;
+      /* Positioned grid items still follow align-self, which would shrink the drawer to its content */
+      align-self: stretch;
+      width: var(--md-layout-drawer-width);
+      max-height: none;
+      margin: 0;
+      padding: 0;
+      overflow-y: auto;
+      overscroll-behavior: contain;
+      border-inline-end: 1px solid var(--md-color-border);
+      background: var(--md-color-bg);
+      /* The backdrop is one huge shadow; both states must have the same number of shadows to transition cleanly */
+      box-shadow: 0 0 0 100vmax transparent;
+      transform: translateX(-100%);
+      visibility: hidden;
+      transition:
+        transform 0.25s cubic-bezier(0.32, 0.72, 0, 1),
+        box-shadow 0.25s,
+        visibility 0s 0.25s;
+    }
+
+    /* The sidebar fills the drawer, so a click anywhere in the drawer counts as inside it */
+    .md-layout-sidebar > * {
+      box-sizing: border-box;
+      min-height: 100%;
+      padding: 1rem 0.75rem;
+    }
+
+    /* Only the sidebar's own state counts; open groups inside it carry data-state too */
+    .md-layout-sidebar:has(> [data-state="open"]) {
+      box-shadow: 0 0 0 100vmax rgb(0 0 0 / 0.36);
+      transform: none;
+      visibility: visible;
+      transition:
+        transform 0.25s cubic-bezier(0.32, 0.72, 0, 1),
+        box-shadow 0.25s;
+    }
+
+    :root:has(.md-layout-sidebar > [data-state="open"]) {
+      overflow: hidden;
+    }
+  }
+
+  /* attachLayout sets this while the viewport is resized: a breakpoint changes the layout, not the state, so nothing slides */
+  .md-layout[data-md-resizing] :is(.md-layout-sidebar, .md-layout-aside-title),
+  .md-layout[data-md-resizing] .md-layout-aside-title::after,
+  .md-layout[data-md-resizing] > .md-sidebar-trigger {
+    transition: none;
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    .md-layout-sidebar,
+    .md-layout-sidebar:has(> [data-state="open"]),
+    .md-layout-aside-title,
+    .md-layout-aside-title::after,
+    .md-layout > .md-sidebar-trigger {
+      transition: none;
+    }
+  }
+}

package/src/styles/pager.css

@@ -0,0 +1,51 @@
+/* Previous and next page links. */
+@layer minidocs {
+  .md-pager {
+    display: grid;
+    grid-template-columns: 1fr 1fr;
+    gap: 1rem;
+    margin-block-start: 4rem;
+    padding-block-start: 1.5rem;
+    border-block-start: 1px solid var(--md-color-border);
+  }
+
+  .md-pager-link {
+    display: flex;
+    flex-direction: column;
+    gap: 0.125rem;
+    color: var(--md-color-heading);
+    text-decoration: none;
+  }
+
+  /* The next page stays on the end side even when there is no previous one */
+  .md-pager-link[rel="next"] {
+    grid-column: 2;
+    text-align: end;
+  }
+
+  .md-pager-link:focus-visible {
+    border-radius: 2px;
+    outline: var(--md-focus-ring);
+    outline-offset: 4px;
+  }
+
+  .md-pager-label {
+    color: var(--md-color-muted);
+    font-size: 0.8125rem;
+  }
+
+  .md-pager-title {
+    font-weight: 500;
+    transition: color 0.15s;
+  }
+
+  .md-pager-link:hover .md-pager-title {
+    color: var(--md-color-accent);
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    .md-pager-title {
+      transition: none;
+    }
+  }
+}

package/src/styles/prose.css

@@ -0,0 +1,218 @@
+/* Rendered Markdown content, from the Prose component or the md-prose class. */
+@layer minidocs {
+  .md-prose {
+    color: var(--md-color-text);
+    font-size: var(--md-prose-font-size);
+    line-height: var(--md-prose-line-height);
+    overflow-wrap: break-word;
+  }
+
+  .md-prose > :first-child {
+    margin-block-start: 0;
+  }
+
+  .md-prose > :last-child {
+    margin-block-end: 0;
+  }
+
+  .md-prose :is(h1, h2, h3, h4, h5, h6) {
+    color: var(--md-color-heading);
+    font-weight: 600;
+    line-height: 1.35;
+    text-wrap: balance;
+  }
+
+  .md-prose h1 {
+    margin-block: 0 1rem;
+    font-size: 1.875em;
+    font-weight: 700;
+    letter-spacing: -0.015em;
+    line-height: 1.25;
+  }
+
+  .md-prose h2 {
+    margin-block: 2.5em 0.75em;
+    font-size: 1.5em;
+    letter-spacing: -0.01em;
+  }
+
+  .md-prose h3 {
+    margin-block: 2em 0.5em;
+    font-size: 1.125em;
+  }
+
+  .md-prose :is(h4, h5, h6) {
+    margin-block: 1.75em 0.5em;
+    font-size: 1em;
+  }
+
+  /* A heading right after another one already has enough space above it */
+  .md-prose :is(h1, h2, h3, h4, h5, h6) + :is(h2, h3, h4, h5, h6) {
+    margin-block-start: 0.75em;
+  }
+
+  /* Except under the page title, which needs a clear gap before the first section */
+  .md-prose h1 + :is(h2, h3, h4, h5, h6) {
+    margin-block-start: 1.75em;
+  }
+
+  .md-prose :is(p, ul, ol, blockquote, pre, table, figure) {
+    margin-block: 1.125em;
+  }
+
+  .md-prose a {
+    color: var(--md-color-accent);
+    text-decoration: underline;
+    text-decoration-color: color-mix(in srgb, var(--md-color-accent) 35%, transparent);
+    text-decoration-thickness: 1px;
+    text-underline-offset: 0.22em;
+    transition: text-decoration-color 0.15s;
+  }
+
+  .md-prose a:hover {
+    text-decoration-color: currentColor;
+  }
+
+  .md-prose strong {
+    color: var(--md-color-heading);
+    font-weight: 600;
+  }
+
+  /* Set explicitly, since resets like Tailwind's Preflight remove the browser defaults */
+  .md-prose :is(ul, ol) {
+    padding-inline-start: 1.375em;
+  }
+
+  .md-prose ul {
+    list-style-type: disc;
+  }
+
+  .md-prose ol {
+    list-style-type: decimal;
+  }
+
+  .md-prose :is(ul, ol) ul {
+    list-style-type: circle;
+  }
+
+  .md-prose li {
+    margin-block: 0.375em;
+    padding-inline-start: 0.125em;
+  }
+
+  .md-prose li > :is(ul, ol) {
+    margin-block: 0.375em;
+  }
+
+  .md-prose li::marker {
+    color: var(--md-color-muted);
+  }
+
+  .md-prose ol > li::marker {
+    font-variant-numeric: tabular-nums;
+  }
+
+  .md-prose blockquote {
+    margin-inline: 0;
+    padding-inline-start: 1em;
+    border-inline-start: 2px solid var(--md-color-border);
+    color: var(--md-color-muted);
+  }
+
+  .md-prose hr {
+    margin-block: 3em;
+    border: 0;
+    border-block-start: 1px solid var(--md-color-border);
+  }
+
+  .md-prose img {
+    max-width: 100%;
+    height: auto;
+    border-radius: var(--md-radius);
+  }
+
+  .md-prose code,
+  .md-prose kbd {
+    font-family: var(--md-font-mono);
+    font-size: 0.875em;
+  }
+
+  .md-prose :not(pre) > code {
+    padding: 0.125em 0.375em;
+    border-radius: 0.3125rem;
+    background: color-mix(in srgb, var(--md-color-heading) 6%, transparent);
+    color: var(--md-color-heading);
+    overflow-wrap: anywhere;
+  }
+
+  .md-prose a code {
+    color: inherit;
+  }
+
+  .md-prose kbd {
+    padding: 0.0625em 0.375em;
+    border: 1px solid var(--md-color-border);
+    border-block-end-width: 2px;
+    border-radius: 0.3125rem;
+    color: var(--md-color-heading);
+  }
+
+  .md-prose pre {
+    padding: 0.875rem 1rem;
+    border: 1px solid var(--md-color-border);
+    border-radius: 0.5rem;
+    background-color: var(--md-color-code-bg);
+    font-size: 0.8125rem;
+    line-height: 1.7;
+    overflow-x: auto;
+    tab-size: 2;
+  }
+
+  .md-prose pre > code {
+    font-size: inherit;
+  }
+
+  /* Shiki dual themes with defaultColor: false leave colors to CSS; single themes set them inline and win */
+  .md-prose :is(pre, pre span) {
+    color: light-dark(var(--shiki-light), var(--shiki-dark));
+  }
+
+  .md-prose pre:focus-visible {
+    outline: var(--md-focus-ring);
+    outline-offset: 2px;
+  }
+
+  /* Wide tables scroll inside themselves instead of widening the page */
+  .md-prose table {
+    display: block;
+    width: max-content;
+    max-width: 100%;
+    overflow-x: auto;
+    border-collapse: collapse;
+    font-size: 0.9375em;
+    line-height: 1.6;
+  }
+
+  .md-prose :is(th, td) {
+    padding: 0.625em 1.25em 0.625em 0;
+    border-block-end: 1px solid var(--md-color-border);
+    text-align: start;
+    vertical-align: top;
+  }
+
+  .md-prose :is(th, td):last-child {
+    padding-inline-end: 0;
+  }
+
+  /* Tables scroll sideways, so code in them stays whole instead of breaking mid-word */
+  .md-prose :is(th, td) code {
+    overflow-wrap: normal;
+    white-space: nowrap;
+  }
+
+  .md-prose th {
+    border-block-end-color: color-mix(in srgb, var(--md-color-heading) 25%, transparent);
+    color: var(--md-color-heading);
+    font-weight: 600;
+  }
+}