@kirchdev/duxt 0.3.4-dev-main.41-23ded41 → 0.3.5-dev-main.43-3310f4b

package/app/components/ui/tabs/TabsTrigger.vue

@@ -4,14 +4,33 @@ import type { HTMLAttributes } from 'vue';
 import { reactiveOmit } from '@vueuse/core';
 import { TabsTrigger, useForwardProps } from 'reka-ui';
 import { cn } from '@duxt/lib/utils';
+import { duxtPill, type DuxtPillSize } from '../../../utils/pill';
 
+/**
+ * Three looks, one behaviour.
+ *
+ * `pill` is the site's own — the code group, the preview and the request
+ * samples, drawn by `duxtPill` like every other "pick one of these" strip.
+ * `underline` is the prose tab group, which sits in running text rather than in
+ * a card. `default` is shadcn's, untouched, for a consumer who wants it.
+ */
 const props = defineProps<
-  TabsTriggerProps & { class?: HTMLAttributes['class'] }
+  TabsTriggerProps & {
+    class?: HTMLAttributes['class'];
+    variant?: 'default' | 'pill' | 'underline';
+    size?: DuxtPillSize;
+  }
 >();
 
-const delegatedProps = reactiveOmit(props, 'class');
+const delegatedProps = reactiveOmit(props, 'class', 'variant', 'size');
 
 const forwardedProps = useForwardProps(delegatedProps);
+
+const looks = {
+  default: `data-[state=active]:bg-background dark:data-[state=active]:text-foreground focus-visible:border-ring focus-visible:ring-ring/50 focus-visible:outline-ring dark:data-[state=active]:border-input dark:data-[state=active]:bg-input/30 text-foreground dark:text-muted-foreground inline-flex h-[calc(100%-1px)] flex-1 items-center justify-center gap-1.5 rounded-md border border-transparent px-2 py-1 text-sm font-medium whitespace-nowrap transition-[color,box-shadow] focus-visible:ring-3 focus-visible:outline-1 disabled:pointer-events-none disabled:opacity-50 data-[state=active]:shadow-sm [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4`,
+  underline:
+    '-mb-px cursor-pointer border-b-2 border-transparent px-3 py-1.5 text-sm text-muted-foreground transition-colors hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring data-[state=active]:border-primary data-[state=active]:text-foreground'
+};
 </script>
 
 <template>
@@ -19,7 +38,9 @@ const forwardedProps = useForwardProps(delegatedProps);
     data-slot="tabs-trigger"
     :class="
       cn(
-        `data-[state=active]:bg-background dark:data-[state=active]:text-foreground focus-visible:border-ring focus-visible:ring-ring/50 focus-visible:outline-ring dark:data-[state=active]:border-input dark:data-[state=active]:bg-input/30 text-foreground dark:text-muted-foreground inline-flex h-[calc(100%-1px)] flex-1 items-center justify-center gap-1.5 rounded-md border border-transparent px-2 py-1 text-sm font-medium whitespace-nowrap transition-[color,box-shadow] focus-visible:ring-3 focus-visible:outline-1 disabled:pointer-events-none disabled:opacity-50 data-[state=active]:shadow-sm [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4`,
+        props.variant === 'pill'
+          ? duxtPill('tab', { size: props.size })
+          : looks[props.variant ?? 'default'],
         props.class
       )
     "

package/app/components/ui/tooltip/TooltipContent.vue

@@ -34,7 +34,7 @@ const forwarded = useForwardPropsEmits(delegatedProps, emits);
       v-bind="{ ...forwarded, ...$attrs }"
       :class="
         cn(
-          'bg-foreground text-background animate-in fade-in-0 zoom-in-95 data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=closed]:zoom-out-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 z-50 w-fit rounded-md px-3 py-1.5 text-xs text-balance',
+          'bg-neutral-900 text-neutral-50 animate-in fade-in-0 zoom-in-95 data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=closed]:zoom-out-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 z-50 w-fit rounded-md px-3 py-1.5 text-xs text-balance',
           props.class
         )
       "
@@ -42,7 +42,7 @@ const forwarded = useForwardPropsEmits(delegatedProps, emits);
       <slot />
 
       <TooltipArrow
-        class="bg-foreground fill-foreground z-50 size-2.5 translate-y-[calc(-50%_-_2px)] rotate-45 rounded-xs"
+        class="z-50 size-2.5 translate-y-[calc(-50%_-_2px)] rotate-45 rounded-xs bg-neutral-900 fill-neutral-900"
       />
     </TooltipContent>
   </TooltipPortal>

package/app/composables/useActiveHeading.ts

@@ -24,17 +24,10 @@
  * `getBoundingClientRect` per heading, coalesced into an animation frame, so at
  * most one pass per painted frame however fast the wheel turns.
  */
-export function useActiveHeading(ids: Ref<string[]>) {
+export function useActiveHeading(ids: Ref<string[]>, scrollOffset = 96) {
   const active = ref<string>();
 
-  /** Where a heading counts as reached: reading position, not the top edge. */
-  const TRIGGER = 96;
-
-  let frame = 0;
-
   function measure() {
-    frame = 0;
-
     const headings = ids.value
       .map((id) => document.getElementById(id))
       .filter((element): element is HTMLElement => Boolean(element));
@@ -58,33 +51,18 @@ export function useActiveHeading(ids: Ref<string[]>) {
 
     let current = headings[0]!;
     for (const heading of headings) {
-      if (heading.getBoundingClientRect().top > TRIGGER) break;
+      if (heading.getBoundingClientRect().top > scrollOffset) break;
       current = heading;
     }
 
     active.value = current.id;
   }
 
-  function schedule() {
-    if (frame) return;
-    frame = requestAnimationFrame(measure);
-  }
-
-  onMounted(() => {
-    measure();
-    window.addEventListener('scroll', schedule, { passive: true });
-    window.addEventListener('resize', schedule, { passive: true });
-  });
+  useDuxtViewportMeasure(measure);
 
   // A new page's headings exist only after it renders, and the ids change
   // before the DOM does.
   watch(ids, () => nextTick(measure));
 
-  onBeforeUnmount(() => {
-    if (frame) cancelAnimationFrame(frame);
-    window.removeEventListener('scroll', schedule);
-    window.removeEventListener('resize', schedule);
-  });
-
   return active;
 }

package/app/composables/useDuxtAnalytics.ts

@@ -0,0 +1,50 @@
+/**
+ * Report one reader interaction to whoever the site said, if it said anyone.
+ *
+ * OPT-IN IS THE WHOLE FEATURE, and it is worth saying what that buys. duxt
+ * ships no provider, no SDK, no adapter and no script: a site that has not
+ * written `duxt.analytics.track` downloads not one byte more than before this
+ * existed, and every call below reaches a `typeof track !== 'function'` and
+ * stops. There is no queue, no buffer, no storage, no cookie and no consent
+ * banner, because duxt never holds the data long enough to need any of them —
+ * the site's own function is the only thing that ever leaves the page.
+ *
+ * That puts three decisions on the side that owns them: WHICH provider, WHETHER
+ * to transmit at all, and under what consent. A layer cannot answer any of the
+ * three for somebody else's readers — the same reason `DuxtPageFeedback` has an
+ * event and no backend, and the footer's legal row ships empty (ADR 0005).
+ *
+ * WHAT IS NEVER SENT, stated once so it can be checked: no API credential, no
+ * request or response body, no concrete request URL, no header, no copied text,
+ * no rendered search result, no browser or reader identifier, and no query
+ * string or fragment off the page's own path. The event types say the rest —
+ * they are a closed union, so what duxt can report is readable in one place.
+ *
+ * CLIENT ONLY. A build and a prerender call nobody: a static render is not a
+ * reader, and a site's analytics must not fill up with pages the crawler
+ * opened. `duxt.app` prerenders every page it has, which is exactly the case
+ * that would otherwise send hundreds of events from a CI box.
+ */
+export function useDuxtAnalytics() {
+  const duxt = useDuxtConfig();
+  const path = useDuxtPath();
+  const { locale } = useI18n();
+  // The source the reader is standing in, not the one a hit came out of — a
+  // search result carries its own provenance on the event itself.
+  const { source } = useDuxtCollection();
+
+  /**
+   * Stamp the context on and hand it over. Returns nothing, on purpose:
+   * nothing a call site does should depend on whether reporting worked.
+   */
+  function track<Event extends DuxtAnalyticsEventInput>(event: Event): void {
+    if (import.meta.server) return;
+
+    emitDuxtAnalytics(duxt.analytics?.track, {
+      ...event,
+      context: duxtAnalyticsContext(path.value, locale.value, source.value)
+    });
+  }
+
+  return { track };
+}

package/app/composables/useDuxtAnimatedHeight.ts

@@ -45,15 +45,6 @@ const HEIGHT_STEP = 24;
  */
 const SETTLE_MS = 60;
 
-/**
- * How long the content takes to come back once the box is on its way.
- *
- * Shorter than the box's own 300ms on purpose: the point is to be readable
- * again well before the box stops moving, not to make the reader wait out two
- * animations in a row.
- */
-const FADE_MS = 200;
-
 export function useDuxtAnimatedHeight(
   shell: Readonly<import('vue').ShallowRef<HTMLElement | null>>,
   body: Readonly<import('vue').ShallowRef<HTMLElement | null>>,
@@ -69,10 +60,10 @@ export function useDuxtAnimatedHeight(
 
     // The box carries the border and `box-sizing: border-box`, so its height
     // has to include what that border takes; the content's height does not.
-    const chrome = box.offsetHeight - box.clientHeight;
+    const borderHeight = box.offsetHeight - box.clientHeight;
 
     const step = (height: number) =>
-      Math.ceil((height + chrome) / HEIGHT_STEP) * HEIGHT_STEP;
+      Math.ceil((height + borderHeight) / HEIGHT_STEP) * HEIGHT_STEP;
 
     let last = step(content.offsetHeight);
 
@@ -90,28 +81,16 @@ export function useDuxtAnimatedHeight(
 
     let settle: ReturnType<typeof setTimeout> | undefined;
 
-    const reduced = window.matchMedia('(prefers-reduced-motion: reduce)');
-
     const observer = new ResizeObserver(() => {
       const next = step(content.offsetHeight);
       if (next === last) return;
 
-      // THE CONTENT FADES WHILE THE BOX TRAVELS.
-      //
-      // The new panel is there the instant the tab is clicked, and until the
-      // box has grown to fit it, `overflow-hidden` cuts it off — a taller
-      // sample appeared with its last lines sliced away for the length of the
-      // animation. Hidden for that moment and faded back in as the box arrives,
-      // there is nothing cut off to see: what a reader watches is one sample
-      // replacing another, not a box catching up with its contents.
-      //
-      // Set with the transition off, so it is instant going out and animated
-      // coming back — a fade in both directions would be twice as long a wait
-      // for the same effect.
-      if (!reduced.matches) {
-        content.style.transition = 'none';
-        content.style.opacity = '0';
-      }
+      // NOTHING FADES. The content used to be hidden while the box travelled and
+      // faded back in as it arrived, so a taller file was never seen cut off.
+      // What a reader saw instead was the block emptying first and filling
+      // again — the code gone for the length of the fade on every tab change.
+      // Clipped by `overflow-hidden` and revealed as the box opens, the new file
+      // is there the whole time.
 
       // ONLY THE VALUE IT SETTLES ON, never the ones on the way.
       //
@@ -131,13 +110,6 @@ export function useDuxtAnimatedHeight(
           last = settled;
           box.style.height = `${settled}px`;
         }
-
-        if (!reduced.matches) {
-          requestAnimationFrame(() => {
-            content.style.transition = `opacity ${FADE_MS}ms ease-out`;
-            content.style.opacity = '1';
-          });
-        }
       }, SETTLE_MS);
     });
 
@@ -148,8 +120,6 @@ export function useDuxtAnimatedHeight(
       clearTimeout(settle);
       box.style.height = '';
       box.style.transition = '';
-      content.style.opacity = '';
-      content.style.transition = '';
     });
   });
 }

package/app/composables/useDuxtAnnouncements.ts

@@ -0,0 +1,153 @@
+/** Where the dismissals are kept. Namespaced so a consumer's keys cannot collide. */
+const STORAGE_KEY = 'duxt:announcements';
+
+/**
+ * The one timer the whole page needs, at module scope.
+ *
+ * Three placements mean up to three components asking the same question — when
+ * does the next window open or close — and three timers firing at the same
+ * millisecond to set the same value. Module scope is safe here because every
+ * write below sits behind `import.meta.client`: in the browser the module is
+ * one app for one page load, and on the server it is never touched at all.
+ */
+let timer: ReturnType<typeof setTimeout> | undefined;
+let scheduledFor: number | undefined;
+
+/**
+ * The announcements a placement should draw, and how a reader closes one.
+ *
+ * TWO configs are read, deliberately. The RESOLVED one is what the banner
+ * prints — `useDuxtConfig()` has collapsed each `text` to the reader's own
+ * language. The WRITTEN one is what a dismissal is remembered against, because
+ * a derived identity has to survive a language change, and a sentence resolved
+ * for `de-DE` is a different string from the same sentence resolved for
+ * `en-GB`. The two lists are the same list in the same order, so an index
+ * addresses the same announcement in both.
+ */
+export function useDuxtAnnouncements(placement: DuxtAnnouncementPlacement) {
+  const appConfig = useAppConfig();
+  const duxt = useDuxtConfig();
+
+  /** As the consumer wrote it: every locale of every sentence, still together. */
+  const written = computed<DuxtAnnouncement[]>(
+    () => mergeDuxtConfig(appConfig.duxt, duxtDefaults).announcements ?? []
+  );
+
+  /**
+   * The reader's clock, shared so the three placements never disagree about
+   * what time it is mid-render.
+   *
+   * Seeded at `0` rather than at `Date.now()`: `0` is before every window a
+   * consumer would write, so an announcement with a `startsAt` cannot flash
+   * during hydration before the real time arrives.
+   */
+  const now = useState<number>('duxt-announcements-now', () => 0);
+
+  /** The keys this reader has closed. Empty until the browser says otherwise. */
+  const dismissed = useState<string[]>(
+    'duxt-announcements-dismissed',
+    () => []
+  );
+
+  function read(): string[] {
+    // Blocked storage, or a value someone else wrote — either way, nothing has
+    // been dismissed and every due announcement shows.
+    const parsed = readStoredJson(STORAGE_KEY);
+
+    return Array.isArray(parsed)
+      ? parsed.filter((entry): entry is string => typeof entry === 'string')
+      : [];
+  }
+
+  /**
+   * Keep only the keys the config still names.
+   *
+   * Without it the list grows for the life of the browser profile: every
+   * announcement a site ever ran leaves a key behind, and none of them can ever
+   * match anything again — a derived key changes with its sentence, and a
+   * retired `id` is gone from the config.
+   */
+  function persist(keys: string[]) {
+    const live = new Set(written.value.map(duxtAnnouncementKey));
+    const next = keys.filter((key) => live.has(key));
+
+    dismissed.value = next;
+
+    // A dismissal that cannot be remembered still hides the banner for this
+    // page. Not worth an error the reader would have to read.
+    writeStoredJson(STORAGE_KEY, next);
+  }
+
+  /**
+   * Wake up exactly once, at the next moment the list changes.
+   *
+   * Not a poll: an announcement scheduled for next Tuesday costs one sleeping
+   * timer rather than a tick every second for six days. `setTimeout` overflows
+   * past 2^31 ms and fires immediately, so a longer wait is taken in day-long
+   * steps — each one simply re-asks the same question.
+   */
+  function schedule() {
+    if (!import.meta.client) return;
+
+    const next = duxtNextAnnouncementChange(written.value, now.value);
+
+    if (next === undefined) {
+      scheduledFor = undefined;
+      return;
+    }
+
+    if (timer !== undefined && scheduledFor === next) return;
+
+    const DAY = 86_400_000;
+    clearTimeout(timer);
+    scheduledFor = next;
+    timer = setTimeout(
+      () => {
+        timer = undefined;
+        scheduledFor = undefined;
+        now.value = Date.now();
+        schedule();
+      },
+      Math.min(Math.max(next - Date.now(), 0), DAY)
+    );
+  }
+
+  onMounted(() => {
+    now.value = Date.now();
+    persist(read());
+    schedule();
+  });
+
+  const visible = computed(() => {
+    const due = new Set(
+      duxtVisibleAnnouncements(written.value, {
+        placement,
+        now: now.value,
+        dismissed: dismissed.value,
+        maxVisible: duxt.announcementOptions?.maxVisible
+      })
+    );
+
+    // Paired back to the resolved list by POSITION: `resolveDuxtTexts` maps an
+    // array one to one, so index `n` is the same announcement in both — which
+    // is what lets the identity come from the written text and the words on
+    // screen from the resolved one.
+    return written.value.flatMap((announcement, index) =>
+      due.has(announcement)
+        ? [
+            {
+              key: duxtAnnouncementKey(announcement),
+              text: duxt.announcements?.[index]?.text ?? '',
+              link: duxt.announcements?.[index]?.link
+            }
+          ]
+        : []
+    );
+  });
+
+  function dismiss(key: string) {
+    persist([...dismissed.value, key]);
+  }
+
+  return { visible, dismiss };
+}

package/app/composables/useDuxtCopy.ts

@@ -0,0 +1,51 @@
+/**
+ * Copy a string to the clipboard, and say whether it worked.
+ *
+ * Every copy control on the site does the same four things — write, confirm
+ * with a toast, show a check for two seconds, report a refusal — and seven of
+ * them used to spell it out. The spellings had drifted: two reported a failure
+ * in English whatever the reader's language, one never confirmed a success at
+ * all, and none cleared its timer, so two copies inside two seconds reset the
+ * icon early.
+ *
+ * Returns whether the text reached the clipboard, which is what a caller
+ * reporting the copy needs: an analytics event for a copy the clipboard
+ * refused would be a copy that never happened.
+ *
+ * `toast: false` for a control whose own label already changes to "Copied" —
+ * a second confirmation in the corner says the same thing twice.
+ */
+export function useDuxtCopy({
+  toast = true,
+  failureKey = 'duxt.code.copyFailed'
+}: { toast?: boolean; failureKey?: string } = {}) {
+  const copied = ref(false);
+  const notify = useDuxtToast();
+  const { t } = useI18n();
+
+  let reset: ReturnType<typeof setTimeout> | undefined;
+
+  async function copy(text: string | undefined): Promise<boolean> {
+    if (!text) return false;
+
+    try {
+      await navigator.clipboard.writeText(text);
+    } catch {
+      // Unavailable over plain HTTP, or refused by the browser.
+      notify.error(t(failureKey));
+      return false;
+    }
+
+    copied.value = true;
+    if (toast) notify.success(t('duxt.code.copiedToast'));
+
+    clearTimeout(reset);
+    reset = setTimeout(() => (copied.value = false), 2000);
+
+    return true;
+  }
+
+  onScopeDispose(() => clearTimeout(reset));
+
+  return { copied, copy };
+}

package/app/composables/useDuxtDirection.ts

@@ -0,0 +1,23 @@
+import { localeDirection } from '@duxt/utils/direction';
+import type { DuxtDirection } from '@duxt/utils/direction';
+
+/**
+ * Which way round this page is drawn.
+ *
+ * Two shells need the answer and neither can borrow it from the other:
+ * `error.vue` REPLACES `app.vue` rather than nesting inside it, which is how
+ * the error page came to set `lang` and never `dir`. One composable, both
+ * shells, and the layer's one statement about direction.
+ *
+ * WHAT THE ANSWER IS FOR is wider than the `<html>` attribute. reka-ui reads
+ * its direction from a `ConfigProvider` and from nothing else — `useDirection`
+ * injects that context and defaults to `ltr`, never looking at the document —
+ * so a menu, a select and a tooltip stay left-to-right under a right-to-left
+ * page unless the same value is handed to the provider. That is the difference
+ * between a theme that CAN be mirrored and one that merely says it is.
+ */
+export function useDuxtDirection(): ComputedRef<DuxtDirection> {
+  const { locale, locales } = useI18n();
+
+  return computed(() => localeDirection(locales.value, locale.value));
+}

package/app/composables/useDuxtNavigation.ts

@@ -1,4 +1,5 @@
 import type { ContentNavigationItem } from '@nuxt/content';
+import { tfplugindocsNavigation } from '../../tfplugindocs';
 
 /**
  * Which collections the navigation is being fetched from.
@@ -22,7 +23,11 @@ import type { ContentNavigationItem } from '@nuxt/content';
 const useNavigationSource = () =>
   useState('duxt-navigation-source', () => ({
     base: 'docs' as DuxtCollectionName,
-    translation: 'docs' as DuxtCollectionName
+    translation: 'docs' as DuxtCollectionName,
+    // The base source's tfplugindocs prefix, or `undefined` for any other
+    // flavour. Resolved in `useDuxtNavigation`, never in the handler — see
+    // the note there.
+    tfplugindocsPrefix: undefined as string | undefined
   }));
 
 /**
@@ -35,19 +40,28 @@ const useNavigationSource = () =>
  * see `overlayTranslations`.
  */
 const handler = async (): Promise<ContentNavigationItem[]> => {
-  // Read BEFORE the first await: after it, the route may have moved on.
-  const { base, translation } = useNavigationSource().value;
+  // Read BEFORE the first await: after it, the route may have moved on — and
+  // the Nuxt instance is gone. NOTHING below the first await may call a
+  // composable: `useDuxtConfig()` sat under it once, threw E1001 on every
+  // request, and the handler's error left every page without a sidebar.
+  // `tests/async-data-context.test.ts` holds that line.
+  const { base, translation, tfplugindocsPrefix } = useNavigationSource().value;
 
   const tree = await queryCollectionNavigation(base as DuxtCollectionArg, [
     'icon',
-    'description'
+    'description',
+    'subcategory'
   ]);
 
   // Before the overlay: a folder's title comes from its own index page, and a
   // translated index has to be able to carry that up with it.
   const named = titleFoldersFromIndex(tree);
+  const navigable =
+    tfplugindocsPrefix === undefined
+      ? named
+      : tfplugindocsNavigation(named, tfplugindocsPrefix);
 
-  if (translation === base) return named;
+  if (translation === base) return navigable;
 
   const translated = await queryCollection(translation as DuxtCollectionArg)
     .select('path', 'title', 'description')
@@ -55,7 +69,7 @@ const handler = async (): Promise<ContentNavigationItem[]> => {
 
   return titleFoldersFromIndex(
     overlayTranslations(
-      named,
+      navigable,
       new Map(translated.map((page) => [page.path, page]))
     )
   );
@@ -68,14 +82,20 @@ const handler = async (): Promise<ContentNavigationItem[]> => {
  * one cache entry, and neither may two languages of one.
  */
 export function useDuxtNavigation() {
-  const { collection, baseCollection } = useDuxtCollection();
+  const { collection, baseCollection, sources } = useDuxtCollection();
   const source = useNavigationSource();
 
   // Kept in step before every fetch, including the ones `watch` triggers.
   watchEffect(() => {
+    const base = sources.value.find(
+      (entry) => entry.collection === baseCollection.value
+    );
+
     source.value = {
       base: baseCollection.value,
-      translation: collection.value
+      translation: collection.value,
+      tfplugindocsPrefix:
+        base?.flavor === 'tfplugindocs' ? base.prefix : undefined
     };
   });
 

package/app/composables/useDuxtPath.ts

@@ -8,11 +8,7 @@ export function useDuxtPath() {
   const route = useRoute();
   const { locales } = useI18n();
 
-  const codes = computed(() =>
-    locales.value.map((entry) =>
-      typeof entry === 'string' ? entry : entry.code
-    )
-  );
+  const codes = computed(() => localeCodesOf(locales.value));
 
   return computed(() => stripLocalePrefix(route.path, codes.value));
 }
@@ -30,6 +26,8 @@ export function useDuxtLink() {
 
   return (to?: string) => {
     if (!to?.startsWith('/')) return to;
+    // A root server route has no locale variant — see `isMachineRoute`.
+    if (isMachineRoute(to)) return to;
 
     // localePath resolves a route, and a trailing anchor is not part of one.
     // Split it off and put it back, so a sidebar entry pointing at a heading