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 - это творческая возможность быстро придумывать новый контент и, если вам нужно больше интерактива на странице, вы можете легко интегрировать ваши компоненты 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++}>
      Увеличить {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: Заголовок компонента Hello World
tags:
  - super
  - exiting
  - docs
---
import { Tags } from "../../../components/tags/tags";
 
Это простой компонент Hello World.
 
<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>
  );
});

Участники

Спасибо всем участникам, которые помогли сделать эту документацию лучше!