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 */
    ],
  };
});

Open Graph 属性

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

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" />

读取前置数据

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

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

贡献者

感谢所有帮助改进此文档的贡献者！