The documentation for SurrealDB, built using Vike.
If you want to contribute, then please read the contributing guidelines.
- Table of Contents
- Getting started with SurrealDB
- Learn SurrealDB
- Contributing to the documentation
- Installation
- Contributing Lab content to SurrealDB Documentation
- Overview
- Prerequisites
- Creating a new Lab
- Content guidelines
- Best practices
- Submitting your contribution
- Review process
- Need help?
- Development
- Building
- Adding a new doc
- File structure
- Linting
Visit surrealdb.com/docs to get started with SurrealDB.
- SurrealDB University: https://surrealdb.com/learn/fundamentals
- Aeon's Surreal Renaissance (Interative book): https://surrealdb.com/learn/book
- Documentation: https://surrealdb.com/docs
Please see our contributing guidelines.
We have a list of good first issues that contain bugs that have a relatively limited scope. This is a great place to get started, gain experience, and get familiar with our contribution process.
To get started with contributing to the SurrealDB documentation, first install the required packages using the following command.
This project uses Bun as our package manager. If you haven't installed Bun yet, then please see the installation guide for your operating system. It also requires Node.js v20.0.0 or higher.
bun i Labs are a collection of community and official content that helps users learn and work with SurrealDB. This guide will help you contribute your own lab content to the documentation.
- Bun installed on your system
- A GitHub account
- Basic knowledge of Markdown
The easiest way to create a new lab is using the built-in tool:
- Clone the repository and install dependencies:
git clone https://github.com/surrealdb/docs.surrealdb.com.git
cd docs.surrealdb.com
bun install- Run the lab creation tool:
bun run make:lab- Follow the interactive prompts to provide:
- Lab name (required)
- URL (optional) - Link to your project/repository
- Languages
- Python
- Rust
- TypeScript
- Go
- Java
- PHP
- SurrealQL
- Category (required) - Choose from:
- Blogposts
- Code Repositories
- Videos
- Documentation
- Learning Resources
- Topics (optional) - Select one or more from:
- AI
- Cloud
- Data Management
- Examples
- Libraries
- Security
- Templates
- Tooling
- Author name (required)
- Author role (required for community content)
Alternatively, you can create a lab manually by creating a new Markdown file in src/content/labs-items/ with the following structure:
---
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...For the author avatar field, you will also need to upload an avatar to /src/assets/img/labs-authors with the same file name as the author property in the lab markdown
Choose the most appropriate category for your lab:
- Blogposts: Blog posts and written content
- Source code: Code libraries and packages
- Videos: Video content and tutorials
- Documentation: Documentation and guides
- Learning resources: Other form of learning resource
Select relevant topics to help users find your content:
- AI: Artificial Intelligence related content
- Cloud: content related to cloud deployments and SurrealDB Cloud
- Data management": Data handling and management
- Examples: Practical examples and guides
- Libraries: Client libraries and SDKs
- Security: Security features and best practices
- Templates: Reusable project starters, schemas, and boilerplates
- Tooling: Developer tools, CLIs, integrations, plugins, and utilities
- Title: Choose a clear, descriptive title that reflects the content. Keep it short and concise for better readability
- Content (Only required when no URL is provided):
- Start with a brief introduction
- Include clear instructions
- Add code examples where relevant
- Include screenshots or diagrams if helpful
- URL: If your lab has an associated project, include the URL
- Author Information:
- Use your real name
- Provide a clear role description
- For official SurrealDB content, use "surrealdb" as the author name
- Create a new branch for your lab
- Add your lab content
- Commit your changes
- Push to your fork
- Create a pull request
Your lab will be reviewed for:
- Technical accuracy
- Content quality
- Adherence to guidelines
- Proper categorisation and topics
If you need assistance or have questions:
- Open an issue in the repository
- Join the SurrealDB community channels
- Check existing labs for examples
Remember, your contribution helps the SurrealDB community grow and learn. Thank you for contributing!
The following command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
bun dev
This repo renders SVG railroad diagrams using the JS library by Tab Atkins (JS README, project page).
- Component:
RailroadDiagramfrom@surrealdb/ui - Wired up as an MDX shortcode in
src/utils/markdown.tsx, so no import is needed inside content files
Usage in MDX/Markdown content:
<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" }
]
}' />The ast prop is passed as a JSON string and parsed by the shortcode wrapper before being handed to the underlying RailroadDiagram component.
The following command builds and generates static content into the build directory, and can then be served using any static contents hosting service.
bun run build
Documentation pages live in src/content/ and are loaded via vike-content-collection. Each top-level folder under src/content/ is a content collection registered through a +Content.ts file that points at a schema in src/content/config.ts.
To add a new page, create a .md or .mdx file inside the appropriate collection folder with frontmatter that matches the collection's schema (see abstractDoc and labCollection in src/content/config.ts). Sidebar ordering is controlled by position in frontmatter and __category.json files within subdirectories.
If you add a brand new collection, you will also need to register it in src/content/config.ts (URL prefix via urlForCollection) and add a matching +onBeforePrerenderStart.ts so the routes are prerendered.
To contribute to the documentation, most of your changes will be made to the src/content directory. Each section of the documentation has its own subdirectory, and each page is a Markdown or MDX file.
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, ...)To ensure the documentation is consistent and follows our style guide, we use bun run qc to check for linting errors. You can also use bun run qa to automatically fix most of the errors.
Here are the commands for some of the common commands you may need to use.
bun install- Install dependencies, first time or when they changebun run dev- Run a development serverbun run build- Build the websitebun run preview- Preview a build you madebun run qc- Check code quality (fmt + lint)bun run qa- Apply safe code quality suggestionsbun run qau- Apply (un)safe code quality suggestionsbun run qts- Type-check with TypeScript