ut.code(); LearnのremarkTermを実装し、キーワードのポップアップ・リンク

.gitignore

@@ -5,6 +5,7 @@
 
 # documentation
 /public/docs/**/sections.*
+/public/docs/**/termDefinitions.*
 /public/docs/languages.*
 /public/docs/revisions-dev.yml
 /public/docs/commits-dev.yml

README.md

@@ -101,6 +101,10 @@ Cloudflare Worker のビルドログとステータス表示が見れますが
       - このセクションに関連する、想定される質問例。
       # question: 自体を省略すると、GitHub ActionがGeminiを呼び出して質問例を生成しpushします。
       # 質問例が不要な場合は question: [] にしてください。
+    term:
+      - キーワード
+      - きーわーど
+      # 他のページで [[キーワード]] と書いた場合に、このセクションの内容がポップアップで表示される。
     ```
 * コード例はそれが配置されているセクションの内容と関連するようにする。
     ````md

app/(docs)/@chat/chat/[chatId]/page.tsx

@@ -4,7 +4,7 @@ import {
   getChatOne,
   initContext,
 } from "@/lib/chatHistory";
-import { getMarkdownSections, getPagesList } from "@/lib/docs";
+import { getMarkdownSections, getPagesListForLang, LangId } from "@/lib/docs";
 import { ChatAreaContainer, ChatAreaContent } from "./chatArea";
 import { cacheLife, cacheTag } from "next/cache";
 import { isCloudflare } from "@/lib/detectCloudflare";
@@ -29,9 +29,8 @@ export default async function ChatPage({
     );
   }
 
-  const pagesList = await getPagesList();
-  const targetLang = pagesList.find(
-    (lang) => lang.id === chatData.section.pagePath.split("/")[0]
+  const targetLang = await getPagesListForLang(
+    chatData.section.pagePath.split("/")[0] as LangId
   );
   const targetPage = targetLang?.pages.find(
     (page) => page.slug === chatData.section.pagePath.split("/")[1]

app/(docs)/@docs/[lang]/[pageId]/page.tsx

@@ -9,7 +9,8 @@ import {
 } from "@/lib/chatHistory";
 import {
   getMarkdownSections,
-  getPagesList,
+  getPagesListForLang,
+  getTermDefinitions,
   LangId,
   PagePath,
   PageSlug,
@@ -18,15 +19,15 @@ import { cacheLife, cacheTag } from "next/cache";
 import { isCloudflare } from "@/lib/detectCloudflare";
 import { DocsAutoRedirect } from "./autoRedirect";
 import { dateReviver } from "@/lib/dateReviver";
+import { TermDefinitionProvider } from "@/markdown/term";
 
 export async function generateMetadata({
   params,
 }: {
   params: Promise<{ lang: LangId; pageId: PageSlug }>;
 }): Promise<Metadata> {
   const { lang, pageId } = await params;
-  const pagesList = await getPagesList();
-  const langEntry = pagesList.find((l) => l.id === lang);
+  const langEntry = await getPagesListForLang(lang);
   const pageEntry = langEntry?.pages.find((p) => p.slug === pageId);
   if (!langEntry || !pageEntry) notFound();
 
@@ -45,8 +46,7 @@ export default async function Page({
   params: Promise<{ lang: LangId; pageId: PageSlug }>;
 }) {
   const { lang, pageId } = await params;
-  const pagesList = await getPagesList();
-  const langEntry = pagesList.find((l) => l.id === lang);
+  const langEntry = await getPagesListForLang(lang);
   const pageEntryIndex =
     langEntry?.pages.findIndex((p) => p.slug === pageId) ?? -1;
   const pageEntry = langEntry?.pages[pageEntryIndex];
@@ -62,17 +62,21 @@ export default async function Page({
   const context = await initContext();
   const chatHistories = await getChatFromCache(path, context.userId);
 
+  const termDefinitions = await getTermDefinitions(lang);
+
   return (
     <>
-      <PageContent
-        chatHistories={chatHistories}
-        splitMdContent={sections}
-        langEntry={langEntry}
-        pageEntry={pageEntry}
-        prevPage={prevPage}
-        nextPage={nextPage}
-        path={path}
-      />
+      <TermDefinitionProvider termDefinitions={termDefinitions} lang={lang}>
+        <PageContent
+          chatHistories={chatHistories}
+          splitMdContent={sections}
+          langEntry={langEntry}
+          pageEntry={pageEntry}
+          prevPage={prevPage}
+          nextPage={nextPage}
+          path={path}
+        />
+      </TermDefinitionProvider>
       <DocsAutoRedirect path={path} />
     </>
   );

app/api/chat/route.ts

@@ -9,7 +9,7 @@ import {
 import {
   DynamicMarkdownSectionSchema,
   getMarkdownSections,
-  getPagesList,
+  getPagesListForLang,
   introSectionId,
   PagePathSchema,
   SectionId,
@@ -57,8 +57,7 @@ export async function POST(request: NextRequest) {
     execResults,
   } = parseResult.data;
 
-  const pagesList = await getPagesList();
-  const langEntry = pagesList.find((lang) => lang.id === path.lang);
+  const langEntry = await getPagesListForLang(path.lang);
   const langName = langEntry?.name ?? path.lang;
   let targetPath = path;
   let targetSectionContent = sectionContent;

app/lib/docs.ts

@@ -43,6 +43,10 @@ export const SectionFrontMatterSchema = z.object({
    * scripts/questionExample.ts で生成する
    */
   question: z.array(z.string()).optional(),
+  /**
+   * 他のページで [[キーワード]] と書いた場合に、このセクションの内容がポップアップで表示される。
+   */
+  term: z.array(z.string()).optional(),
 });
 export type SectionFrontMatter = z.output<typeof SectionFrontMatterSchema>;
 export const MarkdownSectionSchema = SectionFrontMatterSchema.extend({
@@ -61,6 +65,15 @@ export const MarkdownSectionSchema = SectionFrontMatterSchema.extend({
 });
 export type MarkdownSection = z.output<typeof MarkdownSectionSchema>;
 
+export const TermDefinitionSchema = z.object({
+  term: z.array(z.string()),
+  page: z.string().transform((s) => s as PageSlug),
+  id: z.string().transform((s) => s as SectionId),
+  title: z.string(),
+  rawContentWithoutCode: z.string(),
+});
+export type TermDefinition = z.output<typeof TermDefinitionSchema>;
+
 export const ReplacedRangeSchema = z.object({
   start: z.number(),
   end: z.number(),
@@ -197,22 +210,23 @@ async function getLanguageIds(): Promise<LangId[]> {
 
 export async function getPagesList(): Promise<LanguageEntry[]> {
   const langIds = await getLanguageIds();
-  return await Promise.all(
-    langIds.map(async (langId) => {
-      const raw = await readPublicFile(`docs/${langId}/index.yml`);
-      const data = yaml.load(raw) as IndexYml;
-      return {
-        id: langId,
-        name: data.name as LangName,
-        description: data.description,
-        pages: data.pages.map((p, index) => ({
-          ...p,
-          slug: p.slug as PageSlug,
-          index,
-        })),
-      };
-    })
-  );
+  return await Promise.all(langIds.map(getPagesListForLang));
+}
+export async function getPagesListForLang(
+  langId: LangId
+): Promise<LanguageEntry> {
+  const raw = await readPublicFile(`docs/${langId}/index.yml`);
+  const data = yaml.load(raw) as IndexYml;
+  return {
+    id: langId,
+    name: data.name as LangName,
+    description: data.description,
+    pages: data.pages.map((p, index) => ({
+      ...p,
+      slug: p.slug as PageSlug,
+      index,
+    })),
+  };
 }
 
 export async function getRevisions(
@@ -328,6 +342,7 @@ function parseFrontmatter(content: string, file: string): MarkdownSection {
     title: fm.title,
     level: fm.level,
     question: fm.question,
+    term: fm.term,
     rawContent,
     md5: crypto.createHash("md5").update(rawContent).digest("base64"),
   };
@@ -360,3 +375,47 @@ export async function getRevisionOfMarkdownSection(
     );
   }
 }
+
+export async function getTermDefinitions(
+  langId: LangId
+): Promise<TermDefinition[]> {
+  if (isCloudflare()) {
+    const termsJson = await readPublicFile(
+      `docs/${langId}/termDefinitions.json`
+    );
+    return JSON.parse(termsJson) as TermDefinition[];
+  } else {
+    // これに関しては<Term>の表示のたびに毎回全ファイルを読むのは非効率なので、
+    // cloudflareでない場合でも事前生成済みファイルがあれば利用
+    try {
+      const termsJson = await readPublicFile(
+        `docs/${langId}/termDefinitions.json`
+      );
+      return JSON.parse(termsJson) as TermDefinition[];
+    } catch (e) {
+      // not found?
+      console.warn(`failed to read docs/${langId}/termDefinitions.json:`, e);
+    }
+    const terms: TermDefinition[] = [];
+    const langEntry = await getPagesListForLang(langId);
+    const headingRegex = /^#+(.*)$/m;
+    const codeBlockRegex = /^(`{3,})(.*)\n([\s\S]*?)\n^\1/gm;
+    for (const page of langEntry.pages) {
+      const sections = await getMarkdownSections(langId, page.slug);
+      for (const section of sections) {
+        if (section.term && section.term.length >= 1) {
+          terms.push({
+            term: section.term,
+            page: page.slug,
+            id: section.id,
+            title: section.title,
+            rawContentWithoutCode: section.rawContent
+              .replace(codeBlockRegex, "")
+              .replace(headingRegex, ""),
+          });
+        }
+      }
+    }
+    return terms;
+  }
+}

app/markdown/markdown.tsx

@@ -2,13 +2,12 @@ import Markdown, { Components } from "react-markdown";
 import remarkGfm from "remark-gfm";
 import removeComments from "remark-remove-comments";
 import remarkCjkFriendly from "remark-cjk-friendly";
-import {
-  MultiHighlightTag,
-  remarkMultiHighlight,
-} from "./multiHighlight";
+import { MultiHighlightTag, remarkMultiHighlight } from "./multiHighlight";
 import { Heading } from "./heading";
 import { AutoCodeBlock } from "./codeBlock";
 import { ReplacedRange } from "@/lib/docs";
+import remarkTerm from "./remarkTerm";
+import Term from "./term";
 
 export function StyledMarkdown(props: {
   content: string;
@@ -21,6 +20,7 @@ export function StyledMarkdown(props: {
         removeComments,
         remarkCjkFriendly,
         [remarkMultiHighlight, props.replacedRange],
+        remarkTerm,
       ]}
       components={components}
     >
@@ -58,4 +58,5 @@ const components: Components = {
   pre: ({ node, ...props }) => props.children,
   code: AutoCodeBlock,
   ins: MultiHighlightTag,
+  q: Term,
 };

app/markdown/remarkTerm.ts

@@ -0,0 +1,94 @@
+import type { Plugin } from "unified";
+import type { Nodes, PhrasingContent, Root, RootContent } from "mdast";
+import { phrasing } from "mdast-util-phrasing";
+
+/**
+ * `[[用語]]`を`<Term>用語</Term>`に変換するプラグイン。
+ * 
+ * https://github.com/ut-code/utcode-learn/blob/main/src/remark/remark-term.ts からコピペ
+ * Copyright (c) 2023 ut.code();
+ *
+ * @example
+ * // returns "<Term>**HTML**</Term>と<Term>CSS</Term>、そして<Term>JavaScript</Term>です。"
+ * String(
+ *   await remark()
+ *     .use(remarkMdx)
+ *     .use(remarkTerm)
+ *     .process("[[**HTML**]]と[[CSS]]、そして[[JavaScript]]です。"),
+ * );
+ */
+const remarkTerm: Plugin<[], Root> = () => (tree) => transform(tree);
+
+export default remarkTerm;
+
+function isParent(node: Nodes) {
+  return "children" in node;
+}
+
+function transform(node: Nodes) {
+  if (!isParent(node)) return;
+
+  for (const child of node.children) {
+    transform(child);
+  }
+
+  node.children = wrapDelimitedPhrasingContentsAsTerm(
+    node.children.flatMap((child) => isolateTermDelimiters(child))
+  );
+}
+
+function isolateTermDelimiters(node: RootContent): RootContent[] {
+  if (node.type !== "text") return [node];
+
+  return node.value
+    .split(/(\[\[|\]\])/)
+    .filter((segment) => segment !== "")
+    .map((segment) => ({
+      type: "text",
+      value: segment,
+    }));
+}
+
+function wrapDelimitedPhrasingContentsAsTerm(
+  children: RootContent[]
+): RootContent[] {
+  const result: RootContent[] = [];
+  const buffer: PhrasingContent[] = [];
+
+  for (const child of children) {
+    if (buffer.length === 0) {
+      if (child.type === "text" && child.value === "[[") {
+        buffer.push(child);
+        continue;
+      }
+      result.push(child);
+      continue;
+    }
+
+    if (child.type === "text" && child.value === "]]") {
+      // 修正ポイント：MDXノードの代わりに、hNameを持った汎用ノードを作成
+      result.push({
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        type: "term" as any,
+        data: {
+          hName: "q",
+        },
+        children: buffer.slice(1),
+      });
+      buffer.length = 0;
+      continue;
+    }
+
+    if (phrasing(child)) {
+      buffer.push(child);
+      continue;
+    }
+
+    result.push(...buffer, child);
+    buffer.length = 0;
+  }
+
+  result.push(...buffer);
+
+  return result;
+}