ITADN · 发现全球开源项目

SurrealDB 是面向未来应用的终极云
数据库

更轻松地开发。更快地构建。更迅速地扩展。

SurrealDB 的文档，使用 Vike 构建。

如果您想贡献代码，请阅读贡献指南。

目录
SurrealDB 入门
学习 SurrealDB
为文档做贡献
- 适合初学者的问题
安装
向 SurrealDB 文档贡献 Lab 内容
概述
先决条件
创建新的 Lab
- 使用 Lab 创建工具
- 手动创建
内容指南
- 分类
- 主题
最佳实践
提交您的贡献
审查流程
需要帮助？
开发
- 铁路图（可复用）
构建
添加新文档
文件结构
代码检查

SurrealDB 入门

访问 surrealdb.com/docs 开始使用 SurrealDB。

学习 SurrealDB

SurrealDB University: https://surrealdb.com/learn/fundamentals
Aeon's Surreal Renaissance (Interative book): https://surrealdb.com/learn/book
Documentation: https://surrealdb.com/docs

为文档做贡献

请参阅我们的贡献指南。

适合初学者的问题

我们有一个适合初学者的问题列表，其中包含范围相对有限的 bug。这是一个很好的起点，可以积累经验并熟悉我们的贡献流程。

安装

要开始为 SurrealDB 文档做贡献，首先使用以下命令安装所需的软件包。

本项目使用 Bun 作为我们的包管理器。如果您尚未安装 Bun，请参阅适用于您操作系统的安装指南。它还需要 Node.js v20.0.0 或更高版本。

bun i

向 SurrealDB 文档贡献 Lab 内容

概述

Labs 是一系列社区和官方内容，旨在帮助用户学习和使用 SurrealDB。本指南将帮助您向文档贡献自己的 Lab 内容。

先决条件

系统上已安装 Bun](https://bun.sh/)
一个 GitHub 账户
基本的 Markdown 知识

创建新的 Lab

使用 Lab 创建工具

创建新 Lab 最简单的方法是使用内置工具：

克隆仓库并安装依赖项：

git clone https://github.com/surrealdb/docs.surrealdb.com.git
cd docs.surrealdb.com
bun install

运行实验室创建工具：

bun run make:lab

按照交互式提示提供以下信息：
- 实验室名称（必填）
- URL（可选）- 指向您的项目/仓库的链接
- 语言
  - Python
  - Rust
  - TypeScript
  - Go
  - Java
  - PHP
  - SurrealQL
- 类别（必填）- 从以下选项中选择：
  - 博客文章
  - 代码仓库
  - 视频
  - 文档
  - 学习资源
- 主题（可选）- 从以下选项中选择一项或多项：
  - AI
  - 云
  - 数据管理
  - 示例
  - 库
  - 安全
  - 模板
  - 工具
- 作者姓名（必填）
- 作者角色（社区内容必填）

手动创建

或者，您可以在 src/content/labs-items/ 中创建一个新 Markdown 文件来手动创建实验室，其结构如下：

---
title: "Your Lab Title"
url: "https://your-project-url.com"  # Optional
category: "Category Name"  # Must be one of the predefined categories
topics:  # Optional
  - Topic1
  - Topic2
author:
  name: "Your Name"
  role: "Your Role"
  avatar: "your-name-slug"  # Will be automatically generated
---

Your lab content here...

对于作者头像字段，您还需要将头像上传到 /src/assets/img/labs-authors，文件名必须与 lab markdown 中的 author 属性相同

内容指南

主题

选择相关主题以帮助用户找到您的内容：

AI：与人工智能相关的内容
Cloud：与云部署和 SurrealDB Cloud 相关的内容
Data management"：数据处理和管理
Examples：实用示例和指南
Libraries：客户端库和 SDK
Security：安全功能和最佳实践
Templates：可复用的项目模板、模式（schemas）和样板代码
Tooling：开发者工具、CLI、集成、插件和实用工具

最佳实践

标题：选择一个清晰、描述性的标题，以反映内容。保持简短和简洁，以提高可读性
内容（仅在未提供 URL 时必填）：
- 以简短的介绍开头
- 包含清晰的说明
- 在相关处添加代码示例
- 如有帮助，包含截图或图表
URL：如果你的实验有相关项目，请包含 URL
作者信息：
- 使用你的真实姓名
- 提供清晰的角色描述
- 对于官方 SurrealDB 内容，使用 "surrealdb" 作为作者名称

提交你的贡献

为你的实验创建一个新的分支
添加你的实验内容
提交你的更改
推送到你的 fork
创建一个 pull request

审查流程

你的实验将被审查：

技术准确性
内容质量
遵守指南
适当的分类和主题

需要帮助？

如果你需要协助或有疑问：

请记住，你的贡献有助于 SurrealDB 社区成长和进步。感谢你的贡献！

开发

以下命令启动一个本地开发服务器并打开一个浏览器窗口。大多数更改无需重启服务器即可实时反映。

bun dev

铁路图（可复用）

此仓库使用 Tab Atkins 的 JS 库渲染 SVG 铁路图（JS README, 项目页面）。

组件：RailroadDiagram 来自 @surrealdb/ui
在 src/utils/markdown.tsx 中配置为 MDX 短代码，因此内容文件中无需导入

在 MDX/Markdown 内容中的用法：

<RailroadDiagram ast='{
  "type": "Diagram",
  "padding": [10, 20, 10, 20],
  "children": [
    { "type": "Start", "startType": "simple", "label": "statement" },
    {
      "type": "Sequence",
      "children": [
        { "type": "NonTerminal", "text": "ACCESS" },
        { "type": "Choice", "index": 1, "children": [
          { "type": "Terminal", "text": "ON" },
          { "type": "Terminal", "text": "TO" }
        ]},
        { "type": "NonTerminal", "text": "resource" }
      ]
    },
    { "type": "End" }
  ]
}' />

ast 属性以 JSON 字符串的形式传递，并在传递给底层 RailroadDiagram 组件之前由 shortcode 包装器解析。

构建

以下命令将构建并生成静态内容到 build 目录，之后可以使用任何静态内容托管服务进行部署。

bun run build

添加新文档

文档页面位于 src/content/，并通过 vike-content-collection 加载。src/content/ 下的每个顶级文件夹都是一个内容集合，通过指向 src/content/config.ts 中模式的 +Content.ts 文件进行注册。

要添加新页面，请在相应的集合文件夹中创建一个 .md 或 .mdx 文件，其 frontmatter 需符合该集合的模式（参见 src/content/config.ts 中的 abstractDoc 和 labCollection）。侧边栏顺序由 frontmatter 中的 position 和子目录中的 __category.json 文件控制。

如果您添加了一个全新的集合，还需要在 src/content/config.ts 中注册它（通过 urlForCollection 设置 URL 前缀），并添加一个匹配的 +onBeforePrerenderStart.ts，以便预渲染路由。

文件结构

要为文档做出贡献，您的大部分更改将针对 src/content 目录。文档的每个部分都有自己的子目录，每个页面都是一个 Markdown 或 MDX 文件。

src/
    assets/      # Static images, styles, and data files
    components/  # React components (with co-located *.module.scss)
    content/     # vike-content-collection collections (one folder per collection)
    lib/         # Shared API/data helpers
    modals/      # Modal components
    pages/       # Vike filesystem-routed pages (+Page.tsx, +data.ts, +config.ts, ...)
    typings/     # Shared TypeScript types
    utils/       # Shared utilities (markdown, sidebar, collection helpers, ...)

Linting

为确保文档的一致性并遵循我们的风格指南，我们使用 bun run qc 来检查 linting 错误。你还可以使用 bun run qa 来自动修复大部分错误。

以下是一些你可能需要使用的常用命令。

bun install - 安装依赖项，首次使用或依赖项变更时
bun run dev - 运行开发服务器
bun run build - 构建网站
bun run preview - 预览你构建的版本
bun run qc - 检查代码质量（fmt + lint）
bun run qa - 应用安全的代码质量建议
bun run qau - 应用（不）安全的代码质量建议
bun run qts - 使用 TypeScript 进行类型检查

SurrealDB 是面向未来应用的终极云 数据库

更轻松地开发。 更快地构建。 更迅速地扩展。

目录