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: 你好，世界
---

这是一个简单的你好世界组件。

上述组件将在 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: 你好，世界
---
import { Counter } from "../../../components/counter/counter";

这是一个简单的你好世界组件。

<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++}>
      增加 {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';
// 请参阅下面
import rehypeAutolinkHeadings from 'rehype-autolink-headings';
export default defineConfig(() => {
  return {
    plugins: [
      qwikCity({
        mdxPlugins: {
          remarkGfm: false,
          rehypeSyntaxHighlight: false,
          rehypeAutolinkHeadings: false,
        },
        mdx: {
          rehypePlugins: [
            // 现在可以手动添加插件以使用不同的配置
            [rehypeAutolinkHeadings, { behavior: 'wrap' }],
          ],
        },
      }),
      /* 其余的配置 */
    ],
  };
});

Open Graph 属性

你可以使用 og 或 opengraph 属性来定义 Open Graph 协议的元数据。

title: 我的标题
description: 我的描述
og:
  - title: 我的自定义标题
    description: true
  - image: https://example.com/rock.jpg
    image:alt: 一个闪亮的红苹果被咬了一口
  - image: https://example.com/rock2.jpg

将 og:title 或 og:description 设置为 true 将检查并使用外部的 title 和 description 属性。因此，你可以避免重复编写相同的标题和描述。

上述示例将生成以下 HTML 代码。

<title>我的标题</title>
<meta name="description" content="我的描述" />
 
<meta property="og:title" content="我的自定义标题" />
<meta property="og:description" content="我的描述" />
 
<meta property="og:image" content="https://example.com/rock.jpg" />
<meta property="og:image:alt" content="一个闪亮的红苹果被咬了一口" />
 
<meta property="og:image" content="https://example.com/rock2.jpg" />

读取前置数据

可以通过利用 useDocumentHead() 钩子来访问前置数据的键。

src/routes/some/path/index.mdx

---
title: 你好，世界
tags:
  - 超级
  - 令人兴奋
  - 文档
---
import { Tags } from "../../../components/tags/tags";

这是一个简单的你好世界组件。

<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>
  );
});

Contributors

Thanks to all the contributors who have helped make this documentation better!