Polish documentation formatting and standardise structure

.github/workflows/dependency-review.yml

@@ -17,7 +17,7 @@ permissions:
 
 jobs:
   dependency-review:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-slim
     steps:
       - name: "Checkout Repository"
         uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd

README.md

@@ -39,9 +39,9 @@ Pull requests to `main` are also validated in CI with formatting checks, `astro
 
 ## Project Structure
 
-```
+```text
 .
-├── astro.config.mjs    # Astro, Starlight, sidebar, social links, redirects
+├── astro.config.mjs    # Astro, Starlight, sidebar, and social links
 ├── markdoc.config.mjs  # Starlight Markdoc integration
 ├── public/             # Static files copied as-is
 src/
@@ -73,7 +73,7 @@ Prefer absolute internal links with trailing slashes, for example:
 [Installation](/getting-started/installation/)
 ```
 
-When routes move, update internal links to the new route. Keep legacy redirects in `astro.config.mjs` when an old public docs URL should continue to work.
+When routes move, update internal links to the new route. If an old public docs URL should keep working, add a redirect in `astro.config.mjs` (see the [Astro redirects reference](https://docs.astro.build/en/reference/configuration-reference/#redirects)).
 
 ## Images and Assets
 
@@ -93,10 +93,6 @@ The sidebar is configured in `astro.config.mjs`.
 
 Some sections are autogenerated from folders, while larger sections use explicit ordering so the sidebar remains predictable. When adding a new page, check whether the section uses `autogenerate` or a manually listed item.
 
-## Redirects
-
-`astro.config.mjs` includes redirects from older documentation routes to the current Starlight routes. Do not remove these just because the old route is no longer present in `src/content/docs/`; they preserve inbound links from the previous docs site.
-
 ## Deployment
 
 The production build outputs static files to `dist/`.

src/content/docs/admin-guide/company.mdoc

@@ -51,7 +51,7 @@ Configure the rest of your business profile in the same area:
 
 Set the default signature appended to system emails:
 
-```
+```text
 --
 Best regards,
 The Example Company Team

src/content/docs/admin-guide/config.mdoc

@@ -177,10 +177,12 @@ DB_PORT=3306             # Override database port
 
 ## Making Changes
 
+{% steps %}
 1. Edit `config.php` with a text editor
 2. Save the file
 3. Clear the cache: **System → Tools → Clear cache** (or delete `/data/cache/`)
 4. Test your changes
+{% /steps %}
 
 {% aside type="caution" %}
 Always back up `config.php` before making changes. A syntax error will break your installation.

src/content/docs/admin-guide/custom-payment-gateway.mdoc

@@ -70,16 +70,16 @@ Only trusted administrators should edit Custom gateway templates. Do not paste s
 ## Example: Different instructions by currency
 
 ```twig
-{ percent if invoice.currency == 'EUR' percent }
+{% if invoice.currency == 'EUR' %\}
   <p>Transfer to IBAN: DE00 0000 0000 0000 0000 00</p>
-{ percent elseif invoice.currency == 'USD' percent }
+{% elseif invoice.currency == 'USD' %\}
   <p>Transfer to account 1234567890, routing 021000021.</p>
-{ percent else percent }
+{% else %\}
   <p>Contact support for {{ invoice.currency }} payment instructions.</p>
-{ percent endif percent }
+{% endif %\}
 ```
 
-Replace `{ percent` with `{%` and `percent }` with `%}` when adding the template in FOSSBilling.
+Remove the backslashes when using this template in FOSSBilling.
 
 ## Supported template syntax
 
@@ -91,12 +91,14 @@ Do not use advanced Twig features such as importing templates, including templat
 
 After confirming the payment:
 
+{% steps %}
 1. Go to **Invoicing → Invoices**.
 2. Open the relevant invoice.
 3. Use **Mark as paid**.
 4. Select the Custom gateway if needed.
 5. Enter a transaction ID or payment reference.
 6. Choose whether FOSSBilling should execute the related invoice tasks.
+{% /steps %}
 
 The transaction ID is required when marking an invoice as paid through the Custom gateway.
 

src/content/docs/admin-guide/email-templates.mdoc

@@ -48,13 +48,13 @@ See [Twig Filters & Functions](/extensions-and-development/twig-filters/) for al
 Default templates use Markdown for simple formatting. Wrap your content with the `apply markdown_to_html` filter:
 
 ```twig
-\{% apply markdown_to_html %\}
-Hi \{\{ staff.name \}\},
+{% apply markdown_to_html %\}
+Hi {{ staff.name }},
 
 If you are reading this email, FOSSBilling is **configured properly** and is **able to send emails**.
 
-\{\{ guest.system_company.signature \}\}
-\{% endapply %\}
+{{ guest.system_company.signature }}
+{% endapply %\}
 ```
 
 Remove the backslashes when using this in your actual template.

src/content/docs/admin-guide/invoice-pdf.mdoc

@@ -24,8 +24,10 @@ Table cells can't span pages. Keep table rows compact enough to fit on one page.
 
 ### Creating a Custom Stylesheet
 
+{% steps %}
 1. Copy `/modules/Invoice/templates/pdf/default-invoice.css`
 2. Paste as `/modules/Invoice/templates/pdf/custom-invoice.css`
+{% /steps %}
 
 FOSSBilling automatically uses `custom-invoice.css` if it exists.
 
@@ -55,8 +57,10 @@ Customize the HTML structure by adding a custom Twig template.
 
 ### Creating a Custom Template
 
+{% steps %}
 1. Copy `/modules/Invoice/templates/pdf/default-invoice.twig`
 2. Paste as `/modules/Invoice/templates/pdf/custom-invoice.twig`
+{% /steps %}
 
 FOSSBilling uses `custom-invoice.twig` automatically.
 
@@ -82,14 +86,14 @@ The PDF renderer does not provide top-level `client`, `company`, or `currency` v
 
 ```twig
 <div class="custom-header">
-  {\% if logo_source %\}
+  {% if logo_source %\}
   <img src="{{ logo_source }}" alt="{{ seller['Name']|default(seller['Company']|default('Company logo'|trans)) }}">
-  {\% endif %\}
+  {% endif %\}
   <h1>{{ 'Invoice'|trans }} #{{ invoice.serie_nr }}</h1>
 </div>
 ```
 
-(Remove backslashes in actual template code; they are used here to prevent rendering in this documentation.)
+Remove backslashes in actual template code.
 
 ### Twig Filters
 
@@ -103,10 +107,12 @@ PDF templates support the same [Twig filters](/extensions-and-development/twig-f
 
 ## Testing Changes
 
+{% steps %}
 1. Make your edits to `custom-invoice.css` or `custom-invoice.twig`
 2. Generate a test invoice
 3. Download the PDF
 4. Review the output
+{% /steps %}
 
 {% aside type="tip" %}
 Twig templates may be cached. Clear the cache (**System → Tools → Clear cache**) if template changes do not appear.

src/content/docs/admin-guide/localization.mdoc

@@ -14,13 +14,13 @@ FOSSBilling ships with translations that are at least 25% complete. To install m
 
 ### Translation Structure
 
-```
-/locale/
-└── en_US/
-    └── LC_MESSAGES/
-        ├── messages.mo    ← Compiled translation (required)
-        └── messages.po    ← Source file (optional but helpful)
-```
+{% filetree %}
+- locale/
+  - en_US/
+    - LC_MESSAGES/
+      - messages.mo    ← Compiled translation (required)
+      - messages.po    ← Source file (optional but helpful)
+{% /filetree %}
 
 {% aside type="tip" %}
 Add your language to `/locale/locales.php` to show the native name in language selectors. This file is overwritten on updates, so you'll need to re-add it.
@@ -38,18 +38,22 @@ Add your language to `/locale/locales.php` to show the native name in language s
 
 Don't see your language?
 
+{% steps %}
 1. Join our [Discord](https://fossbilling.org/discord)
 2. Ask in `#localization` for it to be added
 3. We'll add it to Crowdin
 4. Start translating
+{% /steps %}
 
 ### Already Have a Translation?
 
 If you've created a complete translation locally:
 
+{% steps %}
 1. Submit a pull request to the [locale repository](https://github.com/FOSSBilling/locale)
 2. **Don't include the `.mo` file** — we generate those automatically
 3. We'll add it to Crowdin for community contributions
+{% /steps %}
 
 For assistance, ask in our [Discord](https://fossbilling.org/discord).
 

src/content/docs/admin-guide/product-types/apikeys.mdoc

@@ -1,6 +1,8 @@
 ---
 title: API Keys
 description: Sell API keys for your custom applications and services.
+sidebar:
+  order: 6
 ---
 
 API key products let you sell access to your own APIs or services. After purchase, the customer receives a unique key that your application can validate against FOSSBilling.
@@ -22,42 +24,45 @@ Disabling or removing this extension will delete the database table storing API
 
 ## Setting Up API Key Products
 
-### 1. Enable the Extension
+{% steps %}
 
-Go to **Extensions** and install "API Key Product".
+1. Enable the Extension
 
-### 2. Configure Key Generation
+    Go to **Extensions** and install "API Key Product".
 
-When creating the product, set these options:
+2. Configure Key Generation
 
-| Option | Default | Description |
-|--------|---------|-------------|
-| `Length` | 32 | Total characters in the key |
-| `Split` | Enabled | Add dashes for readability |
-| `Split Interval` | 8 | Characters between dashes |
-| `Capitalization` | Uppercase | Uppercase, lowercase, or mixed |
+    When creating the product, set these options:
 
-**Example key with default settings:**
+    | Option | Default | Description |
+    |--------|---------|-------------|
+    | `Length` | 32 | Total characters in the key |
+    | `Split` | Enabled | Add dashes for readability |
+    | `Split Interval` | 8 | Characters between dashes |
+    | `Capitalization` | Uppercase | Uppercase, lowercase, or mixed |
 
-```
-BA907863-47C1A4F5-3CB914D3-AC927BDD
-```
+    **Example key with default settings:**
 
-{% aside type="note" %}
-Dashes don't count toward the key length. If you disable splitting, the key would be `BA90786347C1A4F53CB914D3AC927BDD`.
-{% /aside %}
+    ```text
+    BA907863-47C1A4F5-3CB914D3-AC927BDD
+    ```
 
-### 3. Add Custom Parameters
+    {% aside type="note" %}
+    Dashes don't count toward the key length. If you disable splitting, the key would be `BA90786347C1A4F53CB914D3AC927BDD`.
+    {% /aside %}
 
-You can define custom parameters attached to each API key:
+3. Add Custom Parameters
 
-- `monthlyLimit` — number of allowed requests per month
-- `tier` — pricing tier (basic, pro, enterprise)
-- Any other metadata your application needs
+    You can define custom parameters attached to each API key:
 
-{% aside type="danger" %}
-Custom parameters are retrievable by anyone with the API key. **Don't store sensitive information here.**
-{% /aside %}
+    - `monthlyLimit` — number of allowed requests per month
+    - `tier` — pricing tier (basic, pro, enterprise)
+    - Any other metadata your application needs
+
+    {% aside type="danger" %}
+    Custom parameters are retrievable by anyone with the API key. **Don't store sensitive information here.**
+    {% /aside %}
+{% /steps %}
 
 ## API Endpoints
 
@@ -117,7 +122,7 @@ FOSSBilling includes rate limiting on all API requests (configured via the `rate
 Cache validation results in your application for a few minutes. This avoids hitting rate limits and reduces server load.
 {% /aside %}
 
-You can adjust rate limiting in the [configuration](/admin-guide/config#rate-limiter).
+You can adjust rate limiting in the [configuration](/admin-guide/config/#rate-limiter).
 
 ## Security Considerations
 

src/content/docs/admin-guide/product-types/domains.mdoc

@@ -52,10 +52,12 @@ The module exists but needs fixes. [Source code](https://github.com/FOSSBilling/
 
 ## Setting Up Domain Reselling
 
+{% steps %}
 1. Get API credentials from your chosen registrar
 2. Go to **System** → **Domain registration** in FOSSBilling
 3. Configure the registrar settings
 4. Set up pricing for each TLD you want to sell
 5. Enable the TLDs you want to offer
+{% /steps %}
 
 Need a registrar that is not supported yet? See [Creating a Registrar Integration](/extensions-and-development/guides/creating-a-registrar-integration/).

src/content/docs/admin-guide/product-types/downloadable.mdoc

@@ -1,6 +1,8 @@
 ---
 title: Downloadable Products
 description: Sell digital files that customers can download after purchase.
+sidebar:
+  order: 4
 ---
 
 Downloadable products let you sell digital files such as software packages, ebooks, templates, or internal documents. After checkout, the customer can download the file from their account area.
@@ -21,10 +23,12 @@ Downloadable products let you sell digital files such as software packages, eboo
 
 ## Setting Up Downloadable Products
 
+{% steps %}
 1. Create a new product and select "Downloadable" as the product type
 2. Upload the file(s) customers should receive
 3. Configure any download limits or restrictions
 4. Set up pricing and availability as normal
+{% /steps %}
 
 The product will appear in your store like any other. After purchase, customers can access their downloads from the client area.
 

src/content/docs/admin-guide/product-types/hosting.mdoc

@@ -40,10 +40,12 @@ Anything not listed above likely won't work. Check our [server managers document
 
 ## Setting Up Hosting
 
+{% steps %}
 1. Configure your server in **System** → **Hosting plans and servers**
 2. Create hosting plans that match your control panel packages
 3. Create products using the "Hosting" product type
 4. Link them to your hosting plans
+{% /steps %}
 
 See [server manager guides](/admin-guide/server-managers/) for specific setup instructions.