My logo
Published on

v1 的特性

Overview

一篇关于v1.0 特性的文章:

Theme colors

您可以通过更改顺风配置文件中的主要属性来轻松修改主题颜色:

tailwind.config.js
theme: {
    colors: {
      primary: colors.teal,
      gray: colors.neutral,
      ...
    }
  ...
}

主要颜色属性应被分配一个对象，该对象的键为50、100、200... 900，对应的值为颜色代码。

Tailwind包括一些非常优秀的默认颜色调色板，可用于为自己的网站设置主题。查看 customizing colors documentation page 自定义颜色文档页面以获取完整的选项范围。

Xdm MDX compiler

MDX mdx-bundler（用于 JSX 的 Markdown）允许你在 Markdown 文档中直接编写 JSX。当使用 mdx-bundler 和 xdm 这样的工具时，你可以在 MDX 文件中无缝导入和使用 React 组件。这种集成使得在构建过程中可以嵌入并编译 JavaScript 代码。

以下是如何在 MDX 文件中导入和使用 React 组件的示例：

import PageTitle from "./PageTitle.js";
<PageTitle> Using JSX components in MDX </PageTitle>;

Using JSX components in MDX

默认配置会相对于 components 目录解析所有组件。

Table of contents component

受 Docusaurus 和 Gatsby's gatsby-remark-table-of-contents 启发， 包含文档所有顶级标题的 toc 变量会被传递到 MDX 文件，并可以进行相应的样式处理。 为了简化目录（TOC）的生成，可以使用现有的 TOCInline 组件。

例如，本帖子的目录是通过以下代码生成的：

<TOCInline toc={props.toc} exclude="Overview" toHeading={2} />

你可以通过配置 fromHeading 和 toHeading 属性来自定义显示的标题， 或通过向 exclude 属性传递一个字符串或字符串数组来排除特定的标题。默认情况下， 所有深度为 3 或更小的标题都会缩进。可以通过更改 indentDepth 属性来配置这一点。asDisclosure 属性可以用于在一个可扩展的披露元素中呈现目录 (TOC)。

以下是在披露元素中呈现的完整目录 (TOC)：

<TOCInline toc={props.toc} asDisclosure />
Table of Contents

Layouts

你可以通过配置 frontmatter 字段将 MDX 博客内容映射到布局组件。例如，这篇文章是用 PostSimple 布局编写的！

Adding new templates

布局模板存储在 ./layouts 文件夹中。你可以将你想要映射到 markdown 内容的 React 组件添加到这个文件夹中。组件文件名必须与 markdown frontmatter 布局字段中指定的名称匹配。

唯一必需的字段是 children，它包含渲染的 MDX 内容，不过你可能还需要传入 frontMatter 内容并在模板中渲染它。

以下是一个可以进一步自定义的示例布局：

export default function ExampleLayout({ frontMatter, children }) {
  const { date, title } = frontMatter;

  return (
    <SectionContainer>
      <div>{date}</div>
      <h1>{title}</h1>
      <div>{children}</div>
    </SectionContainer>
  );
}

Configuring a blog post frontmatter

你可以使用 layout frontmatter 字段来指定要将 markdown 文章映射到的模板。以下是这篇文章的 frontmatter 示例：

---
title: 'New features in v1'
date: '2021-05-26   '
tags: ['remix-run', 'tailwind', 'guide']
draft: false
summary: 'Introducing the new layout features - you can map mdx blog content to layout components by configuring the frontmatter field'
layout: PostSimpleLayout
---

你可以通过修改 DEFAULT_LAYOUT 变量在相应的页面部分配置默认布局。博客文章页面的 DEFAULT_LAYOUT 设置为 PostSimpleLayout。

Extend

layout 映射到 wrapper，它包裹整个 MDX 内容。

在 MDXComponents.tsx 文件中，我确实有一个相当笨拙的 switch 语句，所以每次添加新的布局模板时，都必须将其添加到该 switch 语句中。

以下是一个示例说明如何在 MDXComponents.tsx 中管理布局模板：

switch (layout) {
  case "PostSimpleLayout":
    return <PostSimpleLayout children={children} {...rest} />;
  case "AuthorLayout":
    return <AuthorLayout children={children} {...rest} />;
  case "ExampleLayout":
    return <ExampleLayout children={children} {...rest} />;
}

动态引入模块在 Remix 中确实有点棘手，特别是在服务器端渲染的环境中。虽然使用 switch 语句是一个解决方案，但它可能不太优雅。以下是一个改进的方法，使用一个对象来映射布局模板，并在 LayoutWrapper 中选择适当的模板：

const Layout = (await import(`~/app/layouts/${layout}`)) as any;
return <Layout {...rest} />;

可以使用 MDXLayoutRenderer 组件来接收一个布局名称并映射到所需的布局。你需要从布局文件夹中传递布局名称（必须完全匹配）。

export const MDXLayoutRenderer = ({ layout, mdxSource, ...rest }) => {
  const MDXLayout = useMemo(() => getMDXComponent(mdxSource), [mdxSource]);

  return <MDXLayout layout={layout} components={MDXComponents} {...rest} />;
};

Copy button for code blocks

你可以自定义代码块的行为，包括在代码块上方添加 GitHub 风格的复制按钮。要实现这一点，你需要修改 ./components/Pre.js 文件，因为这个组件会传递给 MDXComponents 并修改所有 <pre> 块。

Line highlighting and line numbers

使用 rehype-prism-plus plugin 插件，现在可以支持代码块的行高亮和行号功能。以下是如何使用这个插件以及如何在 MDX

文件中使用 JavaScript 代码块的示例：

```js:showLineNumbers {1, 3-4}
var num1, num2, sum
num1 = prompt('Enter first number')
num2 = prompt('Enter second number')
sum = parseInt(num1) + parseInt(num2) // "+" means "add"
alert('Sum = ' + sum) // "+" means combine into a string
```

将显示为:

showLineNumbers
var num1, num2, sum;
num1 = prompt("Enter first number");
num2 = prompt("Enter second number");
sum = parseInt(num1) + parseInt(num2); // "+" means "add"
alert("Sum = " + sum); // "+" means combine into a string

要修改样式，请更改 prism.css 文件中的以下类选择器：

.code-highlight {
  @apply float-left min-w-full;
}

.code-line {
  @apply -mx-4 block border-l-4 border-opacity-0 pl-4 pr-4;
}

.code-line.inserted {
  @apply bg-green-500 bg-opacity-20;
}

.code-line.deleted {
  @apply bg-red-500 bg-opacity-20;
}

.highlight-line {
  @apply -mx-4 border-l-4 border-primary-500 bg-gray-700 bg-opacity-50;
}

.line-number::before {
  @apply -ml-2 mr-4 inline-block w-4 text-right text-gray-400;
  content: attr(line);
}

参考书目和引文

rehype-citation 插件已添加到 xdm 处理管道中。这使您可以轻松格式化引文并从现有的 bibtex 或 CSL-json 文件插入参考书目。

例如，以下 Markdown 代码示例:

Standard citation [@Nash1950]
In-text citations e.g. @Nash1951
Multiple citations [see @Nash1950; @Nash1951, page 50]

**References:**

[^ref]

被渲染为以下内容：

标准引文 (Nash, 1950)

文本引用 e.g. Nash (1951)

多次引用 (see Nash, 1950, 1951, p. 50)

References:

[^ref]

参考书目将插入到文档末尾，但可以通过在预期位置指定 [^Ref] 标签来覆盖。该插件使用 APA 引文格式，但还支持以下 CSL：“apa”、“vancouver”、“harvard1”、“chicago”、“mla”或用户指定的 CSL 文件的路径。

See rehype-citation readme 有关配置选项的更多信息。