The documentation for SurrealDB, built using Astro.

If you want to contribute, then please read the contributing guidelines.

• Getting Started with SurrealDB
• Learn SurrealDB
• Contributing to the Documentation
  • Good First Issues
• Installation
• Contributing Lab Content
  • Overview
  • Prerequisites
  • Creating a New Lab
    • Using the Lab Creation Tool
• Categories
• Topics
• 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:

1. Clone the repository and install dependencies:

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

2. Run the lab creation tool:

bun run make:lab

3. Follow the interactive prompts to provide:
   • Lab name (required)
   • URL (optional) - Link to your project/repository
   • Category (required) - Choose from:
     • CI/CD
     • Demos
     • Deployment Tools
     • Development Tools
     • Docker Images
     • Integrations
     • Libraries
     • SDKs
     • Templates
     • Tutorials
     • Videos
   • Topics (optional) - Select one or more from:
     • AI
     • Data Management
     • Embedding
     • Security
     • Examples
     • Optimisation
     • Beginner
   • 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 avater 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:

• CI/CD: Continuous integration and deployment tools
• Demos: Example applications and demonstrations
• Deployment Tools: Tools for deploying SurrealDB
• Development Tools: Tools for development workflow
• Docker Images: Docker-related resources
• Integrations: Third-party integrations
• Libraries: Code libraries and packages
• SDKs: Software development kits
• Templates: Project templates and starters
• Tutorials: Step-by-step guides
• Videos: Video content and tutorials

Select relevant topics to help users find your content:

• AI: Artificial Intelligence related content
• Data Management: Data handling and management
• Embedding: Embedding-related features
• Security: Security features and best practices
• Examples: Code examples and snippets
• Optimisation: Performance optimization
• Beginner: Content suitable for beginners

1. Title: Choose a clear, descriptive title that reflects the content. Keep it short and concise for better readability
2. 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
3. URL: If your lab has an associated project, include the URL
4. Author Information:
   • Use your real name
   • Provide a clear role description
   • For official SurrealDB content, use "surrealdb" as the author name

1. Create a new branch for your lab
2. Add your lab content
3. Commit your changes
4. Push to your fork
5. 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

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

READ VERY CAREFULLY

When adding a new doc, you MUST update redirect logic
If this does not happen, you'll get endless redirects :D
In: project://aws/viewer-request/index.js#4

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 an MDX file.

src/
    assets/
    components/
    content/
        doc-surrealdb/
        doc-surrealql/
        doc-surrealist/
        ...
    layouts/
    pages/
    styles/
    util/ 

To ensure the documentation is consistent and follows our style guide, we use make qc to check for linting errors. You can also use make qa to automatically fix most of the errors.

Here are the commands for some of the common commands you may need to use.

• make install - Install dependencies, first time or when they change
• make dev - Run a development server
• make build - Build the website
• make preview - Preview a build you made
• make qc - Check code quality (fmt + lint)
• make qa - Apply safe code quality suggestions
• make qau - Apply (un)safe code quality suggestions