Code Block File Name Transformerを追加し、Astroの使用例をドキュメントに追加

Author: dc7290

docs/.vitepress/config.mts

@@ -38,6 +38,10 @@ export default defineConfig({
 								text: "Syntax Highlighting by Shiki",
 								link: "/features/transformer/syntax-highlighting-by-shiki",
 							},
+							{
+								text: "Code Block File Name",
+								link: "/features/transformer/code-block-file-name",
+							},
 							{
 								text: "Attributes",
 								link: "/features/transformer/attributes",
@@ -61,6 +65,7 @@ export default defineConfig({
 				items: [
 					{ text: "Responsive Image", link: "/examples/responsive-image" },
 					{ text: "Lazy Loading", link: "/examples/lazy-loading" },
+					{ text: "Astro", link: "/examples/astro" },
 				],
 			},
 		],

docs/examples/astro.md

@@ -0,0 +1,55 @@
+# Astro Example
+
+`microcms-rich-editor-handler`をAstroで使用する例です。
+フロントマッターでMicroCMSから取得したリッチエディタのHTMLコンテンツを処理し、目次を生成して表示します。
+
+```astro {25-33}
+---
+import type { MicroCMSListContent } from "microcms-js-sdk";
+import { createClient } from "microcms-js-sdk";
+import {
+ microCMSRichEditorHandler,
+ responsiveImageTransformer,
+ tocExtractor,
+} from "microcms-rich-editor-handler";
+
+const client = createClient({
+ serviceDomain: import.meta.env.MICROCMS_SERVICE_DOMAIN,
+ apiKey: import.meta.env.MICROCMS_API_KEY,
+});
+
+export type Blog = {
+ title: string;
+ content: string;
+} & MicroCMSListContent;
+
+const blogContent = await client.getListDetail<Blog>({
+ endpoint: "blogs",
+ contentId: "id001",
+});
+
+const {
+ html,
+ data: { toc },
+} = await microCMSRichEditorHandler(blogContent.content, {
+ transformers: [responsiveImageTransformer()],
+ extractors: {
+  toc: [tocExtractor(), { phase: "before" }],
+ },
+});
+
+blogContent.content = html;
+---
+
+<main>
+  <nav>
+    {toc.map((item) => (
+      <a href={`#${item.id}`}>{item.text}</a>
+    ))}
+  </nav>
+  <section>
+    <h1>{blogContent.title}</h1>
+    <div set:html={blogContent.content}></div>
+  </section>
+</main>
+```

docs/features/handler.md

@@ -39,57 +39,24 @@ export const microCMSRichEditorHandler = async <T extends DefaultGenerics>(
 
 extractorsに指定したキーに対応するするようにdataの型を決定するために少し複雑になっていますが、基本的には以下のように使います。
 
-例）Astroでの使用例
-
-```astro {25-33}
----
-import type { MicroCMSListContent } from "microcms-js-sdk";
-import { createClient } from "microcms-js-sdk";
+```js
 import {
  microCMSRichEditorHandler,
  responsiveImageTransformer,
- tocExtractor,
-} from "microcms-rich-editor-handler";
-
-const client = createClient({
- serviceDomain: import.meta.env.MICROCMS_SERVICE_DOMAIN,
- apiKey: import.meta.env.MICROCMS_API_KEY,
-});
-
-export type Blog = {
- title: string;
- content: string;
-} & MicroCMSListContent;
-
-const blogContent = await client.getListDetail<Blog>({
- endpoint: "blogs",
- contentId: "id001",
-});
-
-const {
- html,
- data: { toc },
-} = await microCMSRichEditorHandler(blogContent.content, {
- transformers: [responsiveImageTransformer()],
- extractors: {
-  toc: [tocExtractor(), { phase: "before" }],
- },
-});
-
-blogContent.content = html;
----
-
-<main>
-  <nav>
-    {toc.map((item) => (
-      <a href={`#${item.id}`}>{item.text}</a>
-    ))}
-  </nav>
-  <section>
-    <h1>{blogContent.title}</h1>
-    <div set:html={blogContent.content}></div>
-  </section>
-</main>
+ tocExtractor
+} from 'microcms-rich-editor-handler';
+
+const main = async () => {
+ const { html, data } = await microCMSRichEditorHandler(
+  dataFromMicroCMS, // MicroCMSから取得したデータのリッチエディタのHTML文字列
+  {
+   transformers: [responsiveImageTransformer()],
+   extractors: {
+    toc: [tocExtractor(), { phase: "before" }],
+   },
+  },
+ );
+};
 ```
 
 ## Parameters

docs/features/transformer/code-block-file-name.md

@@ -0,0 +1,58 @@
+# Code Block File Name Transformer
+
+`Code Block File Name` は、コードブロックのファイル名を表示するためのTransformerです。
+microCMSではコードブロックにファイル名を指定することができ、そのファイル名を表示するために使用します。
+
+## Type Definition
+
+```ts
+import type { Transformer } from "./types";
+
+type Options = {
+ /**
+  * ファイル名を表示する要素のタグ名
+  * デフォルトは span
+  */
+ tagName?: string | undefined
+ /**
+  * ファイル名を表示する要素に追加する属性
+  */
+ attributes?: Record<string, string> | undefined;
+};
+
+/**
+ * コードブロックのファイル名を表示する
+ */
+const codeBlockFileNameTransformer: (options?: Options | undefined) => Transformer
+```
+
+## Usage
+
+```ts
+import { microCMSRichEditorHandler, codeBlockFileNameTransformer } from "microcms-rich-editor-handler";
+
+const html = `
+  <div data-filename="index.js">
+    <pre><code>console.log("Hello, World!")</code></pre>
+  </div>
+`;
+
+const main = async () => {
+  const { html: transformedHtml } = await microCMSRichEditorHandler({
+    transformers: [codeBlockFileNameTransformer()],
+  });
+
+  console.log(transformedHtml);
+};
+
+main();
+```
+
+Output:
+
+```html
+<div data-filename="index.js">
+  <span>index.js</span>
+  <pre><code>console.log("Hello, World!")</code></pre>
+</div>
+```