MDX

使用 .mdx 檔案（Markdown JSX）是另一種撰寫內容的方式。這些檔案以 Markdown 撰寫，但會被編譯成 Qwik 組件。除了 Markdown 語法之外，.mdx 檔案還可以參考其他組件。

假設您的路由設定如下

src/
└── routes/
    └── some/
        └── path/
            └── index.mdx    # https://example.com/some/path

src/routes/some/path/index.mdx

---
title: Hello World Title
---
 
This is a simple hello world component.

上述組件將會在 https://example.com/some/path 進行渲染。

導入其他組件。

MDX 為您提供了一個絕佳機會，讓您能夠快速（「Qwikly」🙂）創建新內容。如果您需要在頁面上添加更多互動性，您可以輕鬆整合您的 Qwik 元件，如下所示：

src/
├── components/
|   └── counter
│       └──  counter.tsx
└── routes/
    └── some/
        └── path/
            └── index.mdx    # https://example.com/some/path

src/routes/some/path/index.mdx

---
title: Hello World Title
---
import { Counter } from "../../../components/counter/counter";
 
This is a simple hello world component.
 
<Counter />

src/components/counter/counter.tsx

import { component$, useSignal } from '@builder.io/qwik';
 
export const Counter = component$(() => {
  const count = useSignal(0);
 
  return (
    <button class="counter" type="button" onClick$={() => count.value++}>
      Increment {count.value}
    </button>
  );
});

注意：Qwik City 與許多現有元框架的主要區別在於基於目錄的路由。每個路由都必須定義為 a-directory/index.(tsx,ts,js,jsx,md,mdx)。

在其他元框架中，您習慣於使用 about.mdx 來呈現路由 http://example.com/about。然而，這在 Qwik City 中是行不通的。您必須將檔案重新命名為 about/index.mdx，Qwik City 才能知道要呈現它。

停用預設包含的 MDX 外掛。

Qwik City 預設包含 3 個外掛。

remarkGfm：GFM 支援（自動連結字面值、註腳、刪除線、表格、任務清單）。
rehypeSyntaxHighlight：使用 Prism 進行輕量級、穩健、優雅的虛擬語法高亮顯示。
rehypeAutolinkHeadings：在 HTML 中新增標題連結的外掛。

這些外掛可以透過以下方式個別停用：

vite.config.js

import { defineConfig } from 'vite';
import { qwikCity } from '@builder.io/qwik-city/vite';
// See below
import rehypeAutolinkHeadings from 'rehype-autolink-headings';
export default defineConfig(() => {
  return {
    plugins: [
      qwikCity({
        mdxPlugins: {
          remarkGfm: false,
          rehypeSyntaxHighlight: false,
          rehypeAutolinkHeadings: false,
        },
        mdx: {
          rehypePlugins: [
            // Plugins can now be added manually to use a different configuration
            [rehypeAutolinkHeadings, { behavior: 'wrap' }],
          ],
        },
      }),
      /* the rest of the configuration */
    ],
  };
});

開放圖譜屬性

您可以使用 og 或 opengraph 屬性來定義開放圖譜協定中繼資料。

title: My Title
description: My Description
og:
  - title: My Custom Title
    description: true
  - image: https://example.com/rock.jpg
    image:alt: A shiny red apple with a bite taken out
  - image: https://example.com/rock2.jpg

將 og:title 或 og:description 設定為 true 將會檢查並使用外部的 title 和 description 屬性。因此，您可以避免重複撰寫相同的標題和描述。

以上範例將會產生以下 HTML 程式碼。

<title>My Title</title>
<meta name="description" content="My Description" />
 
<meta property="og:title" content="My Custom Title" />
<meta property="og:description" content="My Description" />
 
<meta property="og:image" content="https://example.com/rock.jpg" />
<meta property="og:image:alt" content="A shiny red apple with a bite taken out" />
 
<meta property="og:image" content="https://example.com/rock2.jpg" />

讀取 Frontmatter 資料

可以使用 useDocumentHead() 鉤子來存取 Frontmatter 鍵值。

src/routes/some/path/index.mdx

---
title: Hello World Title
tags:
  - super
  - exiting
  - docs
---
import { Tags } from "../../../components/tags/tags";
 
This is a simple hello world component.
 
<Tags />

src/components/tags/tags.tsx

import { component$ } from '@builder.io/qwik';
import { useDocumentHead } from '@builder.io/qwik-city';
 
export const Tags = component$(() => {
  const { frontmatter } = useDocumentHead();
  
  if (frontmatter.tags.length === 0) {
    return null;
  }
  
  return (
    <ul>
      {frontmatter.tags.map((tag: string) => (
        <li key={`tag-${tag}`}>{tag}</li>
      ))}
    </ul>
  );
});

貢獻者

感謝所有幫助改進此文件的貢獻者！