flarum · imgbot · Jul 7, 2025 · Jul 7, 2025 · Jul 7, 2025 · Nov 24, 2025
diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml
@@ -1,22 +1,32 @@
 name: Deploy to production
 
 on:
+  workflow_dispatch:
   push:
     branches:
-      - master
+      - main
 
 jobs:
   deploy:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@master
+      - uses: actions/checkout@v4
 
-      - name: executing remote upgrade
-        uses: appleboy/ssh-action@v1.0.3
+      - name: Use Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '24.x'
+          cache: 'yarn'
+      - run: yarn install --frozen-lockfile
+      - run: yarn build
+
+      - name: copy compiled assets to remote
+        uses: appleboy/scp-action@v1
         with:
           host: ${{ secrets.DEPLOY_HOST }}
           username: ${{ secrets.DEPLOY_USERNAME }}
           key: ${{ secrets.DEPLOY_SSH_KEY }}
           port: ${{ secrets.DEPLOY_PORT }}
-          script: cd /var/www/docs.flarum.org && ./deploy.sh
+          source: build
+          target: public_html/docs.flarum.org
diff --git a/README.md b/README.md
@@ -2,14 +2,50 @@
 
 This repository contains the source code for [Flarum's docs site](https://docs.flarum.org).
 
-In order to avoid conflicts and corruption during translation synchronization, we only currently accept content contributions in English, and translations are only accepted through [crowdin](https://crowdin.com/project/flarum-docs). We really appreciate all contributions, and these measures help ensure that documentation is up to date and avoids breaking unexpectedly. See [our docs](https://docs.flarum.org/contributing-docs-translations) for more information.
+In order to avoid conflicts and corruption during translation synchronization, we only currently accept content contributions in English, and translations are only accepted through [Crowdin](https://crowdin.com/project/flarum-docs). We really appreciate all contributions, and these measures help ensure that documentation is up to date and avoids breaking unexpectedly. See [our docs](https://docs.flarum.org/contributing-docs-translations) for more information.
+
+## Translations
+
+Translations are managed with [Crowdin](https://crowdin.com/project/flarum-docs), **not** by editing files in this repository directly.
+
+**English is the only source.** The `docs/` and `versioned_docs/` directories are the source of truth; every file under `i18n/<locale>/` is a translation managed by Crowdin and **should not be edited by hand** — manual edits there will be overwritten on the next sync.
+
+### How to contribute a translation
+
+1. Go to the [Flarum Docs Crowdin project](https://crowdin.com/project/flarum-docs) and sign in (a free Crowdin account is required).
+2. Pick your language. If it isn't listed, request it via the project.
+3. Translate strings in Crowdin's web editor. Source strings come from the English Markdown; keep Markdown structure, code blocks, and placeholders (e.g. `` `{user}` ``) intact.
+
+### How translations reach the site
+
+Crowdin's GitHub integration periodically pushes approved translations to the `l10n_master2` branch and opens a **"New Crowdin updates"** pull request. A maintainer reviews and merges it, after which the normal [deploy workflow](.github/workflows/deploy.yml) publishes the translated pages. Crowdin does **not** commit to `main` or publish anything on its own — a human merge is always required.
+
+> **Maintainers:** when reviewing a "New Crowdin updates" PR, build it locally first (`yarn build`) — translated content can contain Markdown that fails the MDX compiler (e.g. unescaped `{` or `<`), which would break the production build for **all** languages.
+
+## Search
+
+Search is powered by [Algolia](https://www.algolia.com/) via Docusaurus's built-in Algolia theme. Algolia uses an external web crawler that periodically indexes the **deployed site** at `https://docs.flarum.org` — it does not index local builds.
+
+This means:
+- New or updated pages will **not appear in search** until they are deployed to production and the Algolia crawler has re-indexed the site.
+- Pages must be listed in `sidebars.js` to be included in the built site and therefore indexed.
+- Search results are filtered by doc version (`contextualSearch: true`), so `2.x` pages won't appear when searching from the `1.x` docs and vice versa.
+
+To manually trigger a re-index after a significant content addition, use the Algolia Crawler dashboard (requires Algolia account access for `appId: QHP1YG60G0`, `indexName: flarum`).
 
 ## Testing locally
 
-Our documentation is generated with [Docusaurus](https://docusaurus.io/docs).
+Our documentation is generated with [Docusaurus](https://docusaurus.io/docs). It requires **Node.js 20 or newer**.
+
 Use Yarn to install the dependencies and start Docusaurus in a local webserver:
 
 ```bash
 yarn install
-yarn run start
+yarn start
+```
+
+To produce a production build (as the deploy workflow does):
+
+```bash
+yarn build
 ```
diff --git a/crowdin.yml b/crowdin.yml
@@ -1,7 +1,11 @@
 files:
   - source: /i18n/en/**/*
     translation: /i18n/%two_letters_code%/**/%original_file_name%
-  - source: /docs/**/*
-    translation: /i18n/%two_letters_code%/docusaurus-plugin-content-docs/current/**/%original_file_name%
+  # 2.x (current) translations are intentionally not synced. They were frozen at
+  # a Dec-2024 snapshot, fell ~18 months behind, and translated since-corrected
+  # content (e.g. the pre-Symfony mail driver API). They were removed ahead of the
+  # 2.0 release. Re-enable this mapping to resume 2.x translation from current English.
+  # - source: /docs/**/*
+  #   translation: /i18n/%two_letters_code%/docusaurus-plugin-content-docs/current/**/%original_file_name%
   - source: /versioned_docs/version-1.x/**/*
     translation: /i18n/%two_letters_code%/docusaurus-plugin-content-docs/version-1.x/**/%original_file_name%
diff --git a/docs/admin.md b/docs/admin.md
@@ -11,6 +11,6 @@ The Admin Dashboard has the following sections, being:
 - **Permissions** - Shows the permissions for each user group, and allows you to configure global and specific scopes.
 - **Appearance** - Allows you to customize the forum's colors, branding and add additional CSS for customization.
 - **Users** - Provides you with a paginated list of all the users in the forum, and grants you the ability to edit the user or take administrative actions.
-- **Advanced** - Allows you to configure advanced settings such as Maintenance Mode, Search drivers, and more.
+- **Advanced** - Allows you to configure advanced settings such as Maintenance Mode, Search drivers, Queue driver, and more.
 
 Apart from the above-mentioned sections, the Admin Dashboard also allows you to manage your Extensions (including the flarum core extensions such as Tags) under the _Features_ section. Extensions which modify the forum theme, or allow you to use multiple languages are categorized under the _Themes_ and _Languages_ section respectively.
diff --git a/docs/assets/api_flowchart.svg b/docs/assets/api_flowchart.svg
diff --git a/docs/assets/config-repositories.png b/docs/assets/config-repositories.png
diff --git a/docs/assets/extension-manager-page.png b/docs/assets/extension-manager-page.png
diff --git a/docs/assets/gambit_autocomplete_dropdown.png b/docs/assets/gambit_autocomplete_dropdown.png
diff --git a/docs/assets/global_search_modal.png b/docs/assets/global_search_modal.png
diff --git a/docs/assets/home_screenshot.png b/docs/assets/home_screenshot.png
diff --git a/docs/assets/install-extension.png b/docs/assets/install-extension.png
diff --git a/docs/assets/uninstall-extension.png b/docs/assets/uninstall-extension.png
diff --git a/docs/assets/update-extension.png b/docs/assets/update-extension.png
diff --git a/docs/config.md b/docs/config.md
@@ -32,9 +32,57 @@ Here's a quick overview of what everything means with an example file:
     'api' => 'api', // /api goes to the API
     'admin' => 'admin', // /admin goes to the admin
   ),
+  'queue' =>
+  array (
+    'driver' => 'sync', // Use the standard sync queue. Omitting this will entirely will have the same effect
+  ),
+  'fontawesome' =>
+  array (
+    'source' => 'local', // Use the bundled FontAwesome Free v7 icons. See below for other config options
+  )
 );
 ```
 
+### Configuration via environment variables
+
+Whilst the file based method described here is suitable for most Flarum installations, scaled Flarum instances or those deployed via CI/CD will probably benefit from being configured via the environment. Here's an example of how to do this:
+
+```php
+<?php return array (
+  'debug' => env('DEBUG')
+  ...
+);
+```
+
+This provides Flarum with the static configuration file it expects, but pulls variables from the environment at runtime.
+
+### Queues
+
+Flarum ships with support for two queue drivers - `sync` and `database`. Many tasks, or 'jobs' can be offloaded to a separate process in order to improve response times and provide a better user experience.
+
+The only configuration key read from `config.php` is `driver`. Omitting the `queue` block entirely is equivalent to setting `driver` to `sync`.
+
+* `sync` - default behaviour; jobs run immediately inline during the request
+* `database` - stores jobs in a dedicated `queue_jobs` database table, which are then processed via the [scheduler](/2.x/scheduler) in a separate process. It is strongly advised that the scheduler is configured to run _every minute_
+
+When the `database` driver is active, additional tuning options (retries, memory limit, timeout, etc.) become available in the admin panel under **Admin > Advanced Settings**.
+
+##### Other queue drivers
+
+Extensions such as [FoF Redis](https://github.com/FriendsOfFlarum/redis) provide additional queue drivers. These do not require any `queue` entry in `config.php` — they are configured through their own extension settings.
+
+### Announcements widget
+
+Flarum displays an announcements widget on the admin dashboard, showing the latest news from the official [Flarum community](https://discuss.flarum.org). This is enabled by default and refreshes weekly in the background.
+
+To disable it, add the following to your `config.php`:
+
+```php
+'flarum_announcements.disabled' => true,
+```
+
+When disabled, the widget is hidden from the dashboard, no outbound requests are made to discuss.flarum.org, and the scheduled refresh task is not registered.
+
 ### Maintenance modes
 
 Flarum has a maintenance mode that can be enabled by setting the `offline` key in the `config.php` file to one of the following values:
@@ -46,3 +94,33 @@ Flarum has a maintenance mode that can be enabled by setting the `offline` key i
 This can also be configured from the admin panel's advanced settings page:
 
 ![Toggle advanced page](https://user-images.githubusercontent.com/20267363/277113270-f2e9c91d-2a29-436b-827f-5c4d20e2ed54.png)
+
+### FontAwesome
+
+By default Flarum uses the bundled FontAwesome Free v7 icons. These can be switched out to use either a CDN hosted icon bundle, or a custom kit. See the [FontAwesome](fontawesome.md) page for full details on each source.
+
+```php
+<?php
+
+return [
+    'url' => 'https://example.com',
+    // ... other config
+
+    // FontAwesome Kit (Pro features + custom icons)
+    'fontawesome' => [
+        'source' => 'kit',
+        'kit_url' => 'https://kit.fontawesome.com/YOUR_KIT_CODE.js',
+    ],
+
+    // OR use a CDN
+    // 'fontawesome' => [
+    //     'source' => 'cdn',
+    //     'cdn_url' => 'https://cdnjs.cloudflare.com/ajax/libs/font-awesome/7.0.0/css/all.min.css',
+    // ],
+
+    // OR keep local (default, no config needed)
+    // 'fontawesome' => [
+    //     'source' => 'local',
+    // ],
+];
+```