unraid/docs: Unraid Documentation · GitHub

Unraid Documentation

Source for the official Unraid documentation site.
Explore the docs »

View Site · Report Bug · Request Content

1. About The Project
   • Built With
2. Getting Started
   • Prerequisites
   • Installation
3. Usage
4. Roadmap
5. Contributing
6. License
7. Contact
8. Acknowledgments

This repository powers the public Unraid Docs site. It contains source content, UI components, and supporting scripts that help the Unraid team publish accurate, localized, and accessible documentation for Unraid OS and connected services.

The documentation site is built on Docusaurus 3, rendered as a static site, and deployed via GitHub Pages. Remark-based linting, Crowdin integrations, and automated formatting scripts keep Markdown/MDX contributions consistent across the project.

(back to top)

(back to top)

Follow these steps to work on the docs locally.

• Node.js 22 or newer (see the package.json engines field)
• pnpm via Corepack
• Recommended: nvm for managing Node versions

Install or update Node with nvm:

nvm install --lts
nvm use

1. Clone the repo

   git clone https://github.com/unraid/docs.git
   cd docs

2. Install dependencies

   corepack enable
   pnpm install

This repo includes a VS Code dev container for contributors who want a local environment that closely matches the GitHub Actions Ubuntu/Node/pnpm setup.

To use it:

1. Install Docker Desktop or another compatible container runtime.
2. Install the Dev Containers extension for VS Code.
3. Open this repo in VS Code and choose Dev Containers: Reopen in Container.

The container uses the Node.js version from .nvmrc, enables Corepack/pnpm, installs repo dependencies, forwards the Docusaurus dev server on port 3001, and includes useful CLI tools such as git, gh, jq, ripgrep, nvi, shellcheck, and actionlint.

Once the container is ready, see Usage for local development commands.

VS Code Dev Containers can share host Git credentials with the container. See Sharing Git credentials with your container for SSH agent and credential-helper setup. GitHub CLI authentication is separate; run gh auth login inside the container if you need authenticated gh commands. The container stores GitHub CLI config in a Docker named volume (gh-config) so gh authentication can persist across dev container rebuilds and can be shared with other dev containers on the same Docker engine.

(back to top)

Spin up a local Docusaurus dev server:

pnpm start

The local docs dev server listens on http://localhost:3001 by default. This keeps local iframe/embed testing aligned with iframe-test.html and other localhost examples in the repo.

Preview specific locales (one at a time):

pnpm start -- --locale zh
pnpm start -- --locale es

Run Docusaurus lint/build checks:

pnpm lint

Additional project scripts:

• Type check TypeScript: pnpm typecheck
• Unit tests (watch): pnpm test
• Single test run (CI): pnpm test:run
• Build production site: pnpm build
• Preview production build: pnpm serve

(back to top)

The docs search index is refreshed by the GitHub Actions workflow at .github/workflows/algolia-reindex.yml.

That workflow matches the current Algolia Crawler API flow for this site:

• It looks up crawler unraid with GET https://crawler.algolia.com/api/1/crawlers?name=unraid
• It checks crawler details with GET https://crawler.algolia.com/api/1/crawlers/<crawler_id>
• It triggers POST https://crawler.algolia.com/api/1/crawlers/<crawler_id>/reindex

The workflow runs automatically on main when published docs content changes, and it can also be started manually with Actions > Algolia Reindex > Run workflow.

To enable it in GitHub, create these repository secrets:

• ALGOLIA_CRAWLER_USER_ID
• ALGOLIA_CRAWLER_API_KEY

You can find both in the Algolia dashboard under Data sources > Crawler > Settings.

Optional repository variables:

• ALGOLIA_APP_ID defaults to JUYLFQHE7W
• ALGOLIA_CRAWLER_NAME defaults to unraid
• ALGOLIA_REINDEX_DELAY_SECONDS defaults to 300

The workflow does not need the standard ALGOLIA_API_KEY secret. Reindexing uses the crawler-specific credentials above.

(back to top)

Forked pull requests do not get native Cloudflare preview builds, so this repo uses a two-workflow GitHub Actions flow for untrusted contributions:

• .github/workflows/fork-preview-build.yml runs on fork PRs, installs dependencies, builds the site, and uploads the static build/ output as an artifact.
• .github/workflows/fork-preview-deploy.yml runs after that build completes, downloads the artifact in a trusted workflow, and deploys it to a preview-only Cloudflare Pages project with wrangler pages deploy --branch=pr-<number>.

This keeps Cloudflare secrets out of the untrusted PR build while still producing a stable preview URL at https://pr-<number>.<project>.pages.dev.

Set these before enabling the workflows:

• Repository variable: CLOUDFLARE_PREVIEW_PAGES_PROJECT
• Repository secret: CLOUDFLARE_ACCOUNT_ID
• Repository secret: CLOUDFLARE_DEPLOY_TOKEN

Recommended setup:

1. Create a separate Cloudflare Pages project dedicated to previews only.
2. Keep production on the existing deployment path.
3. Scope the Cloudflare deploy token to Pages edit access for the account that owns the preview project.

(back to top)

New to the docs? Start with the contributor Style Guide for voice, formatting, and workflow expectations. It covers terminology, MDX conventions, screenshots, and review tips.

Once you're comfortable with the guidelines, typical workflow looks like:

1. Fork the project
2. Create a feature branch (git checkout -b docs/your-change)
3. Run pnpm lint before committing
4. Commit with a clear message (git commit -m "docs: describe change")
5. Push to your fork and open a pull request against main

(back to top)

Help translate Unraid Docs for the global community.

• Join the project on Crowdin: unraid.crowdin.com/unraid-docs
• Follow the glossary and tone guidance in the Style Guide
• Use pnpm crowdin:upload or pnpm crowdin:upload:sources after changing English source docs
• Use pnpm crowdin:upload:translations -- --language <lang> after manually fixing files under i18n/ so those fixes are pushed back to Crowdin before the next download
• The upload wrapper accepts the repo locale codes directly: use de, es, fr, and zh for i18n/zh; it normalizes zh to Crowdin's zh-CN project language code automatically
• Use pnpm crowdin:download to pull the latest exported translations after uploads
• pnpm crowdin:sync updates source strings and downloads translations, but it does not replace crowdin:upload:translations when you need to preserve manual translation fixes

Crowdin suggestions are reviewed regularly by maintainers and native-language contributors.

(back to top)

© 2024 Lime Technology, Inc. All rights reserved. See the Unraid Legal Terms for usage guidelines.

(back to top)

Need help? Open an issue on GitHub or reach us via unraid.net/contact.

Project Link: https://github.com/unraid/docs

(back to top)

• Docusaurus
• Crowdin
• Remark Lint
• Vitest

(back to top)