RavenDB Documentation
This documentation is built using Docusaurus, an open-source modern static website generator.
Cloning the repository
To clone the repository and checkout the main branch:
git clone https://github.com/ravendb/docs.git
cd docs
git checkout main
Contributing
- Open the markdown file you want to change, commit the changes, and create a pull request.
- Describe the changes made in the commits and pull request description.
Installation
npm ci
Local development
npm run start
This command starts a local development server and opens up a browser window.
Most changes are reflected live without having to restart the server (hot reload).
To run only selected versions (to shorten build time):
Build
docusaurus build
This command generates static content into the build directory and can be served using any static contents hosting service.
Note it may be necessary to increase Node.js max memory usage, e.g. to 8 GB
$env:NODE_OPTIONS="--max-old-space-size=8192"
To build only selected versions (to shorten build time and save memory):
Serving static content
Static content can be served using a static file server, such as serve:
npm run serve
Documentation structure
The documentation is organized into two main directories
docs: Contains the documentation files for latest RavenDB version.
versioned_docs: Contains the documentation files for all other RavenDB versions.
Adding a new version
To add a new documentation version:
- Create a snapshot of the current version in the
versioned_docs directory.
Use: npm run docusaurus docs:version version_label
- To make the new version selectable in the sidebar, update the current version number in the
docs property of the docusaurus.config.ts file.
E.g., to add version 7.2:
- Create a version for
7.1npm run docusaurus docs:version 7.1
- Set
7.2 as the current docs version.
docusaurus.config.ts file:docs: {
sidebarPath: "sidebars.ts",
routeBasePath: "/",
includeCurrentVersion: true,
lastVersion: 'current',
versions: {
current: {
label: "7.2",
path: "7.2"
}
},
onlyIncludeVersions: getOnlyIncludeVersions(),
//editUrl:
// 'https://github.com/ravendb/docs/tree/main/'
},
Update latestVersion in customFields of docusaurus.config.ts.
Update defaultVersion in handle_redirects.js.
Modifying latest version
To modify the latest version of the documentation, you can edit the files in the docs directory.
Any changes made here will be reflected in the latest version of the documentation.
Modifying previous versions
To modify a previous version of the documentation, you can edit the files in the versioned_docs/version-version_label directory.
Versions are entirely separate, so changes made for one version will not affect other versions.
Docusaurus components
Tabs and TabItem: Create tabbed content for organizing related information.
<Tabs>
<TabItem value="rql" label="RQL">
// RQL Query
from Orders
where Total > 100
</TabItem>
<TabItem value="linq" label="LINQ">
// LINQ C# code
var orders = session
.Query<Order>()
.Where(x => x.Total > 100)
.ToList();
</TabItem>
</Tabs>
CodeBlock: Displays formatted code snippets with syntax highlighting:
<CodeBlock language="csharp">
{`
// Call 'Execute' directly on the index instance
new Orders_ByTotal().Execute(store);
`}
</CodeBlock>
Or use triple backticks (```) with a language identifier to create a fenced code block with syntax highlighting:
```csharp
// Call 'Execute' directly on the index instance
new Orders_ByTotal().Execute(store);
```
Admonition: Shows styled callout boxes to highlight important content.
Available types: note, warning, info, tip, danger.
<Admonition type="note" title="Important">
Remember to back up your data before making major changes.
</Admonition>
Custom components
Apart from the standard Docusaurus components, this documentation uses the following custom components
LanguageSwitcher: A component responsible for handling switching between different language versions of the documentation.
Languages supported by particular document are stored in supportedLanguages array.
export const supportedLanguages = ["csharp", "java", "nodejs"];
<LanguageSwitcher supportedLanguages={supportedLanguages} />
LanguageContent: A component that displays documentation content based on the selected language.
<LanguageContent language="csharp">
<!-- Content specific to C# language -->
</LanguageContent>
Authoring tutorials
Detailed articles on using custom components are available in the templates directory.
Alternatively, you can view them at /templates while your local environment is active.
Page metadata and sidebar settings
Each .mdx file begins with a block delimited by --- that defines metadata used by Docusaurus for rendering, sidebar navigation, and page behavior.
For example:
---
title: "Enable Data Archiving"
hide_table_of_contents: true
sidebar_label: "Enable Data Archiving"
sidebar_position: 1
---
Key fields:
title: The document’s title metadata. This is used in the browser tab and SEO,
and is also shown as the main heading only if you don’t provide your own # Heading in the MDX body.
sidebar_label: Sets the text displayed for this page in the left sidebar menu.
sidebar_position: Controls the article’s position in the sidebar.
Use this to place the article relative to others in the same folder or section.
Lower numbers appear higher in the menu.
Category metadata for subfolders
When adding a new subfolder, you must create a _category_.json file to define how the section appears in the sidebar.
Example of a _category_.json file:
{
"position": 4,
"label": "Data Archival"
}
Key fields:
label: Sets the name of the folder as it will appear in the sidebar.
position – Controls the folder’s order relative to sibling items in the sidebar. Lower numbers appear higher.
Report broken links
To create a broken links report during the build process, set the docusaurus.config.ts file onBrokenLinks and onBrokenMarkdownLinks options to warn before building the site using npm run start or npm run build.
onBrokenLinks: "warn",
onBrokenMarkdownLinks: "warn",
onBrokenAnchors: "ignore",
To disable broken links reporting, set both options to ignore.
onBrokenLinks: "ignore",
onBrokenMarkdownLinks: "ignore",
onBrokenAnchors: "ignore",
Updating redirects for moved documentation
When moving a documentation page, it's necessary to add a redirect entry to /scripts/redirects.json file.
For example, when moving documentation page from /studio/database/code-assistance to /querying/rql/rql-code-assistance for versions 7.2 and above, add the following entry:
{
"key": "/studio/database/code-assistance",
"value": {
"targetUrl": "/querying/rql/rql-code-assistance",
"minimumVersion": "7.2"
}
}