@kirchdev/duxt 0.3.4 → 0.3.5-dev-main.44-5337cc1

package/app/pages/[...slug].vue

@@ -52,13 +52,32 @@ const { data: found } = await useAsyncData(
       if (hit) return { page: hit, from: entry!.locale, asked: locale.value };
     }
 
-    return undefined;
+    // `null`, not `undefined`: Nuxt reads a handler that resolves to nothing as
+    // one that failed to return (E3006) and repeats the query on the client.
+    // No page in any language is a real answer — the 404 below.
+    return null;
   },
   { watch: [collection, path] }
 );
 
 const page = computed(() => found.value?.page);
 
+/**
+ * What THIS page says about the docs shell around it.
+ *
+ * Eight frontmatter fields, resolved over the site's own switches in one place
+ * — see `app/utils/page-controls.ts`. The alternative was eight `v-if`s each
+ * reading a different field off `page.value` with its own idea of what an
+ * absent value means, which is how `duxt.breadcrumb` ended up being the only
+ * one of the eight that existed at all.
+ */
+const controls = computed(() =>
+  duxtPageControls(page.value, {
+    breadcrumb: duxt?.breadcrumb,
+    tocMaxDepth: duxt.toc?.depth
+  })
+);
+
 /** True when the reader is being shown a language they did not ask for. */
 const untranslated = computed(() => {
   if (!translates.value || !found.value) return false;
@@ -76,12 +95,17 @@ if (!page.value) {
   throw createError({
     statusCode: 404,
     statusMessage: 'Page not found',
-    fatal: true
+    // Fatal on the CLIENT only. A client-side navigation needs it to replace
+    // the page with the error page; the server renders that page for any
+    // error thrown here. Fatal on the server, Nitro files every missing URL
+    // as a sensitive failure and logs it with a stack trace — in dev and in
+    // production alike, one line per bot probing a path that does not exist.
+    fatal: import.meta.client
   });
 }
 
 // Feeds the search dialog's empty state.
-const { remember } = useRecentPages();
+const { remember } = useRecentPages(duxt.search?.recentPages);
 onMounted(() =>
   remember({ path: path.value, title: page.value?.title ?? path.value })
 );
@@ -129,7 +153,22 @@ const owned = computed(() =>
  * genuinely have no outline.
  */
 const generated = computed(() =>
-  owned.value ? generatedToc(page.value?.body) : []
+  owned.value && controls.value.toc
+    ? generatedToc(page.value?.body, controls.value.tocMaxDepth)
+    : []
+);
+
+/**
+ * The written page's outline, cut to the depth the page asked for.
+ *
+ * Content parses every level down to `h6` — see `content.build.markdown.toc` in
+ * `nuxt.config.ts` — so this is where the column is decided rather than at
+ * parse time, and `toc: { maxDepth: 5 }` has something to show.
+ */
+const outline = computed(() =>
+  controls.value.toc
+    ? duxtTocLinks(page.value?.body?.toc?.links, controls.value.tocMaxDepth)
+    : []
 );
 
 /**
@@ -175,6 +214,21 @@ const aside = computed(
     (generated.value.length > 0 || (duxt.aside?.links?.length ?? 0) > 0)
 );
 
+/**
+ * Is there anything left to put in a written page's right-hand column?
+ *
+ * It was drawn unconditionally, which was right while nothing could empty it —
+ * a page that turns off both the contents and the provenance on a site with no
+ * aside links would otherwise reserve fourteen rems for nothing. Page info is
+ * on by default, so the ordinary page keeps exactly the column it had.
+ */
+const column = computed(
+  () =>
+    outline.value.length > 0 ||
+    (duxt.aside?.links?.length ?? 0) > 0 ||
+    controls.value.pageInfo
+);
+
 // The social card. Rendered from the layer's own template unless the consumer
 // ships a component of the same name — see `OgImage/Duxt.satori.vue`.
 //
@@ -227,6 +281,19 @@ useHead(() => ({
     {
       rel: 'canonical',
       href: absolute(localeLink(preferredPath.value) ?? preferredPath.value)
+    },
+    {
+      // Static HTML retains these relations when an edge serves a prerendered
+      // page, unlike an HTTP Link header configured only at runtime.
+      rel: 'alternate',
+      type: 'text/markdown',
+      href: `${localeLink(path.value) ?? path.value}.md`
+    },
+    {
+      // Unhead's narrow relation union does not yet include this standard
+      // relation, but it still renders arbitrary link relation values.
+      rel: 'describedby' as never,
+      href: '/llms.txt'
     }
   ]
 }));
@@ -272,8 +339,16 @@ useSchemaOrg([
   <!-- The type's own layout owns the page: no reading width and no header of
        ours — see `owned`. The CONTENTS COLUMN is drawn here rather than left to
        the layout, because only the page holds the body it is read from. -->
-  <div v-if="owned" class="flex min-w-0 flex-1 gap-10">
+  <!-- BOTH BRANCHES HANG ON `page`. A missing page throws its 404 out of
+       `setup`, and Vue still renders the component once on the way to the
+       error page — with none of the bindings `setup` never got to return. The
+       first nested read then threw `Cannot read properties of undefined
+       (reading 'fullWidth')` on every client-side navigation to a missing page.
+       Without a page there is nothing of this component to draw. -->
+  <div v-if="page && owned" class="flex min-w-0 flex-1 gap-10">
     <div class="min-w-0 flex-1 py-8">
+      <DuxtAnnouncements placement="above-content" />
+
       <DuxtVersionBanner />
 
       <DuxtTranslationBanner v-if="untranslated" :from="found?.from" />
@@ -288,23 +363,45 @@ useSchemaOrg([
            does not — and a header narrower than the parameter tables under it
            draws a rule that stops halfway across the page. -->
       <header v-if="!titled" class="mb-8 border-b pb-8">
-        <DuxtBreadcrumb
-          v-if="duxt?.breadcrumb !== false"
-          :path="path"
-          class="mb-3"
-        />
-
-        <div class="flex items-start justify-between gap-4">
+        <DuxtBreadcrumb v-if="controls.breadcrumb" :path="path" class="mb-3" />
+
+        <!-- THE TITLE ROW, AND WHY IT IS ALLOWED TO WRAP. This shape repeats
+             three times on this page — here, in the compact row below and in
+             the written-page header further down — and at 320px all three used
+             to push the document sideways. Nothing in the row could give: the
+             copy control is `shrink-0` by choice, the row was `nowrap`, and an
+             `<h1>` keeps `min-width: auto`, so a title whose longest word is
+             wide at `text-4xl` pins the row at that word's min-content. Three
+             of duxt's own pages overflowed, *Introduction* by 56px.
+
+             Below `sm` the control drops to its own line instead, because at
+             that width there is no room for a 36px title and a 145px control
+             side by side, and a clipped title is worse than a wrapped control.
+             `sm:flex-nowrap` keeps the control beside the title everywhere
+             else: `flex-wrap` breaks lines on an item's MAX-content, so
+             wrapping unconditionally would demote the control below any
+             ordinary long title on a desktop, which is not the bug.
+
+             `min-w-0` plus `wrap-break-word` on the heading is the backstop for
+             the case wrapping cannot reach — a single word wider than the whole
+             column. `overflow-wrap: break-word` does not lower an element's
+             min-content width, so without `min-w-0` it can never act inside a
+             flex row; and because it only breaks a word that fits on no line of
+             its own, an ordinary title is left exactly as it was. -->
+        <div
+          class="flex flex-wrap items-start justify-between gap-x-4 gap-y-2 sm:flex-nowrap"
+        >
           <h1
             ref="heading"
             tabindex="-1"
-            class="text-4xl font-semibold tracking-tight text-balance outline-none"
+            class="min-w-0 text-4xl font-semibold tracking-tight text-balance wrap-break-word outline-none"
           >
             {{ page?.title }}
           </h1>
 
           <DuxtCopyPage
-            class="mt-1"
+            v-if="controls.copyPage"
+            class="mt-1 ms-auto"
             :path="path"
             :title="page?.title"
             :rawbody="(page as { rawbody?: string })?.rawbody"
@@ -328,11 +425,15 @@ useSchemaOrg([
 
       <!-- A type that DOES draw its own title keeps the compact row: where the
            reader is, and what they can do with the page. -->
-      <div v-else class="mb-6 flex items-start justify-between gap-4">
-        <DuxtBreadcrumb v-if="duxt?.breadcrumb !== false" :path="path" />
+      <div
+        v-else
+        class="mb-6 flex flex-wrap items-start justify-between gap-x-4 gap-y-2 sm:flex-nowrap"
+      >
+        <DuxtBreadcrumb v-if="controls.breadcrumb" :path="path" />
 
         <DuxtCopyPage
-          class="-mt-1 ml-auto"
+          v-if="controls.copyPage"
+          class="-mt-1 ms-auto"
           :path="path"
           :title="page?.title"
           :rawbody="(page as { rawbody?: string })?.rawbody"
@@ -349,7 +450,7 @@ useSchemaOrg([
            at the section's edge, so the links can only be siblings — and a
            release page that ended in whitespace now ends in the release before
            it, which is how a history is read. -->
-      <DuxtPageNav :path="path" />
+      <DuxtPageNav v-if="controls.prevNext" :path="path" />
 
       <!-- Provenance survives the header, because it is the one part of it that
            is still true: every page of a generated section came out of one
@@ -359,7 +460,7 @@ useSchemaOrg([
       <!-- As a row, and as wide as the page: with no column to sit in it is a
            footer, and a rule that stopped at the reading measure under a page
            set wider than that ended halfway across. -->
-      <DuxtPageInfo v-if="!aside" row :page="page" />
+      <DuxtPageInfo v-if="!aside && controls.pageInfo" row :page="page" />
     </div>
 
     <div v-if="aside" class="hidden w-56 shrink-0 xl:block">
@@ -368,37 +469,46 @@ useSchemaOrg([
       >
         <DuxtToc :links="generated" />
 
-        <DuxtPageInfo :page="page" />
+        <DuxtPageInfo v-if="controls.pageInfo" :page="page" />
       </div>
     </div>
   </div>
 
-  <div v-else class="flex min-w-0 flex-1 justify-center gap-10">
-    <article class="min-w-0 max-w-3xl flex-1 py-8">
+  <div v-else-if="page" class="flex min-w-0 flex-1 justify-center gap-10">
+    <!-- `fullWidth` removes the reading measure and NOTHING else: the header,
+         the left navigation and the column beside the article all stay, and a
+         page that wants those gone says so with their own controls. It is the
+         one page control that is off until asked for, because it removes a
+         constraint rather than something the shell draws. -->
+    <article
+      class="min-w-0 flex-1 py-8"
+      :class="controls.fullWidth ? undefined : 'max-w-3xl'"
+    >
+      <DuxtAnnouncements placement="above-content" />
+
       <DuxtVersionBanner />
 
       <DuxtTranslationBanner v-if="untranslated" :from="found?.from" />
 
       <header class="mb-8 border-b pb-8">
-        <DuxtBreadcrumb
-          v-if="duxt?.breadcrumb !== false"
-          :path="path"
-          class="mb-3"
-        />
+        <DuxtBreadcrumb v-if="controls.breadcrumb" :path="path" class="mb-3" />
         <!-- The copy action sits with the title, not under the article: it is
              what a reader does with the page BEFORE reading it, and a control
              for that at the bottom is a control nobody finds. -->
-        <div class="flex items-start justify-between gap-4">
+        <div
+          class="flex flex-wrap items-start justify-between gap-x-4 gap-y-2 sm:flex-nowrap"
+        >
           <h1
             ref="heading"
             tabindex="-1"
-            class="text-4xl font-semibold tracking-tight text-balance outline-none"
+            class="min-w-0 text-4xl font-semibold tracking-tight text-balance wrap-break-word outline-none"
           >
             {{ page?.title }}
           </h1>
 
           <DuxtCopyPage
-            class="mt-1"
+            v-if="controls.copyPage"
+            class="mt-1 ms-auto"
             :path="path"
             :title="page?.title"
             :rawbody="(page as { rawbody?: string })?.rawbody"
@@ -416,25 +526,26 @@ useSchemaOrg([
         <ContentRenderer v-if="page" :value="page" />
       </div>
 
-      <DuxtPageNav :path="path" />
+      <DuxtPageNav v-if="controls.prevNext" :path="path" />
 
-      <DuxtPageFeedback />
+      <DuxtPageFeedback v-if="controls.feedback" />
     </article>
 
     <!-- A div for the same reason as the sidebar's: DuxtToc's two <nav>s are
          the landmarks, and both are labelled. -->
-    <div class="hidden w-56 shrink-0 xl:block">
+    <!-- It drops out entirely once a page has emptied it — see `column`. -->
+    <div v-if="column" class="hidden w-56 shrink-0 xl:block">
       <div
         class="sticky top-[var(--duxt-header-offset)] max-h-[calc(100vh-var(--duxt-header-offset)-1.5rem)] overflow-y-auto py-8"
       >
-        <DuxtToc :links="page?.body?.toc?.links ?? []" />
+        <DuxtToc :links="outline" />
 
         <!-- Provenance under the contents: where this page came from, when it
              last changed and who wrote it. On the right rather than under the
              article, where it read as an afterthought below the prev/next
              links — this column is already the one answering what a page IS
              rather than what it says. -->
-        <DuxtPageInfo :page="page" />
+        <DuxtPageInfo v-if="controls.pageInfo" :page="page" />
       </div>
     </div>
   </div>

package/app/pages/index.vue

@@ -21,7 +21,6 @@
 const duxt = useDuxtConfig();
 const localeLink = useDuxtLink();
 const { t } = useI18n();
-const notify = useDuxtToast();
 
 /**
  * Where a hero button goes when the config did not say — the same fallback
@@ -48,22 +47,11 @@ const { data: highlightedCommand } = await useAsyncData(
   { watch: [command] }
 );
 
-const copied = ref(false);
-async function copyCommand() {
-  if (!command.value) return;
-
-  try {
-    await navigator.clipboard.writeText(command.value);
-    copied.value = true;
-    // The icon alone is a 3.5 rem change under the reader's own cursor, which
-    // is exactly where they are not looking after a click. The toast is the
-    // confirmation; the icon is what stays for the two seconds after it.
-    notify.success(t('duxt.code.copiedToast'));
-    setTimeout(() => (copied.value = false), 2000);
-  } catch {
-    notify.error(t('duxt.page.copyFailed'));
-  }
-}
+// The icon alone is a 3.5 rem change under the reader's own cursor, which is
+// exactly where they are not looking after a click. The toast is the
+// confirmation; the icon is what stays for the two seconds after it.
+const { copied, copy } = useDuxtCopy();
+const copyCommand = () => copy(command.value);
 
 /**
  * The badge, in either of its two shapes. A string is the label and nothing
@@ -275,12 +263,16 @@ defineOgImage('Duxt', {
             <span aria-hidden="true" class="text-muted-foreground select-none"
               >$</span
             >
+            <!-- A shell command does not turn round with the interface, so
+                 it declares its own direction and aligns to the start of THAT
+                 — which is the left, in either locale. -->
             <span
               v-if="highlightedCommand"
-              class="min-w-0 overflow-x-auto text-left [&_pre]:bg-transparent!"
+              dir="ltr"
+              class="min-w-0 overflow-x-auto text-start [&_pre]:bg-transparent!"
               v-html="highlightedCommand"
             />
-            <span v-else class="min-w-0 overflow-x-auto text-left">{{
+            <span v-else dir="ltr" class="min-w-0 overflow-x-auto text-start">{{
               command
             }}</span>
             <Icon
@@ -412,7 +404,7 @@ defineOgImage('Duxt', {
                       ? 'lucide:arrow-up-right'
                       : 'lucide:arrow-right'
                   "
-                  class="size-3.5 text-muted-foreground transition-transform group-hover:translate-x-0.5"
+                  class="size-3.5 text-muted-foreground rtl:-scale-x-100 transition-transform ltr:group-hover:translate-x-0.5 rtl:group-hover:-translate-x-0.5"
                 />
               </UiCardTitle>
 
@@ -425,9 +417,9 @@ defineOgImage('Duxt', {
       </div>
     </section>
 
-    <!-- THE REST. One line each, no cards and no links: these are real and
-         worth naming, and a card apiece would say they matter as much as the
-         four above.
+    <!-- THE SUPPORTING SYSTEM. One line each, no cards and no links: these are
+         real parts of publishing and reading the content, while a card apiece
+         would say they matter as much as the primary capabilities above.
          
          A <ul>, and the entries are paragraphs rather than headings: this is a
          list of things, not a part of the document with sections under it — and