1
import { defineConfig } from 'astro/config';
2
import mdx from '@astrojs/mdx';
3
import vue from '@astrojs/vue';
4

5
export default defineConfig({
6
  integrations: [
7
    mdx({
8
      // MDX 配置选项
9
      shikiConfig: {
10
        theme: 'github-dark',
11
      },
12
    }),
13
    vue(), // 支持在 MDX 中使用 Vue 组件
14
  ],
15
  markdown: {
16
    // 支持 GFM（GitHub Flavored Markdown）
17
    gfm: true,
18
    // 智能标点
19
    smartypants: true,
20
  },
21
});

1
import { defineCollection, z } from 'astro:content';
2
import { docsSchema } from '@astrojs/starlight/schema';
3

4
// 定义 MDX 集合
5
const mdxCollection = defineCollection({
6
  type: 'content',
7
  schema: ({ image }) => z.object({
8
    title: z.string(),
9
    description: z.string(),
10
    publishDate: z.date(),
11
    updatedDate: z.date().optional(),
12
    author: z.string(),
13
    tags: z.array(z.string()),
14
    // 支持图片
15
    coverImage: image().optional(),
16
    // 自定义元数据
17
    difficulty: z.enum(['beginner', 'intermediate', 'advanced']).optional(),
18
    interactive: z.boolean().default(false),
19
  }),
20
});
21

22
export const collections = {
23
  'mdx-content': mdxCollection,
24
};

1
---
2
import Counter from '../../components/vue/Counter.vue';
3
import DataVisualizer from '../../components/vue/DataVisualizer.vue';
4
import QuizComponent from '../../components/vue/Quiz.vue';
5

6
title: 'MDX 中的 Vue 交互组件演示'
7
description: '学习如何在 MDX 中集成 Vue 交互式组件'
8
publishDate: '2023-10-15'
9
tags: ['mdx', 'vue', 'interactive']
10
interactive: true
11
---
12

13
# Vue + MDX 交互式文档
14

15
## 1. 基础计数器组件
16

17
下面是一个 Vue 计数器组件，完全在 MDX 中工作：
18

19
<Counter
20
  initialValue={10}
21
  step={2}
22
  client:load
23
/>
24

25
**代码说明：**
26
- `client:load` 属性确保组件在页面加载时激活
27
- 可以传递 props 给 Vue 组件
28
- 组件完全交互式，状态在客户端维护
29

30
## 2. 数据可视化组件
31

32
<DataVisualizer
33
  data={[
34
    { month: 'Jan', value: 4000 },
35
    { month: 'Feb', value: 3000 },
36
    { month: 'Mar', value: 5000 },
37
    { month: 'Apr', value: 8000 },
38
  ]}
39
  type="bar"
40
  client:visible
41
/>
42

43
## 3. 交互式测验组件
44

45
<QuizComponent
46
  questions={[
47
    {
48
      question: '什么是 MDX？',
49
      options: [
50
        '一种新的编程语言',
51
        'Markdown 和 JSX 的结合',
52
        '一个 CSS 框架',
53
        '一个数据库'
54
      ],
55
      correctAnswer: 1
56
    }
57
  ]}
58
  client:idle
59
/>

1
<template>
2
  <div class="mdx-counter" :class="{ interactive: isInteractive }">
3
    <div class="counter-display">
4
      <h3>{{ title }}</h3>
5
      <div class="count">{{ count }}</div>
6
    </div>
7

8
    <div class="controls">
9
      <button @click="decrement" :disabled="count <= min">
10
        −
11
      </button>
12
      <button @click="reset">
13
        重置
14
      </button>
15
      <button @click="increment" :disabled="count >= max">
16
        +
17
      </button>
18
    </div>
19

20
    <div v-if="showStats" class="stats">
21
      <p>历史最高: {{ maxCount }}</p>
22
      <p>点击次数: {{ clickCount }}</p>
23
    </div>
24
  </div>
25
</template>
26

27
<script setup>
28
import { ref, computed, onMounted } from 'vue';
29

30
const props = defineProps({
31
  initialValue: {
32
    type: Number,
33
    default: 0
34
  },
35
  min: {
36
    type: Number,
37
    default: -Infinity
38
  },
39
  max: {
40
    type: Number,
41
    default: Infinity
42
  },
43
  title: {
44
    type: String,
45
    default: '计数器'
46
  },
47
  showStats: {
48
    type: Boolean,
49
    default: true
50
  },
51
  step: {
52
    type: Number,
53
    default: 1
54
  }
55
});
56

57
// 响应式状态
58
const count = ref(props.initialValue);
59
const maxCount = ref(props.initialValue);
60
const clickCount = ref(0);
61
const isInteractive = ref(true);
62

63
// 计算属性
64
const countStyle = computed(() => ({
65
  color: count.value > 0 ? 'green' : count.value < 0 ? 'red' : 'gray',
66
  fontSize: `${Math.min(2, 1 + Math.abs(count.value) * 0.1)}rem`
67
}));
68

69
// 方法
70
const increment = () => {
71
  if (count.value < props.max) {
72
    count.value += props.step;
73
    updateStats();
74
  }
75
};
76

77
const decrement = () => {
78
  if (count.value > props.min) {
79
    count.value -= props.step;
80
    updateStats();
81
  }
82
};
83

84
const reset = () => {
85
  count.value = props.initialValue;
86
  clickCount.value += 1;
87
};
88

89
const updateStats = () => {
90
  clickCount.value += 1;
91
  if (count.value > maxCount.value) {
92
    maxCount.value = count.value;
93
  }
94
};
95

96
// 生命周期
97
onMounted(() => {
98
  console.log('MDX Counter mounted in Astro');
99
});
100

101
// 暴露方法供父组件调用
102
defineExpose({
103
  increment,
104
  decrement,
105
  reset,
106
  getCount: () => count.value
107
});
108
</script>
109

110
<style scoped>
111
.mdx-counter {
112
  border: 2px solid #e5e7eb;
113
  border-radius: 12px;
114
  padding: 1.5rem;
115
  margin: 2rem 0;
116
  background: linear-gradient(135deg, #f9fafb 0%, #f3f4f6 100%);
117
  transition: all 0.3s ease;
118
}
119

120
.mdx-counter.interactive:hover {
121
  border-color: #3b82f6;
122
  box-shadow: 0 10px 25px -5px rgba(59, 130, 246, 0.1);
123
}
124

125
.counter-display {
126
  text-align: center;
127
  margin-bottom: 1.5rem;
128
}
129

130
.counter-display h3 {
131
  margin: 0 0 0.5rem 0;
132
  color: #374151;
133
  font-size: 1.25rem;
134
}
135

136
.count {
137
  font-size: 3rem;
138
  font-weight: bold;
139
  transition: all 0.3s ease;
140
}
141

142
.controls {
143
  display: flex;
144
  gap: 1rem;
145
  justify-content: center;
146
  margin-bottom: 1.5rem;
147
}
148

149
.controls button {
150
  padding: 0.5rem 1rem;
151
  border: none;
152
  border-radius: 6px;
153
  background: #3b82f6;
154
  color: white;
155
  font-size: 1rem;
156
  cursor: pointer;
157
  transition: all 0.2s ease;
158
}
159

160
.controls button:hover:not(:disabled) {
161
  background: #2563eb;
162
  transform: translateY(-2px);
163
}
164

165
.controls button:disabled {
166
  background: #9ca3af;
167
  cursor: not-allowed;
168
}
169

170
.stats {
171
  border-top: 1px solid #e5e7eb;
172
  padding-top: 1rem;
173
  font-size: 0.875rem;
174
  color: #6b7280;
175
}
176
</style>

1
---
2
import LineChart from '../../components/vue/charts/LineChart.vue';
3
import BarChart from '../../components/vue/charts/BarChart.vue';
4
import PieChart from '../../components/vue/charts/PieChart.vue';
5
import DataControls from '../../components/vue/DataControls.vue';
6
import CodeEditor from '../../components/vue/CodeEditor.vue';
7

8
title: '数据可视化教程'
9
description: '交互式学习数据可视化'
10
publishDate: '2023-11-20'
11
tags: ['tutorial', 'data-viz', 'interactive']
12
difficulty: 'intermediate'
13
interactive: true
14
---
15

16
# 交互式数据可视化教程
17

18
## 介绍
19

20
本教程通过实际操作来学习数据可视化。你可以：
21

22
1. 📊 直接与图表交互
23
2. 🔧 修改数据和配置
24
3. 💾 查看实时代码变化
25

26
---
27

28
## 第一部分：基础图表
29

30
### 1. 折线图
31

32
<LineChart
33
  client:load
34
  id="line-chart-1"
35
  title="月度销售数据"
36
  :data="[
37
    { month: '1月', sales: 4000 },
38
    { month: '2月', sales: 3000 },
39
    { month: '3月', sales: 5000 },
40
    { month: '4月', sales: 8000 },
41
    { month: '5月', sales: 7000 },
42
    { month: '6月', sales: 9000 },
43
  ]"
44
  :config="{
45
    showGrid: true,
46
    animate: true,
47
    curve: 'smooth'
48
  }"
49
/>
50

51
**练习：** 尝试修改上方的数据，观察图表变化。
52

53
### 2. 柱状图
54

55
<BarChart
56
  client:visible
57
  id="bar-chart-1"
58
  title="产品类别销售"
59
  :data="[
60
    { category: '电子产品', sales: 12000 },
61
    { category: '服装', sales: 8500 },
62
    { category: '食品', sales: 9500 },
63
    { category: '书籍', sales: 4500 },
64
  ]"
65
  :colors="['#3b82f6', '#10b981', '#f59e0b', '#ef4444']"
66
/>
67

68
---
69

70
## 第二部分：动态数据控制
71

72
<DataControls
73
  client:load
74
  v-slot="{ data, updateData }"
75
>
76
  <div class="data-section">
77
    <h3>实时数据控制面板</h3>
78

79
    <div class="chart-container">
80
      <PieChart
81
        :data="data"
82
        title="动态饼图"
83
      />
84
    </div>
85

86
    <div class="controls">
87
      <p>当前数据点数量: {{ data.length }}</p>
88
      <button @click="updateData('add')">添加数据点</button>
89
      <button @click="updateData('remove')">移除数据点</button>
90
      <button @click="updateData('randomize')">随机化数据</button>
91
    </div>
92
  </div>
93
</DataControls>
94

95
---
96

97
## 第三部分：代码编辑器集成
98

99
### 实时代码演示
100

101
<CodeEditor
102
  client:idle
103
  language="javascript"
104
  :initial-code="`
105
// 数据可视化配置示例
106
const config = {
107
  type: 'line',
108
  data: {
109
    labels: ['Jan', 'Feb', 'Mar', 'Apr'],
110
    datasets: [{
111
      label: 'Sales',
112
      data: [65, 59, 80, 81],
113
      borderColor: 'rgb(75, 192, 192)',
114
      tension: 0.1
115
    }]
116
  },
117
  options: {
118
    responsive: true,
119
    plugins: {
120
      legend: {
121
        position: 'top',
122
      }
123
    }
124
  }
125
};
126

127
// 创建图表
128
const ctx = document.getElementById('myChart').getContext('2d');
129
const myChart = new Chart(ctx, config);
130
  `"
131
  :theme="'github-dark'"
132
  height="400px"
133
/>
134

135
**练习：** 修改上面的代码，然后点击"运行"查看结果。
136

137
---
138

139
## 总结
140

141
通过这个交互式教程，你学到了：
142

143
1. 如何在 MDX 中集成 Vue 图表组件
144
2. 如何创建动态交互的数据可视化
145
3. 如何让读者直接参与学习过程
146

147
<QuizComponent
148
  client:load
149
  :questions="[
150
    {
151
      question: '在 Astro MDX 中使用 Vue 组件需要什么配置？',
152
      options: [
153
        '什么都不需要，默认支持',
154
        '安装 @astrojs/vue 并添加到配置',
155
        '只能使用 React 组件',
156
        '需要特殊的构建配置'
157
      ],
158
      correctAnswer: 1,
159
      explanation: '需要在 astro.config.mjs 中添加 vue() 集成'
160
    }
161
  ]"
162
/>

1
import Alert from './Alert.astro';
2
import Card from './Card.astro';
3
import Tabs from './Tabs.astro';
4
import TabItem from './TabItem.astro';
5

6
// 自定义组件映射
7
export const components = {
8
  Alert,      // 将 Markdown 的 > 警告转换为 Alert 组件
9
  Card,       // 自定义卡片组件
10
  Tabs,       // 标签页组件
11
  TabItem,    // 标签页项
12
  // 覆盖默认的 HTML 元素
13
  h1: (props) => <h1 className="text-4xl font-bold" {...props} />,
14
  a: (props) => <a className="text-blue-600 hover:underline" {...props} />,
15
  // Vue 组件也可以映射
16
  VueCounter: () => import('../vue/Counter.vue').then(m => m.default),
17
};

1
---
2
import type { Props } from 'astro';
3
import TableOfContents from '../components/TableOfContents.astro';
4
import AuthorBio from '../components/AuthorBio.astro';
5
import ShareButtons from '../components/vue/ShareButtons.vue';
6
import ReadingProgress from '../components/vue/ReadingProgress.vue';
7
import MdxComponents from '../components/mdx/CustomComponents';
8

9
const { frontmatter, headings } = Astro.props;
10
---
11

12
<html lang="zh-CN">
13
<head>
14
  <title>{frontmatter.title}</title>
15
  <meta name="description" content={frontmatter.description} />
16
</head>
17
<body>
18
  <!-- 阅读进度条 -->
19
  <ReadingProgress client:load />
20

21
  <div class="mdx-container">
22
    <!-- 侧边栏目录 -->
23
    <aside class="sidebar">
24
      <TableOfContents headings={headings} />
25
    </aside>
26

27
    <!-- 主内容区域 -->
28
    <main class="content">
29
      <article>
30
        <header>
31
          <h1>{frontmatter.title}</h1>
32
          <div class="meta">
33
            <span>发布日期: {frontmatter.publishDate.toLocaleDateString()}</span>
34
            <span>作者: {frontmatter.author}</span>
35
          </div>
36
        </header>
37

38
        <!-- MDX 内容渲染 -->
39
        <div class="mdx-content">
40
          <slot />
41
        </div>
42

43
        <!-- 分享按钮 -->
44
        <ShareButtons
45
          client:load
46
          :title="frontmatter.title"
47
          :url={Astro.url}
48
        />
49

50
        <!-- 作者简介 -->
51
        <AuthorBio author={frontmatter.author} />
52
      </article>
53
    </main>
54
  </div>
55

56
  <style>
57
    .mdx-container {
58
      display: grid;
59
      grid-template-columns: 280px 1fr;
60
      gap: 3rem;
61
      max-width: 1200px;
62
      margin: 0 auto;
63
      padding: 2rem;
64
    }
65

66
    .mdx-content {
67
      line-height: 1.8;
68
    }
69

70
    .mdx-content :global(h2) {
71
      margin-top: 3rem;
72
      padding-bottom: 0.5rem;
73
      border-bottom: 2px solid #e5e7eb;
74
    }
75

76
    .mdx-content :global(pre) {
77
      border-radius: 8px;
78
      padding: 1rem;
79
      overflow-x: auto;
80
    }
81
  </style>
82
</body>
83
</html>

1
---
2
import { Suspense } from 'vue';
3

4
title: '动态组件加载演示'
5
description: '展示如何在 MDX 中懒加载大型组件'
6
---
7

8
# 动态组件加载
9

10
## 大型组件的懒加载
11

12
为了避免页面初始加载过重，我们可以动态导入大型组件：
13

14
```jsx
15
const HeavyComponent = React.lazy(() => import('../components/HeavyComponent'));

1
<template>
2
  <div v-if="hasError" class="error-boundary">
3
    <h3>组件加载失败</h3>
4
    <p>{{ errorMessage }}</p>
5
    <button @click="retry">重试</button>
6
  </div>
7
  <slot v-else />
8
</template>
9

10
<script setup>
11
import { ref, onErrorCaptured } from 'vue';
12

13
const hasError = ref(false);
14
const errorMessage = ref('');
15

16
onErrorCaptured((err) => {
17
  hasError.value = true;
18
  errorMessage.value = err.message;
19
  console.error('MDX 组件错误:', err);
20
  return false; // 阻止错误继续向上传播
21
});
22

23
const retry = () => {
24
  hasError.value = false;
25
  errorMessage.value = '';
26
};
27
</script>

1
---
2
import ApiPlayground from '../../components/vue/ApiPlayground.vue';
3
import ResponseVisualizer from '../../components/vue/ResponseVisualizer.vue';
4
import CodeSnippet from '../../components/CodeSnippet.astro';
5

6
title: 'API 文档 - 用户服务'
7
description: '交互式 API 文档，可直接测试端点'
8
tags: ['api', 'rest', 'interactive']
9
---
10

11
# 用户服务 API
12

13
## GET /api/users
14

15
获取用户列表。
16

17
### 请求示例
18

19
<CodeSnippet language="javascript">
20
// 获取用户列表
21
fetch('/api/users')
22
  .then(response => response.json())
23
  .then(data => console.log(data));
24
</CodeSnippet>
25

26
### 实时测试
27

28
<ApiPlayground
29
  client:load
30
  endpoint="/api/users"
31
  method="GET"
32
  :headers="{ 'Authorization': 'Bearer token' }"
33
/>
34

35
### 响应结构
36

37
<ResponseVisualizer
38
  client:visible
39
  :response="{
40
    success: true,
41
    data: [
42
      {
43
        id: 1,
44
        name: '张三',
45
        email: 'zhangsan@example.com',
46
        role: 'user'
47
      }
48
    ],
49
    pagination: {
50
      page: 1,
51
      limit: 20,
52
      total: 100
53
    }
54
  }"
55
/>

1
---
2
import DashboardDemo from '../../components/vue/DashboardDemo.vue';
3
import FeatureToggle from '../../components/vue/FeatureToggle.vue';
4
import DataExport from '../../components/vue/DataExport.vue';
5

6
title: '产品仪表板演示'
7
description: '交互式产品功能演示'
8
product: 'Analytics Pro'
9
version: '2.0'
10
---
11

12
# 数据分析仪表板 - 交互演示
13

14
## 实时仪表板
15

16
<DashboardDemo
17
  client:load
18
  :initialView="'overview'"
19
  :demoData="demoDataset"
20
  :features="{
21
    realtime: true,
22
    filters: true,
23
    export: true
24
  }"
25
/>
26

27
## 功能配置
28

29
### 1. 实时数据刷新
30

31
<FeatureToggle
32
  client:load
33
  feature="realtime"
34
  label="启用实时数据"
35
  description="每 5 秒自动刷新数据"
36
  :defaultEnabled="true"
37
/>
38

39
### 2. 数据导出选项
40

41
<DataExport
42
  client:idle
43
  :formats="['CSV', 'JSON', 'Excel', 'PDF']"
44
  :defaultFormat="'CSV'"
45
  :includeOptions="{
46
    charts: true,
47
    tables: true,
48
    filters: true
49
  }"
50
/>

1
---
2
import CodeRunner from '../../components/vue/CodeRunner.vue';
3
import InteractiveQuiz from '../../components/vue/InteractiveQuiz.vue';
4
import ConceptVisualizer from '../../components/vue/ConceptVisualizer.vue';
5

6
title: 'JavaScript 基础 - 交互式课程'
7
description: '通过实践学习 JavaScript 基础'
8
level: 'beginner'
9
estimatedTime: '30分钟'
10
---
11

12
# JavaScript 变量与数据类型
13

14
## 实践练习
15

16
### 1. 变量声明
17

18
尝试下面的代码编辑器：
19

20
<CodeRunner
21
  client:load
22
  language="javascript"
23
  :initialCode="`
24
// 声明一个变量
25
let message = 'Hello World';
26

27
// 修改变量的值
28
message = 'Hello JavaScript';
29

30
console.log(message);
31
  `"
32
  :testCases="[
33
    {
34
      input: '',
35
      expectedOutput: 'Hello JavaScript',
36
      description: '应该输出修改后的消息'
37
    }
38
  ]"
39
/>
40

41
### 2. 数据类型可视化
42

43
<ConceptVisualizer
44
  client:visible
45
  concept="dataTypes"
46
  :examples="{
47
    string: 'Hello World',
48
    number: 42,
49
    boolean: true,
50
    array: [1, 2, 3],
51
    object: { name: 'John', age: 30 }
52
  }"
53
/>
54

55
### 3. 理解测验
56

57
<InteractiveQuiz
58
  client:load
59
  :questions="[
60
    {
61
      question: 'let 和 const 的区别是什么？',
62
      type: 'multiple-choice',
63
      options: [
64
        'let 可重新赋值，const 不可',
65
        'const 用于常量，let 用于变量',
66
        '两者完全相同',
67
        'let 是块级作用域，const 不是'
68
      ],
69
      correctAnswers: [0, 1],
70
      explanation: 'let 允许重新赋值，const 用于声明常量'
71
    }
72
  ]"
73
  :passingScore="80"
74
/>

1
<template>
2
  <!-- 跟踪 MDX 交互 -->
3
</template>
4

5
<script setup>
6
import { onMounted, onUnmounted } from 'vue';
7

8
const props = defineProps({
9
  contentId: String,
10
  contentType: String,
11
});
12

13
// 跟踪组件使用
14
onMounted(() => {
15
  // 发送分析事件
16
  trackEvent('mdx_component_view', {
17
    component: props.contentId,
18
    type: props.contentType,
19
    timestamp: Date.now(),
20
  });
21

22
  // 跟踪交互
23
  const interactiveElements = document.querySelectorAll('[data-interactive]');
24
  interactiveElements.forEach(el => {
25
    el.addEventListener('click', trackInteraction);
26
  });
27
});
28

29
onUnmounted(() => {
30
  // 清理事件监听器
31
});
32

33
const trackEvent = (event, data) => {
34
  if (typeof window.gtag !== 'undefined') {
35
    window.gtag('event', event, data);
36
  }
37
};
38

39
const trackInteraction = (event) => {
40
  trackEvent('mdx_interaction', {
41
    element: event.target.dataset.interactive,
42
    action: event.type,
43
  });
44
};
45
</script>