@minidocs/astro 0.0.0-stage → 0.2.0

package/src/components/toc/index.ts

@@ -0,0 +1,4 @@
+export { default as Item } from './Item.astro';
+export { default as Link } from './Link.astro';
+export { default as List } from './List.astro';
+export { default as Root } from './Root.astro';

package/src/styles/base.css

@@ -0,0 +1,42 @@
+/* Variables shared by every minidocs style file. Import it before any of the others. */
+@layer minidocs {
+  /* Colors follow the page's color-scheme, not the system: pages without a dark style stay light */
+  :root {
+    --md-color-bg: light-dark(#ffffff, #18181b);
+    --md-color-heading: light-dark(#18181b, #fafafa);
+    --md-color-text: light-dark(#3f3f46, #d4d4d8);
+    --md-color-muted: light-dark(#71717a, #a1a1aa);
+    --md-color-border: light-dark(#e4e4e7, #2e2e33);
+    /* Neutral by default, so a site brings its own color by setting this one variable */
+    --md-color-accent: var(--md-color-heading);
+    --md-color-hover: color-mix(in srgb, var(--md-color-heading) 5%, transparent);
+    --md-color-current: color-mix(in srgb, var(--md-color-accent) 9%, transparent);
+    --md-color-code-bg: light-dark(#f6f6f7, #202024);
+    --md-color-note: light-dark(#2563eb, #60a5fa);
+    --md-color-tip: light-dark(#15803d, #4ade80);
+    --md-color-important: light-dark(#7c3aed, #a78bfa);
+    --md-color-warning: light-dark(#b45309, #fbbf24);
+    --md-color-caution: light-dark(#dc2626, #f87171);
+    --md-font-sans:
+      -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Hiragino Sans GB", "Microsoft YaHei",
+      "Noto Sans CJK SC", sans-serif;
+    --md-font-mono: ui-monospace, "SF Mono", "JetBrains Mono", Menlo, Consolas, monospace;
+    --md-radius: 0.375rem;
+    --md-focus-ring: 2px solid var(--md-color-accent);
+    --md-sidebar-font-size: 0.875rem;
+    --md-sidebar-item-padding-block: 0.375rem;
+    --md-sidebar-item-padding-inline: 0.625rem;
+    --md-sidebar-indent: 0.625rem;
+    --md-sidebar-rail-gap: 0.375rem;
+    --md-toc-font-size: 0.8125rem;
+    --md-toc-indent: 0.75rem;
+    --md-prose-font-size: 1rem;
+    --md-prose-line-height: 1.75;
+    --md-header-height: 3.5rem;
+    --md-layout-aside-button-height: 2.25rem;
+    --md-layout-sidebar-width: 15rem;
+    --md-layout-main-width: 46rem;
+    --md-layout-aside-width: 13rem;
+    --md-layout-drawer-width: min(20rem, 85vw);
+  }
+}

package/src/styles/callout.css

@@ -0,0 +1,58 @@
+/* Callouts, from the Callout component or the :::type and > [!TYPE] syntax. */
+@layer minidocs {
+  .md-callout {
+    --md-callout-color: var(--md-color-note);
+    padding: 0.75rem 1rem;
+    border-inline-start: 2px solid var(--md-callout-color);
+    border-start-end-radius: var(--md-radius);
+    border-end-end-radius: var(--md-radius);
+    background: color-mix(in srgb, var(--md-callout-color) 7%, transparent);
+    color: var(--md-color-text);
+  }
+
+  .md-callout[data-type="tip"] {
+    --md-callout-color: var(--md-color-tip);
+  }
+
+  .md-callout[data-type="important"] {
+    --md-callout-color: var(--md-color-important);
+  }
+
+  .md-callout[data-type="warning"] {
+    --md-callout-color: var(--md-color-warning);
+  }
+
+  .md-callout[data-type="caution"] {
+    --md-callout-color: var(--md-color-caution);
+  }
+
+  /* :nth-child(n) only raises specificity, so these win over the spacing of prose paragraphs and lists */
+  .md-callout > :nth-child(n) {
+    margin-block: 0;
+  }
+
+  .md-callout > :nth-child(n + 2) {
+    margin-block-start: 0.5em;
+  }
+
+  .md-callout > .md-callout-title + * {
+    margin-block-start: 0.125em;
+  }
+
+  .md-callout-title {
+    color: var(--md-callout-color);
+    font-weight: 600;
+  }
+
+  /* Inside prose, links already follow .md-prose; this covers callouts used elsewhere */
+  .md-callout a {
+    color: inherit;
+    text-decoration: underline;
+    text-decoration-color: color-mix(in srgb, currentColor 40%, transparent);
+    text-underline-offset: 0.22em;
+  }
+
+  .md-prose .md-callout {
+    margin-block: 1.25em;
+  }
+}

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,56 @@
+/* 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);
+  }
+
+  /* Padding gives hover a background like the sidebar's, and margins on the outer side keep text aligned */
+  .md-pager-link {
+    display: flex;
+    flex-direction: column;
+    gap: 0.125rem;
+    margin-block: -0.5rem;
+    margin-inline: -0.75rem 0;
+    padding: 0.5rem 0.75rem;
+    border-radius: var(--md-radius);
+    color: var(--md-color-heading);
+    text-decoration: none;
+    transition: background-color 0.15s;
+  }
+
+  .md-pager-link:hover {
+    background: var(--md-color-hover);
+  }
+
+  /* The next page stays on the end side even when there is no previous one */
+  .md-pager-link[rel="next"] {
+    grid-column: 2;
+    margin-inline: 0 -0.75rem;
+    text-align: end;
+  }
+
+  .md-pager-link:focus-visible {
+    outline: var(--md-focus-ring);
+    outline-offset: -2px;
+  }
+
+  .md-pager-label {
+    color: var(--md-color-muted);
+    font-size: 0.8125rem;
+  }
+
+  .md-pager-title {
+    font-weight: 500;
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    .md-pager-link {
+      transition: none;
+    }
+  }
+}