From 6c77b62f727cca950cd5fb9521e1e24082c596a7 Mon Sep 17 00:00:00 2001
From: Hong Minhee <hong@minhee.org>
Date: Thu, 23 Apr 2026 14:00:24 +0900
Subject: [PATCH 1/8] Expose per-page Markdown in docs

Add a compact per-page Markdown action to the docs so readers can
open or copy the generated Markdown for the current page without
guessing the output path.

Adjust the docs site integration so the action sits alongside page
titles, behaves safely in the dev server, and keeps llms.txt and
llms-full.txt curated by excluding high-noise pages.

Closes https://github.com/fedify-dev/fedify/issues/706

Assisted-by: Codex:gpt-5.4
---
 CHANGES.md                                    |   9 +
 docs/.vitepress/config.mts                    |  22 +-
 .../theme/components/PageMarkdownActions.vue  | 223 ++++++++++++++++++
 docs/.vitepress/theme/index.ts                |   8 +
 docs/.vitepress/theme/style.css               |  32 +++
 5 files changed, 286 insertions(+), 8 deletions(-)
 create mode 100644 docs/.vitepress/theme/components/PageMarkdownActions.vue

diff --git a/CHANGES.md b/CHANGES.md
index f44810d85..35bde51ed 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -202,6 +202,13 @@ To be released.
 
 ### Docs
 
+ -  Added a per-page Markdown action to the docs site so readers can open or
+    copy the LLM-friendly Markdown for the current page without guessing the
+    generated `*.md` path or starting from *llms.txt*.  The action is now
+    available directly from each documentation page while *llms.txt* and
+    *llms-full.txt* continue to exclude high-noise pages such as the changelog,
+    contribution guide, README, and sponsors page.  [[#706], [#715]]
+
  -  Added [*Building a federated blog* tutorial] showing how to layer
     ActivityPub federation onto an [Astro] + [Bun] blog: actor setup,
     follower management, SQLite persistence, sending `Create`/`Update`/
@@ -226,6 +233,8 @@ To be released.
 [#691]: https://github.com/fedify-dev/fedify/issues/691
 [#695]: https://github.com/fedify-dev/fedify/pull/695
 [#704]: https://github.com/fedify-dev/fedify/issues/704
+[#706]: https://github.com/fedify-dev/fedify/issues/706
+[#715]: https://github.com/fedify-dev/fedify/pull/715
 
 
 Version 2.1.10
diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts
index 6f3f2d2f2..5d3a1b089 100644
--- a/docs/.vitepress/config.mts
+++ b/docs/.vitepress/config.mts
@@ -311,14 +311,20 @@ export default withMermaid(defineConfig({
     plugins: [
       groupIconVitePlugin(),
       llmstxt({
-        ignoreFiles: [
-          "changelog.md",
-          "contribute.md",
-          "README.md",
-          "security.md",
-          "sponsors.md",
-          "tutorial.md",
-        ],
+        ignoreFilesPerOutput: {
+          llmsTxt: [
+            "changelog.md",
+            "contribute.md",
+            "README.md",
+            "sponsors.md",
+          ],
+          llmsFullTxt: [
+            "changelog.md",
+            "contribute.md",
+            "README.md",
+            "sponsors.md",
+          ],
+        },
       }),
     ],
   },
diff --git a/docs/.vitepress/theme/components/PageMarkdownActions.vue b/docs/.vitepress/theme/components/PageMarkdownActions.vue
new file mode 100644
index 000000000..ae9cf459d
--- /dev/null
+++ b/docs/.vitepress/theme/components/PageMarkdownActions.vue
@@ -0,0 +1,223 @@
+<script setup lang="ts">
+import { useRoute } from "vitepress";
+import { computed, nextTick, onMounted, ref, watch } from "vue";
+import { Teleport } from "vue";
+
+const copied = ref(false);
+const copyFailed = ref(false);
+const path = ref<string | null>(null);
+const targetReady = ref(false);
+const isDev = import.meta.env.DEV;
+const devMessage =
+  "Markdown actions are not available in the VitePress dev server. Please use the built docs instead.";
+const route = useRoute();
+
+onMounted(() => {
+  const { pathname } = window.location;
+  path.value = pathname === "/"
+    ? "/index.md"
+    : `${pathname.replace(/\/+$/, "").replace(/\.html$/, "")}.md`;
+});
+
+function ensureTarget(): void {
+  const h1 = document.querySelector(".vp-doc h1");
+  if (!(h1 instanceof HTMLElement)) {
+    targetReady.value = false;
+    return;
+  }
+
+  const existingWrapper = h1.parentElement;
+  if (existingWrapper?.classList.contains("page-title-row")) {
+    targetReady.value = existingWrapper.querySelector(".page-title-actions-target") != null;
+    return;
+  }
+
+  const wrapper = document.createElement("div");
+  wrapper.className = "page-title-row";
+  const target = document.createElement("div");
+  target.className = "page-title-actions-target";
+
+  h1.parentNode?.insertBefore(wrapper, h1);
+  wrapper.appendChild(h1);
+  wrapper.appendChild(target);
+  targetReady.value = true;
+}
+
+watch(
+  () => route.path,
+  async () => {
+    targetReady.value = false;
+    await nextTick();
+    ensureTarget();
+  },
+  { immediate: true },
+);
+
+const markdownPath = computed(() => path.value);
+
+async function getMarkdown(): Promise<string> {
+  if (markdownPath.value == null) {
+    throw new Error("Markdown path is not available yet.");
+  }
+  const response = await fetch(markdownPath.value);
+  if (!response.ok) {
+    throw new Error(`Failed to load ${markdownPath.value}: ${response.status}`);
+  }
+  return await response.text();
+}
+
+async function copyMarkdown(): Promise<void> {
+  if (isDev) {
+    window.alert(devMessage);
+    return;
+  }
+  try {
+    const text = await getMarkdown();
+    await navigator.clipboard.writeText(text);
+    copied.value = true;
+    copyFailed.value = false;
+    window.setTimeout(() => {
+      copied.value = false;
+    }, 2000);
+  } catch {
+    copyFailed.value = true;
+    window.setTimeout(() => {
+      copyFailed.value = false;
+    }, 2500);
+  }
+}
+
+function viewMarkdown(event: MouseEvent): void {
+  if (!isDev) return;
+  event.preventDefault();
+  window.alert(devMessage);
+}
+</script>
+
+<template>
+  <Teleport v-if="markdownPath != null && targetReady" to=".page-title-actions-target">
+    <details class="page-markdown-actions__menu">
+      <summary class="page-markdown-actions__trigger">
+        <span>Markdown</span>
+        <svg
+          class="page-markdown-actions__chevron"
+          viewBox="0 0 16 16"
+          fill="none"
+          aria-hidden="true"
+        >
+          <path
+            d="M4 6.5 8 10l4-3.5"
+            stroke="currentColor"
+            stroke-linecap="round"
+            stroke-linejoin="round"
+            stroke-width="1.6"
+          />
+        </svg>
+      </summary>
+      <div class="page-markdown-actions__dropdown">
+        <a
+          class="page-markdown-actions__item"
+          :href="markdownPath"
+          target="_blank"
+          rel="noreferrer"
+          @click="viewMarkdown"
+        >
+          View as Markdown
+        </a>
+        <button class="page-markdown-actions__item" type="button" @click="copyMarkdown">
+          {{ copied ? "Copied" : copyFailed ? "Copy failed" : "Copy Markdown" }}
+        </button>
+      </div>
+    </details>
+  </Teleport>
+</template>
+
+<style scoped>
+.page-markdown-actions__menu {
+  position: relative;
+}
+
+.page-markdown-actions__trigger {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  border: 1px solid var(--vp-c-divider);
+  border-radius: 999px;
+  background: color-mix(in srgb, var(--vp-c-bg-soft) 72%, transparent);
+  color: var(--vp-c-text-1);
+  font-size: 0.8125rem;
+  font-weight: 600;
+  line-height: 1.2;
+  list-style: none;
+  gap: 0.45rem;
+  min-height: 2.1rem;
+  padding: 0.45rem 0.85rem;
+  cursor: pointer;
+  box-shadow: 0 1px 2px rgb(0 0 0 / 0.04);
+  transition:
+    border-color 0.2s ease,
+    background-color 0.2s ease,
+    color 0.2s ease,
+    box-shadow 0.2s ease,
+    transform 0.2s ease;
+}
+
+.page-markdown-actions__trigger::-webkit-details-marker {
+  display: none;
+}
+
+.page-markdown-actions__trigger:hover,
+.page-markdown-actions__menu[open] > .page-markdown-actions__trigger {
+  border-color: var(--vp-c-brand-1);
+  background: var(--vp-c-bg);
+  color: var(--vp-c-brand-1);
+  box-shadow: 0 8px 20px rgb(0 0 0 / 0.08);
+}
+
+.page-markdown-actions__chevron {
+  flex: none;
+  width: 0.95rem;
+  height: 0.95rem;
+  margin-right: -0.05rem;
+  transition: transform 0.2s ease;
+}
+
+.page-markdown-actions__menu[open] .page-markdown-actions__chevron {
+  transform: rotate(180deg);
+}
+
+.page-markdown-actions__dropdown {
+  position: absolute;
+  top: 100%;
+  right: 0;
+  z-index: 20;
+  min-width: 13rem;
+  padding: 0.35rem;
+  border: 1px solid var(--vp-c-divider);
+  border-radius: 0.75rem;
+  background: var(--vp-c-bg);
+  box-shadow: var(--vp-shadow-3);
+}
+
+.page-markdown-actions__item {
+  display: flex;
+  width: 100%;
+  align-items: center;
+  border: 0;
+  border-radius: 0.5rem;
+  background: transparent;
+  color: var(--vp-c-text-1);
+  font: inherit;
+  font-size: 0.875rem;
+  line-height: 1.3;
+  padding: 0.55rem 0.7rem;
+  text-align: left;
+  text-decoration: none;
+  cursor: pointer;
+}
+
+.page-markdown-actions__item:hover {
+  background: var(--vp-c-bg-soft);
+  color: var(--vp-c-brand-1);
+}
+</style>
diff --git a/docs/.vitepress/theme/index.ts b/docs/.vitepress/theme/index.ts
index 5e7ae909f..97c17ba1a 100644
--- a/docs/.vitepress/theme/index.ts
+++ b/docs/.vitepress/theme/index.ts
@@ -1,6 +1,8 @@
 import TwoslashFloatingVue from "@shikijs/vitepress-twoslash/client";
 import "virtual:group-icons.css";
 import type { EnhanceAppContext } from "vitepress";
+import { h } from "vue";
+import PageMarkdownActions from "./components/PageMarkdownActions.vue";
 import Theme from "vitepress/theme";
 
 import "@shikijs/vitepress-twoslash/style.css";
@@ -8,7 +10,13 @@ import "./style.css";
 
 export default {
   extends: Theme,
+  Layout() {
+    return h(Theme.Layout, null, {
+      "doc-before": () => h(PageMarkdownActions),
+    });
+  },
   enhanceApp({ app }: EnhanceAppContext) {
     app.use(TwoslashFloatingVue);
+    app.component("PageMarkdownActions", PageMarkdownActions);
   },
 };
diff --git a/docs/.vitepress/theme/style.css b/docs/.vitepress/theme/style.css
index 1545b1348..0365402d4 100644
--- a/docs/.vitepress/theme/style.css
+++ b/docs/.vitepress/theme/style.css
@@ -34,3 +34,35 @@ main dl dd {
   margin-top: .25rem;
   margin-bottom: 1rem;
 }
+
+@media (min-width: 960px) {
+  .VPDoc .content-container .page-title-row {
+    display: flex;
+    align-items: flex-start;
+    justify-content: space-between;
+    gap: 1rem;
+  }
+
+  .VPDoc .content-container .page-title-row > h1 {
+    flex: 1 1 auto;
+    min-width: 0;
+    margin: 0;
+  }
+
+  .VPDoc .content-container .page-title-actions-target {
+    flex: none;
+    margin-top: -.8rem;
+  }
+}
+
+@media (max-width: 959px) {
+  .VPDoc .content-container .page-title-row {
+    display: flex;
+    flex-direction: column;
+    gap: .75rem;
+  }
+
+  .VPDoc .content-container .page-title-actions-target {
+    align-self: flex-end;
+  }
+}

From 344b9f9c4ee372614db99a04aaac87a5234efd12 Mon Sep 17 00:00:00 2001
From: Hong Minhee <hong@minhee.org>
Date: Thu, 23 Apr 2026 14:34:46 +0900
Subject: [PATCH 2/8] Fix Markdown action routing and timing

Make the docs Markdown action follow VitePress route changes,
avoid DOM work before mount, and handle index-style page paths
correctly. This keeps the action pointed at the current page and
prevents stale UI state after copy failures.

https://github.com/fedify-dev/fedify/pull/715#discussion_r3128482202
https://github.com/fedify-dev/fedify/pull/715#discussion_r3128495074
https://github.com/fedify-dev/fedify/pull/715#discussion_r3128495087

Assisted-by: Codex:gpt-5.4
---
 .../theme/components/PageMarkdownActions.vue  | 71 ++++++++++++-------
 1 file changed, 44 insertions(+), 27 deletions(-)

diff --git a/docs/.vitepress/theme/components/PageMarkdownActions.vue b/docs/.vitepress/theme/components/PageMarkdownActions.vue
index ae9cf459d..b904d3d26 100644
--- a/docs/.vitepress/theme/components/PageMarkdownActions.vue
+++ b/docs/.vitepress/theme/components/PageMarkdownActions.vue
@@ -1,22 +1,22 @@
 <script setup lang="ts">
 import { useRoute } from "vitepress";
 import { computed, nextTick, onMounted, ref, watch } from "vue";
-import { Teleport } from "vue";
 
 const copied = ref(false);
 const copyFailed = ref(false);
-const path = ref<string | null>(null);
 const targetReady = ref(false);
 const isDev = import.meta.env.DEV;
 const devMessage =
   "Markdown actions are not available in the VitePress dev server. Please use the built docs instead.";
 const route = useRoute();
-
-onMounted(() => {
-  const { pathname } = window.location;
-  path.value = pathname === "/"
-    ? "/index.md"
-    : `${pathname.replace(/\/+$/, "").replace(/\.html$/, "")}.md`;
+let copiedResetTimeout: number | null = null;
+let copyFailedResetTimeout: number | null = null;
+
+const markdownPath = computed(() => {
+  let path = route.path.replace(/\.html$/, "");
+  if (path === "/") return "/index.md";
+  if (path.endsWith("/")) return `${path}index.md`;
+  return `${path.replace(/\/+$/, "")}.md`;
 });
 
 function ensureTarget(): void {
@@ -43,22 +43,34 @@ function ensureTarget(): void {
   targetReady.value = true;
 }
 
-watch(
-  () => route.path,
-  async () => {
-    targetReady.value = false;
-    await nextTick();
-    ensureTarget();
-  },
-  { immediate: true },
-);
+async function updateTarget(): Promise<void> {
+  targetReady.value = false;
+  await nextTick();
+  ensureTarget();
+}
+
+onMounted(() => {
+  void updateTarget();
+  watch(() => route.path, updateTarget);
+});
+
+function resetCopiedState(delay: number): void {
+  if (copiedResetTimeout != null) window.clearTimeout(copiedResetTimeout);
+  copiedResetTimeout = window.setTimeout(() => {
+    copied.value = false;
+    copiedResetTimeout = null;
+  }, delay);
+}
 
-const markdownPath = computed(() => path.value);
+function resetCopyFailedState(delay: number): void {
+  if (copyFailedResetTimeout != null) window.clearTimeout(copyFailedResetTimeout);
+  copyFailedResetTimeout = window.setTimeout(() => {
+    copyFailed.value = false;
+    copyFailedResetTimeout = null;
+  }, delay);
+}
 
 async function getMarkdown(): Promise<string> {
-  if (markdownPath.value == null) {
-    throw new Error("Markdown path is not available yet.");
-  }
   const response = await fetch(markdownPath.value);
   if (!response.ok) {
     throw new Error(`Failed to load ${markdownPath.value}: ${response.status}`);
@@ -76,14 +88,19 @@ async function copyMarkdown(): Promise<void> {
     await navigator.clipboard.writeText(text);
     copied.value = true;
     copyFailed.value = false;
-    window.setTimeout(() => {
-      copied.value = false;
-    }, 2000);
+    if (copyFailedResetTimeout != null) {
+      window.clearTimeout(copyFailedResetTimeout);
+      copyFailedResetTimeout = null;
+    }
+    resetCopiedState(2000);
   } catch {
+    copied.value = false;
     copyFailed.value = true;
-    window.setTimeout(() => {
-      copyFailed.value = false;
-    }, 2500);
+    if (copiedResetTimeout != null) {
+      window.clearTimeout(copiedResetTimeout);
+      copiedResetTimeout = null;
+    }
+    resetCopyFailedState(2500);
   }
 }
 

From 2a165441c35a65b73f13c80263dd3652507a9d69 Mon Sep 17 00:00:00 2001
From: Hong Minhee <hong@minhee.org>
Date: Thu, 23 Apr 2026 14:37:01 +0900
Subject: [PATCH 3/8] Match changelog file path formatting

Format *README.md* in the changelog entry so the docs section
follows the repository's Markdown file path style.

https://github.com/fedify-dev/fedify/pull/715#discussion_r3128482211

Assisted-by: Codex:gpt-5.4
---
 CHANGES.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/CHANGES.md b/CHANGES.md
index 35bde51ed..8f4655411 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -207,7 +207,7 @@ To be released.
     generated `*.md` path or starting from *llms.txt*.  The action is now
     available directly from each documentation page while *llms.txt* and
     *llms-full.txt* continue to exclude high-noise pages such as the changelog,
-    contribution guide, README, and sponsors page.  [[#706], [#715]]
+    contribution guide, *README.md*, and sponsors page.  [[#706], [#715]]
 
  -  Added [*Building a federated blog* tutorial] showing how to layer
     ActivityPub federation onto an [Astro] + [Bun] blog: actor setup,

From 2e0d5f09b709278592753ad89544769e85d1bca1 Mon Sep 17 00:00:00 2001
From: Hong Minhee <hong@minhee.org>
Date: Thu, 23 Apr 2026 14:45:33 +0900
Subject: [PATCH 4/8] Harden the docs Markdown dropdown

Make the docs Markdown dropdown wait for the current page heading,
clean up its injected title wrapper on unmount, and close the menu
after actions so repeated navigation leaves no stale open state.

https://github.com/fedify-dev/fedify/pull/715#discussion_r3128568494
https://github.com/fedify-dev/fedify/pull/715#discussion_r3128568502
https://github.com/fedify-dev/fedify/pull/715#discussion_r3128568506

Assisted-by: Codex:gpt-5.4
---
 .../theme/components/PageMarkdownActions.vue  | 73 +++++++++++++++++--
 1 file changed, 66 insertions(+), 7 deletions(-)

diff --git a/docs/.vitepress/theme/components/PageMarkdownActions.vue b/docs/.vitepress/theme/components/PageMarkdownActions.vue
index b904d3d26..43057843f 100644
--- a/docs/.vitepress/theme/components/PageMarkdownActions.vue
+++ b/docs/.vitepress/theme/components/PageMarkdownActions.vue
@@ -1,6 +1,6 @@
 <script setup lang="ts">
 import { useRoute } from "vitepress";
-import { computed, nextTick, onMounted, ref, watch } from "vue";
+import { computed, nextTick, onBeforeUnmount, onMounted, ref, watch } from "vue";
 
 const copied = ref(false);
 const copyFailed = ref(false);
@@ -11,6 +11,8 @@ const devMessage =
 const route = useRoute();
 let copiedResetTimeout: number | null = null;
 let copyFailedResetTimeout: number | null = null;
+let currentWrapper: HTMLElement | null = null;
+let currentTarget: HTMLElement | null = null;
 
 const markdownPath = computed(() => {
   let path = route.path.replace(/\.html$/, "");
@@ -19,8 +21,28 @@ const markdownPath = computed(() => {
   return `${path.replace(/\/+$/, "")}.md`;
 });
 
-function ensureTarget(): void {
-  const h1 = document.querySelector(".vp-doc h1");
+function cleanupTarget(): void {
+  if (
+    currentWrapper == null ||
+    currentTarget == null ||
+    currentWrapper.parentNode == null
+  ) {
+    currentWrapper = null;
+    currentTarget = null;
+    return;
+  }
+
+  const heading = currentWrapper.querySelector(":scope > h1");
+  if (heading instanceof HTMLElement) {
+    currentWrapper.parentNode.insertBefore(heading, currentWrapper);
+  }
+  currentWrapper.remove();
+  currentWrapper = null;
+  currentTarget = null;
+}
+
+function ensureTarget(heading: Element | null): void {
+  const h1 = heading;
   if (!(h1 instanceof HTMLElement)) {
     targetReady.value = false;
     return;
@@ -28,7 +50,9 @@ function ensureTarget(): void {
 
   const existingWrapper = h1.parentElement;
   if (existingWrapper?.classList.contains("page-title-row")) {
-    targetReady.value = existingWrapper.querySelector(".page-title-actions-target") != null;
+    currentWrapper = existingWrapper;
+    currentTarget = existingWrapper.querySelector(".page-title-actions-target");
+    targetReady.value = currentTarget != null;
     return;
   }
 
@@ -40,13 +64,34 @@ function ensureTarget(): void {
   h1.parentNode?.insertBefore(wrapper, h1);
   wrapper.appendChild(h1);
   wrapper.appendChild(target);
+  currentWrapper = wrapper;
+  currentTarget = target;
   targetReady.value = true;
 }
 
+function waitForHeading(maxFrames = 8): Promise<Element | null> {
+  return new Promise((resolve) => {
+    let frame = 0;
+
+    const check = () => {
+      const heading = document.querySelector(".vp-doc h1");
+      if (heading != null || frame >= maxFrames) {
+        resolve(heading);
+        return;
+      }
+      frame++;
+      window.requestAnimationFrame(check);
+    };
+
+    check();
+  });
+}
+
 async function updateTarget(): Promise<void> {
   targetReady.value = false;
   await nextTick();
-  ensureTarget();
+  const heading = await waitForHeading();
+  ensureTarget(heading);
 }
 
 onMounted(() => {
@@ -54,6 +99,17 @@ onMounted(() => {
   watch(() => route.path, updateTarget);
 });
 
+onBeforeUnmount(() => {
+  cleanupTarget();
+  if (copiedResetTimeout != null) window.clearTimeout(copiedResetTimeout);
+  if (copyFailedResetTimeout != null) window.clearTimeout(copyFailedResetTimeout);
+});
+
+function closeMenu(event: Event): void {
+  const details = (event.currentTarget as HTMLElement | null)?.closest("details");
+  if (details instanceof HTMLDetailsElement) details.open = false;
+}
+
 function resetCopiedState(delay: number): void {
   if (copiedResetTimeout != null) window.clearTimeout(copiedResetTimeout);
   copiedResetTimeout = window.setTimeout(() => {
@@ -78,8 +134,9 @@ async function getMarkdown(): Promise<string> {
   return await response.text();
 }
 
-async function copyMarkdown(): Promise<void> {
+async function copyMarkdown(event: MouseEvent): Promise<void> {
   if (isDev) {
+    closeMenu(event);
     window.alert(devMessage);
     return;
   }
@@ -93,6 +150,7 @@ async function copyMarkdown(): Promise<void> {
       copyFailedResetTimeout = null;
     }
     resetCopiedState(2000);
+    closeMenu(event);
   } catch {
     copied.value = false;
     copyFailed.value = true;
@@ -105,6 +163,7 @@ async function copyMarkdown(): Promise<void> {
 }
 
 function viewMarkdown(event: MouseEvent): void {
+  closeMenu(event);
   if (!isDev) return;
   event.preventDefault();
   window.alert(devMessage);
@@ -112,7 +171,7 @@ function viewMarkdown(event: MouseEvent): void {
 </script>
 
 <template>
-  <Teleport v-if="markdownPath != null && targetReady" to=".page-title-actions-target">
+  <Teleport v-if="targetReady" to=".page-title-actions-target">
     <details class="page-markdown-actions__menu">
       <summary class="page-markdown-actions__trigger">
         <span>Markdown</span>

From 8fd8040d7db1c38b4c7d84094e7ae91bf131c59f Mon Sep 17 00:00:00 2001
From: Hong Minhee <hong@minhee.org>
Date: Thu, 23 Apr 2026 15:06:29 +0900
Subject: [PATCH 5/8] Stabilize Markdown action state updates

Prevent stale async title retargeting from older route updates,
restore the wrapped heading before each new retarget, and
invalidate pending work during unmount. This same pass also makes
copy failures distinguish between Markdown load problems and
clipboard write failures.

https://github.com/fedify-dev/fedify/pull/715#discussion_r3128611872

Assisted-by: Codex:gpt-5.4
---
 .../theme/components/PageMarkdownActions.vue  | 37 ++++++++++++++++---
 1 file changed, 31 insertions(+), 6 deletions(-)

diff --git a/docs/.vitepress/theme/components/PageMarkdownActions.vue b/docs/.vitepress/theme/components/PageMarkdownActions.vue
index 43057843f..21117878f 100644
--- a/docs/.vitepress/theme/components/PageMarkdownActions.vue
+++ b/docs/.vitepress/theme/components/PageMarkdownActions.vue
@@ -3,7 +3,7 @@ import { useRoute } from "vitepress";
 import { computed, nextTick, onBeforeUnmount, onMounted, ref, watch } from "vue";
 
 const copied = ref(false);
-const copyFailed = ref(false);
+const copyFailed = ref<"load" | "clipboard" | null>(null);
 const targetReady = ref(false);
 const isDev = import.meta.env.DEV;
 const devMessage =
@@ -13,6 +13,7 @@ let copiedResetTimeout: number | null = null;
 let copyFailedResetTimeout: number | null = null;
 let currentWrapper: HTMLElement | null = null;
 let currentTarget: HTMLElement | null = null;
+let targetUpdateVersion = 0;
 
 const markdownPath = computed(() => {
   let path = route.path.replace(/\.html$/, "");
@@ -88,9 +89,12 @@ function waitForHeading(maxFrames = 8): Promise<Element | null> {
 }
 
 async function updateTarget(): Promise<void> {
+  const version = ++targetUpdateVersion;
   targetReady.value = false;
+  cleanupTarget();
   await nextTick();
   const heading = await waitForHeading();
+  if (version !== targetUpdateVersion) return;
   ensureTarget(heading);
 }
 
@@ -100,6 +104,8 @@ onMounted(() => {
 });
 
 onBeforeUnmount(() => {
+  targetUpdateVersion++;
+  targetReady.value = false;
   cleanupTarget();
   if (copiedResetTimeout != null) window.clearTimeout(copiedResetTimeout);
   if (copyFailedResetTimeout != null) window.clearTimeout(copyFailedResetTimeout);
@@ -121,7 +127,7 @@ function resetCopiedState(delay: number): void {
 function resetCopyFailedState(delay: number): void {
   if (copyFailedResetTimeout != null) window.clearTimeout(copyFailedResetTimeout);
   copyFailedResetTimeout = window.setTimeout(() => {
-    copyFailed.value = false;
+    copyFailed.value = null;
     copyFailedResetTimeout = null;
   }, delay);
 }
@@ -142,9 +148,20 @@ async function copyMarkdown(event: MouseEvent): Promise<void> {
   }
   try {
     const text = await getMarkdown();
-    await navigator.clipboard.writeText(text);
+    try {
+      await navigator.clipboard.writeText(text);
+    } catch {
+      copied.value = false;
+      copyFailed.value = "clipboard";
+      if (copiedResetTimeout != null) {
+        window.clearTimeout(copiedResetTimeout);
+        copiedResetTimeout = null;
+      }
+      resetCopyFailedState(2500);
+      return;
+    }
     copied.value = true;
-    copyFailed.value = false;
+    copyFailed.value = null;
     if (copyFailedResetTimeout != null) {
       window.clearTimeout(copyFailedResetTimeout);
       copyFailedResetTimeout = null;
@@ -153,7 +170,7 @@ async function copyMarkdown(event: MouseEvent): Promise<void> {
     closeMenu(event);
   } catch {
     copied.value = false;
-    copyFailed.value = true;
+    copyFailed.value = "load";
     if (copiedResetTimeout != null) {
       window.clearTimeout(copiedResetTimeout);
       copiedResetTimeout = null;
@@ -201,7 +218,15 @@ function viewMarkdown(event: MouseEvent): void {
           View as Markdown
         </a>
         <button class="page-markdown-actions__item" type="button" @click="copyMarkdown">
-          {{ copied ? "Copied" : copyFailed ? "Copy failed" : "Copy Markdown" }}
+          {{
+            copied
+              ? "Copied"
+              : copyFailed === "load"
+              ? "Could not load Markdown"
+              : copyFailed === "clipboard"
+              ? "Clipboard blocked"
+              : "Copy Markdown"
+          }}
         </button>
       </div>
     </details>

From 376823fbca57379b5187e02ffa39418ddde62e97 Mon Sep 17 00:00:00 2001
From: Hong Minhee <hong@minhee.org>
Date: Thu, 23 Apr 2026 15:24:05 +0900
Subject: [PATCH 6/8] Ignore stale copy results after page changes

Reset copy feedback when the docs page retargets and ignore clipboard
results that complete after a newer route update. This keeps copy
status messages from leaking across VitePress SPA navigation.

https://github.com/fedify-dev/fedify/pull/715#discussion_r3128737517

Assisted-by: Codex:gpt-5.4
---
 docs/.vitepress/theme/components/PageMarkdownActions.vue | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/docs/.vitepress/theme/components/PageMarkdownActions.vue b/docs/.vitepress/theme/components/PageMarkdownActions.vue
index 21117878f..f64b21c73 100644
--- a/docs/.vitepress/theme/components/PageMarkdownActions.vue
+++ b/docs/.vitepress/theme/components/PageMarkdownActions.vue
@@ -91,6 +91,8 @@ function waitForHeading(maxFrames = 8): Promise<Element | null> {
 async function updateTarget(): Promise<void> {
   const version = ++targetUpdateVersion;
   targetReady.value = false;
+  copied.value = false;
+  copyFailed.value = null;
   cleanupTarget();
   await nextTick();
   const heading = await waitForHeading();
@@ -141,6 +143,7 @@ async function getMarkdown(): Promise<string> {
 }
 
 async function copyMarkdown(event: MouseEvent): Promise<void> {
+  const version = targetUpdateVersion;
   if (isDev) {
     closeMenu(event);
     window.alert(devMessage);
@@ -151,6 +154,7 @@ async function copyMarkdown(event: MouseEvent): Promise<void> {
     try {
       await navigator.clipboard.writeText(text);
     } catch {
+      if (version !== targetUpdateVersion) return;
       copied.value = false;
       copyFailed.value = "clipboard";
       if (copiedResetTimeout != null) {
@@ -160,6 +164,7 @@ async function copyMarkdown(event: MouseEvent): Promise<void> {
       resetCopyFailedState(2500);
       return;
     }
+    if (version !== targetUpdateVersion) return;
     copied.value = true;
     copyFailed.value = null;
     if (copyFailedResetTimeout != null) {
@@ -169,6 +174,7 @@ async function copyMarkdown(event: MouseEvent): Promise<void> {
     resetCopiedState(2000);
     closeMenu(event);
   } catch {
+    if (version !== targetUpdateVersion) return;
     copied.value = false;
     copyFailed.value = "load";
     if (copiedResetTimeout != null) {

From 8ffceb4bf3e799bbf989f0805e789ca7887fdcd2 Mon Sep 17 00:00:00 2001
From: Hong Minhee <hong@minhee.org>
Date: Thu, 23 Apr 2026 15:32:40 +0900
Subject: [PATCH 7/8] Close the Markdown menu after async copy

Capture the dropdown trigger before awaiting Markdown fetch and
clipboard writes so the menu still closes after a successful copy.
This avoids relying on event.currentTarget after async suspension.

https://github.com/fedify-dev/fedify/pull/715#discussion_r3128757940

Assisted-by: Codex:gpt-5.4
---
 .../theme/components/PageMarkdownActions.vue          | 11 ++++++-----
 1 file changed, 6 insertions(+), 5 deletions(-)

diff --git a/docs/.vitepress/theme/components/PageMarkdownActions.vue b/docs/.vitepress/theme/components/PageMarkdownActions.vue
index f64b21c73..5d2f672d3 100644
--- a/docs/.vitepress/theme/components/PageMarkdownActions.vue
+++ b/docs/.vitepress/theme/components/PageMarkdownActions.vue
@@ -113,8 +113,8 @@ onBeforeUnmount(() => {
   if (copyFailedResetTimeout != null) window.clearTimeout(copyFailedResetTimeout);
 });
 
-function closeMenu(event: Event): void {
-  const details = (event.currentTarget as HTMLElement | null)?.closest("details");
+function closeMenu(target: EventTarget | HTMLElement | null): void {
+  const details = (target as HTMLElement | null)?.closest("details");
   if (details instanceof HTMLDetailsElement) details.open = false;
 }
 
@@ -143,9 +143,10 @@ async function getMarkdown(): Promise<string> {
 }
 
 async function copyMarkdown(event: MouseEvent): Promise<void> {
+  const trigger = event.currentTarget as HTMLElement | null;
   const version = targetUpdateVersion;
   if (isDev) {
-    closeMenu(event);
+    closeMenu(trigger);
     window.alert(devMessage);
     return;
   }
@@ -172,7 +173,7 @@ async function copyMarkdown(event: MouseEvent): Promise<void> {
       copyFailedResetTimeout = null;
     }
     resetCopiedState(2000);
-    closeMenu(event);
+    closeMenu(trigger);
   } catch {
     if (version !== targetUpdateVersion) return;
     copied.value = false;
@@ -186,7 +187,7 @@ async function copyMarkdown(event: MouseEvent): Promise<void> {
 }
 
 function viewMarkdown(event: MouseEvent): void {
-  closeMenu(event);
+  closeMenu(event.currentTarget);
   if (!isDev) return;
   event.preventDefault();
   window.alert(devMessage);

From 71ac1467b3df846660b81055560ef8fcdc7601eb Mon Sep 17 00:00:00 2001
From: Hong Minhee <hong@minhee.org>
Date: Thu, 23 Apr 2026 16:12:51 +0900
Subject: [PATCH 8/8] Keep Markdown menu open after copy

Leave the docs Markdown dropdown open after a successful copy so
readers can actually see the copied state feedback. Viewing the page
as Markdown still closes the menu, but copy now favors immediate UI
confirmation over collapsing the dropdown.

Assisted-by: Codex:gpt-5.4
---
 docs/.vitepress/theme/components/PageMarkdownActions.vue | 1 -
 1 file changed, 1 deletion(-)

diff --git a/docs/.vitepress/theme/components/PageMarkdownActions.vue b/docs/.vitepress/theme/components/PageMarkdownActions.vue
index 5d2f672d3..5fc903aaa 100644
--- a/docs/.vitepress/theme/components/PageMarkdownActions.vue
+++ b/docs/.vitepress/theme/components/PageMarkdownActions.vue
@@ -173,7 +173,6 @@ async function copyMarkdown(event: MouseEvent): Promise<void> {
       copyFailedResetTimeout = null;
     }
     resetCopiedState(2000);
-    closeMenu(trigger);
   } catch {
     if (version !== targetUpdateVersion) return;
     copied.value = false;