Skip to content

Commit 9c55449

Browse files
coder-hxlcoder-hxl
committed
feat(docs): perfect documentation (guide, API,type)
1 parent 1533628 commit 9c55449

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

44 files changed

+2055
-2748
lines changed

‎docs/.vitepress/config.ts

Lines changed: 108 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -5,10 +5,11 @@ export default defineConfig({
55
title: 'x-crawl',
66
description: '灵活的 Node.js AI 辅助爬虫库',
77

8-
cleanUrls: true,
9-
108
head: [['link', { rel: 'icon', type: 'image/svg+xml', href: '/logo.svg' }]],
119

10+
cleanUrls: true,
11+
lastUpdated: true,
12+
1213
themeConfig: {
1314
// https://vitepress.dev/reference/default-theme-config
1415
logo: '/logo.svg',
@@ -17,6 +18,11 @@ export default defineConfig({
1718
provider: 'local'
1819
},
1920

21+
editLink: {
22+
pattern: 'https://github.com/coder-hxl/x-crawl/edit/main/docs/:path',
23+
text: '为此页提供修改建议'
24+
},
25+
2026
socialLinks: [
2127
{ icon: 'github', link: 'https://github.com/coder-hxl/x-crawl' },
2228
{ icon: 'discord', link: 'https://discord.gg/SF7aaebg4E' }
@@ -33,11 +39,38 @@ export default defineConfig({
3339
nav: [
3440
{ text: '指南', link: '/guide/index' },
3541
{ text: 'API', link: '/api/index' },
36-
{ text: '关于', link: '/about/index' }
42+
{ text: 'Type', link: '/type/index' },
43+
{
44+
text: '关于',
45+
items: [
46+
{ text: '常见问题', link: '/about/faq' },
47+
{ text: '社区', link: '/about/community' },
48+
{ text: '版本发布', link: '/about/releases' },
49+
{ text: '旧版本文档', link: '/about/old-docs' },
50+
{ text: 'Issues', link: '/about/issues' },
51+
{ text: '注意事项', link: '/about/announcements' }
52+
]
53+
}
3754
],
3855

3956
search: {
40-
provider: 'local'
57+
provider: 'local',
58+
options: {
59+
translations: {
60+
button: {
61+
buttonText: '搜索文档',
62+
buttonAriaLabel: '搜索文档'
63+
},
64+
modal: {
65+
noResultsText: '无法找到相关结果',
66+
resetButtonTitle: '清除查询条件',
67+
footer: {
68+
selectText: '选择',
69+
navigateText: '切换'
70+
}
71+
}
72+
}
73+
}
4174
},
4275

4376
sidebar: {
@@ -70,23 +103,85 @@ export default defineConfig({
70103
text: 'AI 辅助',
71104
items: [
72105
{ text: '创建 AI 应用', link: '/guide/create-ai-application' },
73-
{ text: '创建 AI 应用', link: '/guide/create-ai-application' },
74-
{ text: '创建 AI 应用', link: '/guide/create-ai-application' },
75-
{ text: '创建 AI 应用', link: '/guide/create-ai-application' },
76-
{ text: '创建 AI 应用', link: '/guide/create-ai-application' }
106+
{ text: '智能按需分析元素', link: '/guide/parse-elements' },
107+
{
108+
text: '智能生成元素选择器',
109+
link: '/guide/get-element-selectors'
110+
},
111+
{ text: '智能回复爬虫问题', link: '/guide/crawl-openai-help' },
112+
{
113+
text: '用户自定义 AI 功能',
114+
link: '/guide/crawl-openai-custom'
115+
}
77116
]
78117
},
79118
{
80119
text: '进阶',
81120
items: [
82-
{ text: '创建 AI 应用', link: '/guide/create-ai-application' },
83-
{ text: '创建 AI 应用', link: '/guide/create-ai-application' },
84-
{ text: '创建 AI 应用', link: '/guide/create-ai-application' }
121+
{ text: '爬取模式', link: '/guide/crawl-mode' },
122+
{ text: '设备指纹', link: '/guide/fingerprint' },
123+
{ text: '配置', link: '/guide/config' }
85124
]
86125
}
87126
],
88-
'/api': [{ text: 'api', items: [] }],
89-
'/about': [{ text: 'about', items: [] }]
127+
128+
'/api': [
129+
{
130+
text: '爬虫',
131+
items: [
132+
{ text: 'createCrawl', link: '/api/index' },
133+
{ text: 'crawlPage', link: '/api/crawl-page' },
134+
{ text: 'crawlHTML', link: '/api/crawl-html' },
135+
{ text: 'crawlData', link: '/api/crawl-data' },
136+
{ text: 'crawlFile', link: '/api/crawl-file' }
137+
]
138+
},
139+
{
140+
text: 'AI',
141+
items: [
142+
{ text: 'createCrawlOpenAI', link: '/api/create-crawl-openai' },
143+
{ text: 'parseElements', link: '/api/parse-elements' },
144+
{
145+
text: 'getElementSelectors',
146+
link: '/api/get-element-selectors'
147+
},
148+
{ text: 'help', link: '/api/help' },
149+
{ text: 'custom', link: '/api/custom' }
150+
]
151+
}
152+
],
153+
154+
'/type': [
155+
{
156+
text: '爬虫',
157+
items: [
158+
{ text: 'createCrawl', link: '/type/index' },
159+
{ text: 'crawlPage', link: '/type/crawl-page' },
160+
{ text: 'crawlHTML', link: '/type/crawl-html' },
161+
{ text: 'crawlData', link: '/type/crawl-data' },
162+
{ text: 'crawlFile', link: '/type/crawl-file' },
163+
{ text: 'CrawlOtherConfig', link: '/type/crawl-other-config' }
164+
]
165+
},
166+
{
167+
text: 'AI',
168+
items: [
169+
{
170+
text: 'createCrawlOpenAI',
171+
link: '/type/create-crawl-openai'
172+
},
173+
{ text: 'parseElements', link: '/type/parse-elements' },
174+
{
175+
text: 'getElementSelectors',
176+
link: '/type/get-element-selectors'
177+
},
178+
{
179+
text: 'CrawlOpenaiOtherConfig',
180+
link: '/type/crawl-openai-other-config'
181+
}
182+
]
183+
}
184+
]
90185
},
91186

92187
footer: {

‎docs/.vitepress/theme/custom.css

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
*::-webkit-scrollbar {
2+
width: 8px;
3+
}
4+
5+
*::-webkit-scrollbar-thumb {
6+
border-radius: 10px;
7+
background-color: #b2bbbe;
8+
}
9+
10+
*::-webkit-scrollbar-track {
11+
border-radius: 10px;
12+
}

‎docs/.vitepress/theme/style/vars.css

Lines changed: 21 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,27 @@
1+
/**
2+
* Colors
3+
* -------------------------------------------------------------------------- */
4+
15
:root {
2-
--c-yellow: #feba07;
3-
--c-red: #7c1823;
6+
--c-yellow-theme: #feba07;
7+
--c-red-theme: #7c1823;
48
}
59

10+
/**
11+
* Component: Button
12+
* -------------------------------------------------------------------------- */
613
:root {
7-
--vp-home-hero-image-background-image: linear-gradient(180deg, var(--c-yellow) 60%, var(--c-red) 30%);
8-
--vp-home-hero-image-filter: blur(40px);
9-
--vp-c-brand-1: #c79925;
10-
--vp-c-brand-2: #feba07;
14+
--vp-button-brand-bg: var(--c-yellow-theme);
15+
--vp-button-brand-hover-bg:#e4a507;
1116
}
1217

18+
/**
19+
* Component: Home
20+
* -------------------------------------------------------------------------- */
21+
22+
:root {
23+
--vp-home-hero-name-color: transparent;
24+
--vp-home-hero-name-background: linear-gradient(290deg, var(--c-red-theme) 6%, var(--c-yellow-theme));
25+
--vp-home-hero-image-background-image: linear-gradient(180deg, var(--c-yellow-theme) 60%, var(--c-red-theme) 30%);
26+
--vp-home-hero-image-filter: blur(40px);
27+
}

‎docs/about/announcements.md

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# 注意事项
2+
3+
- x-crawl 仅供合法用途，禁止使用该工具进行任何违法活动，包括但不限于未经授权的数据采集、网络攻击、隐私侵犯等行为。
4+
- 在进行数据采集之前，请确保您已经获得了目标网站的明确授权，并遵守其 robots.txt 文件规定以及使用条款。
5+
- 避免对目标网站造成过大的访问压力，以免触发其反爬策略或造成服务器宕机。

‎docs/about/community.md

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
# 社区
2+
3+
- **Discord 聊天:** 通过 [Discord](https://discord.gg/SF7aaebg4E) 与其他 x-crawl 用户实时提问和讨论（提前了解关于 x-crawl 的动态）。
4+
- **GitHub 讨论:** 使用 [GitHub 讨论](https://github.com/coder-hxl/x-crawl/discussions) 来进行留言板式的问题和讨论。
5+
6+
不得提交与任何非法活动相关的问题和讨论。x-crawl 仅供合法用途，禁止使用该工具进行任何违法活动，包括但不限于未经授权的数据采集、网络攻击、隐私侵犯等行为。请确保您的使用行为始终符合法律法规和道德标准，共同维护一个安全、合法的网络环境。

‎docs/about/faq.md

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
# 常见问题
2+
3+
## crawlPage API 跟 puppeteer 的关系
4+
5+
crawlPage API 内置了 [puppeteer](https://github.com/puppeteer/puppeteer) ，您只需要传入一些配置选项即可让 x-crawl 帮助您简化操作，并拿到完好无损的 Brower 实例和 Page 实例，x-crawl 并不会对其重写。
6+
7+
## 使用 crawlPage API 造成程序崩溃
8+
9+
如果你需要在一个 crawlPage 爬取很多页面，建议在每个页面爬下来后，用 [onCrawlItemComplete 生命周期函数](#onCrawlItemComplete) 来处理每个目标的结果并关闭 page 实例，如果不进行关闭操作，则可能因开启的 page 过多而造成程序崩溃（跟自身设备性能有关）。
10+
11+
```js{11,12,13,14,15,16,,17,,18,35,36,37,38,39,40}
12+
import { createCrawl } from 'x-crawl'
13+
14+
const crawlApp = createCrawl()
15+
16+
// 爬取目标少的推荐
17+
crawlApp
18+
.crawlPage([
19+
'https://www.example.com/page-1',
20+
'https://www.example.com/page-2'
21+
])
22+
.then((results) => {
23+
for (const itemResult of results) {
24+
const { page } = itemResult.data
25+
26+
// 后续不再使用就关闭
27+
page.close()
28+
}
29+
})
30+
31+
// 爬取目标多的推荐
32+
// 通过进阶配置的 onCrawlItemComplete
33+
crawlApp.crawlPage({
34+
targets: [
35+
'https://www.example.com/page-1',
36+
'https://www.example.com/page-2',
37+
'https://www.example.com/page-3',
38+
'https://www.example.com/page-4',
39+
'https://www.example.com/page-5',
40+
'https://www.example.com/page-6',
41+
'https://www.example.com/page-7',
42+
'https://www.example.com/page-8',
43+
'https://www.example.com/page-9',
44+
'https://www.example.com/page-10'
45+
],
46+
onCrawlItemComplete(crawlPageSingleResult) {
47+
const { page } = crawlPageSingleResult.data
48+
49+
// 后续不再使用就关闭
50+
page.close()
51+
}
52+
})
53+
```

‎docs/about/index.md

Whitespace-only changes.

‎docs/about/issues.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# Issues
2+
3+
如果您有 **问题 、需求、好的建议** 可以在 [GitHub Issues](https://github.com/coder-hxl/x-crawl/issues) 中提 **Issues** 。

‎docs/about/old-docs.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# 旧版本文档
2+
3+
v9.0.0 版本：https://github.com/coder-hxl/x-crawl/blob/v9.0.0/docs/cn.md

‎docs/about/releases.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# 版本发布
2+
3+
完整的过往发布记录可以在 [GitHub](https://github.com/coder-hxl/x-crawl/blob/main/CHANGELOG.md) 查阅。

0 commit comments

Comments
 (0)