代码片段 — Jamdesk Documentation

代码片段是存放在 /snippets 目录中的可复用内容块。将其导入任意 MDX 页面即可避免重复内容。

创建代码片段

在文档根目录下创建 /snippets 目录:

my-docs/
├── docs.json
├── introduction.mdx
└── snippets/
    ├── prerequisites.mdx
    ├── installation.mdx
    └── support-cta.mdx

像编写普通 MDX 文件一样编写代码片段内容,但不需要 frontmatter:

snippets/prerequisites.mdx

Before you begin, make sure you have:

- Node.js 20 or higher
- A GitHub account
- A text editor (VS Code recommended)

使用代码片段

在页面中导入并使用代码片段:

getting-started.mdx

---
title: Getting Started
---

## Prerequisites

import Prerequisites from '/snippets/prerequisites.mdx';

<Prerequisites />

## Installation

Continue with your page content...

代码片段组件

代码片段可以包含 Jamdesk 组件:

snippets/support-cta.mdx

<Columns cols={2}>
  <Card title="Documentation" icon="book" href="/docs">

    Browse our guides

</Card>
  <Card title="Contact Support" icon="headset" href="/support">

    Get help from our team

</Card>
</Columns>

在任意页面中使用:

import SupportCTA from '/snippets/support-cta.mdx';

## Need Help?

<SupportCTA />

交互式代码片段

对于需要 React Hooks(useState、useEffect 等)的代码片段,使用带有 'use client' 指令的 .tsx 文件:

snippets/counter.tsx

'use client';

import { useState } from 'react';

export function Counter() {
  const [count, setCount] = useState(0);
  return (
    <button onClick={() => setCount(c => c + 1)}>
      Count: {count}
    </button>
  );
}

在 MDX 中导入:

import { Counter } from '/snippets/counter';

<Counter />

任何使用 React Hooks 的组件都必须包含 'use client' 指令。缺少该指令会导致 "useState is not defined" 错误。

参数化代码片段

通过传递 props 使代码片段动态化:

snippets/api-key-warning.mdx

export const ApiKeyWarning = ({ service }) => (
  <Warning>

    Never commit your {service} API key to version control. Use environment variables instead.

</Warning>
);

带 props 使用:

import { ApiKeyWarning } from '/snippets/api-key-warning.mdx';

<ApiKeyWarning service="Stripe" />

组织代码片段

在较大的项目中,可将代码片段按子目录组织:

snippets/
├── components/
│   ├── cta-cards.mdx
│   └── feature-table.mdx
├── warnings/
│   ├── api-key.mdx
│   └── deprecation.mdx
└── shared/
    ├── prerequisites.mdx
    └── support-links.mdx

使用完整路径导入:

import CtaCards from '/snippets/components/cta-cards.mdx';
import ApiKeyWarning from '/snippets/warnings/api-key.mdx';

常见使用场景

使用场景	示例
前置条件	系统要求、账户设置
安装步骤	跨平台的 CLI 安装命令
API 认证	在多个端点中重复的认证设置
支持 CTA	故障排除页面末尾的联系链接
弃用通知	过时功能的警告
代码示例	可复用的代码模式

代码片段与内联组件

特性	代码片段	内联组件
可跨页面复用	是	否(仅限页面内)
可使用 React Hooks	是(需 `'use client'`)	否
可导入外部包	是(`.tsx` 文件)	否
语法	import 语句	MDX 中的 `export const`

对于出现在多个页面中的内容,使用代码片段。对于单个页面中的一次性展示组件,使用内联组件。

接下来做什么？

自定义 React 组件

在 MDX 中定义内联组件

MDX 基础

学习 MDX 基础知识