Nitrokey · daringer · Jan 27, 2026
diff --git a/source/_ext/faq_item.py b/source/_ext/faq_item.py
@@ -15,9 +15,8 @@ class FAQItem(SphinxDirective):
     """
 
     has_content = True
-    required_arguments = 1
-    optional_arguments = 30
-    final_argument_whitespace = True
+    required_arguments = 0
+    optional_arguments = 0
     option_spec = {
         "class": directives.class_option,
     }
@@ -33,16 +32,19 @@ def _make_slug(self, s: str) -> str:
 
     def run(self) -> list[nodes.Node]:
 
+        # question is the first line of the body content
+        question = self.content[0]
+        # remaining content is the answer
+        answer_content = self.content[2:]
+        answer_offset = self.content_offset + 2
+
         # answer (block content)
         content = nodes.container()
         # ... parse
-        self.state.nested_parse(self.content, self.content_offset, content)
+        self.state.nested_parse(answer_content, answer_offset, content)
         answer = nodes.definition("", *content.children)
         # ... assemble
         a_item = nodes.definition_list_item("", answer)
-
-        # question:
-        question = " ".join(self.arguments)
         # ... get slug
         slug = self._make_slug(question)
         # ... get formatted text

diff --git a/source/components/nethsm/faq.rst b/source/components/nethsm/faq.rst
@@ -1,15 +1,18 @@
 Frequently Asked Questions (FAQ)
 ================================
 
-.. faq:: Is NetHSM FIPS or Common Criteria certified?
+.. faq::
+   Is NetHSM FIPS or Common Criteria certified?
 
    Not yet but we are aiming for certifications in the future. Please contact us if you are interested in supporting these efforts.
 
-.. faq:: Which protections against physical tampering are in place?
+.. faq::
+   Which protections against physical tampering are in place?
 
    NetHSM is sealed which allows to detect physical tampering. It contains a TPM which is protected against physical tampering. The TPM is the root of trust and securely stores cryptographic keys which are used to encrypt and decrypt further data and keys in the NetHSM. This protects against booting malicious firmware and software and decrypting data and keys being stored. The current NetHSM doesn't contain additional sensors to detect tampering.
 
-.. faq:: Where can I learn more about NetHMS's security architecture and implementation?
+.. faq::
+   Where can I learn more about NetHMS's security architecture and implementation?
 
    Start with the chapters Getting Started, Administration and Operations. Proceed with the following resources.
 
@@ -18,7 +21,8 @@ Frequently Asked Questions (FAQ)
    * `Full source code <https://github.com/Nitrokey/nethsm/>`_
    * Physical random number generator (TRNG) of quality PTG.3 according to AIS-20: `hardware <https://github.com/Nitrokey/nitrokey-trng-rs232-hardware>`_, `firmware <https://github.com/Nitrokey/nitrokey-trng-rs232-firmware>`_
 
-.. faq:: Roadmap: Which features are planned?
+.. faq::
+   Roadmap: Which features are planned?
 
    Work in progress:
 

diff --git a/source/components/nextbox/faq/generic.rst b/source/components/nextbox/faq/generic.rst
@@ -1,7 +1,8 @@
 Generic FAQ
 ===========
 
-.. faq:: What to do if my NextBox doesn't start?
+.. faq::
+   What to do if my NextBox doesn't start?
 
   If your NextBox doesn't start correctly or you have some other problem using
   it, chances are a soft reset can fix it:
@@ -15,28 +16,33 @@ Generic FAQ
   ability to help you might be limited if you changed your system configuration
   using for example ssh.
 
-.. faq:: How can I factory-reset my NextBox?
+.. faq::
+   How can I factory-reset my NextBox?
 
   Press the hardware button for 5 seconds, see
   :doc:`../technical/factory-reset`. To press the button use a thin (~1mm) pin
   like a smartphone sim-card tray removal device.
 
-.. faq:: What do the different LED colors mean?
+.. faq::
+   What do the different LED colors mean?
 
   The detailed document can be found here: :doc:`../technical/led-colors`
 
-.. faq:: Can the inital setup be done using a monitor & keyboard?
+.. faq::
+   Can the inital setup be done using a monitor & keyboard?
 
   No, this is not possible as the regular login is disabled on delivery. Please
   connect the the NextBox to a network and access the NextBox using
   `nextbox.local`_ or the IP directly.
 
-.. faq:: What is the typical power consumption?
+.. faq::
+   What is the typical power consumption?
 
   The minimum of 0,6A (3W) is rarely reached, in idle mostly around 1A (5W) and
   more than 2A (10W) under higher loads. 
 
-.. faq:: How secure is the NextBox?
+.. faq::
+   How secure is the NextBox?
 
   Debian with frequent `unattended-upgrades` based security updates, a minimal
   attack surface by ensuring that not a single unneccessary port is open 
@@ -45,39 +51,45 @@ Generic FAQ
   2-Factor-Authentification supported login method with e.g., a Nitrokey FIDO2.**
 
 
-.. faq:: What do all the ssh-related "warnings" mean?
+.. faq::
+   What do all the ssh-related "warnings" mean?
 
   Once you set up your ssh-access, you make yourself technically responsible for
   your NextBox. We do provide help as good as we can as goodwill, but under the
   line we cannot provide generic Linux-administration support outside of the
   intended NextBox use-cases.
 
-.. faq:: Can I mirror my NextBox onto another NextBox?
+.. faq::
+   Can I mirror my NextBox onto another NextBox?
 
   This translates to a cluster setup, which is considered an (paid) enterprise
   solution by Nextcloud. The details, especially data consistency and collision
   handling, are far from trivial to realize. Nevertheless, we also see demand
   for more sophisticated backup solutions and will address this issue.
 
-.. faq:: What to do to run/install/fix Nextcloud App "XYZ"? Why does Nextcloud feature XYZ not work?
+.. faq::
+   What to do to run/install/fix Nextcloud App "XYZ"? Why does Nextcloud feature XYZ not work?
 
   Generally we cannot help in detail for these topics. Nextcloud internals and
   apps are out-of-scope for the NextBox development as we use the stock Docker
   images provided by Nextcloud. Ultimately, if some NextBox/OS configuration is
   blocking an app to run properly we for sure will look into fixing it.
 
-.. faq:: Can I connect/use the NextBox using WiFi? 
+.. faq::
+   Can I connect/use the NextBox using WiFi?
 
   No, currently this is not (easily) possible, only wired ethernet using RJ-45
   is available.
 
-.. faq:: Is the WiFi on the Raspberry PI 4B physically available and working?
+.. faq::
+   Is the WiFi on the Raspberry PI 4B physically available and working?
 
   Yes, physically the WiFi is available and working, but not used/managed by the
   NextBox App. If you know what you are doing you can configure and use it, if
   works although being inside the NextBox casing. 
 
-.. faq:: How can I access my NextBox, if I get forwarded to the wrong URL?
+.. faq::
+   How can I access my NextBox, if I get forwarded to the wrong URL?
 
   You should open an incognito window and use: ``https://<your-local-ip>`` or ``http://<your-local-ip>`` 
   keep in mind that using HTTPS once in this browser session will not allow you to use HTTP again in this session,

diff --git a/source/components/nextbox/faq/hardware.rst b/source/components/nextbox/faq/hardware.rst
@@ -4,7 +4,8 @@ Hardware FAQ
 
 
 
-.. faq:: Why must I not connect external hard-drives without an external power-supply to my NextBox?
+.. faq::
+   Why must I not connect external hard-drives without an external power-supply to my NextBox?
 
   The Raspberry Pi 4 Model B can only supply 1.2A of power through USB (see
   `RPi Power Supply <https://www.raspberrypi.com/documentation/computers/raspberry-pi.html#typical-power-requirements>`__).
@@ -13,7 +14,8 @@ Hardware FAQ
   external power supply can lead to an unreliable power supply for the internal
   hard-drive, thus potential data loss.
 
-.. faq:: Where can I find an external hard-drive with its own power supply?
+.. faq::
+   Where can I find an external hard-drive with its own power supply?
 
   The smaller form factors (2.5'' and smaller) for external hard-drives mostly
   come without an additional power supply. For these, *a USB Hub with an
@@ -22,43 +24,50 @@ Hardware FAQ
   thus we recommend external 3.5'' hard-drives, which are nearly always
   externally powered.
 
-.. faq:: Why does my USB device / hub not work, if connected to the NextBox?
+.. faq::
+   Why does my USB device / hub not work, if connected to the NextBox?
 
   There are some devices and especially USB3 hubs that are known to not work properly
   with the Raspberry PI 4B, please see this `USB Documentation`_ from Raspberry.
   On top of that also make sure the USB device is working in general by connecting it 
   to another computer (best case: Linux) and verify that it works.
 
-.. faq:: Why does my hard-drive not show up after plugging it in?
+.. faq::
+   Why does my hard-drive not show up after plugging it in?
 
   Please make sure that you are using one of the supported filesystems (e.g., ext, xfs) and you
   have mounted your hard-drive within *Storage Management*.
 
-.. faq:: Can I generally extend the NextBox using a USB hard-drive?
+.. faq::
+   Can I generally extend the NextBox using a USB hard-drive?
 
   Yes, this is possible, please make sure you are using a hard-drive, which has an external
   power supply. Once connected you can mount the hard-drive using the NextBox *Storage Management* 
   and include it into Nextcloud file-management using the `External storage support`_ app.
 
 
-.. faq:: What functions does the additional "shield" provide?
+.. faq::
+   What functions does the additional "shield" provide?
 
   As of now the shield does provide a :doc:`status LED <../technical/led-colors>`, a hardware button
   to :doc:`factory reset <../technical/factory-reset>` and an additional USB Type-C connector on the 
   same side as the Ethernet port for power supply exclusively.
 
-.. faq:: Is the NextBox hardware extendable/replaceable?
+.. faq::
+   Is the NextBox hardware extendable/replaceable?
 
   Yes, all NextBox components can be easily replaced. None of the components are glued or somehow
   permanently assembled. Using a Phillips screwdriver you can disassemble and re-assemble
   the NextBox easily. Keep in mind that you are doing this at your own risk.
 
-.. faq:: What are the two USB Type-C ports used for?
+.. faq::
+   What are the two USB Type-C ports used for?
 
   Both USB Type-C ports are exclusively for power supply and can not be used for data transfer. 
   Do not connect two power supplies, please just use one of both to power your NextBox.
 
-.. faq:: Which fan should I install?
+.. faq::
+   Which fan should I install?
 
   **There is absolutely no need for a fan, the NextBox is designed to work without an active 
   cooling**. Although if the NextBox is used for additional tasks (it's still a Linux), we have
@@ -67,7 +76,8 @@ Hardware FAQ
   the outputs are not controlled yet by the NextBox daemon, so this is also something you would have
   to do by yourself.
 
-.. faq:: Can I upgrade the NextBox' RAM size?
+.. faq::
+   Can I upgrade the NextBox' RAM size?
 
   No, the Raspberry PI 4B has the RAM component soldered onto the mainboard, thus it cannot be replaced/extended.
 

diff --git a/source/components/nextbox/faq/nextcloud.rst b/source/components/nextbox/faq/nextcloud.rst
@@ -1,52 +1,61 @@
 Nextcloud FAQ
 =============
 
-.. faq:: What to do to run/install/fix Nextcloud App "XYZ"? Why does Nextcloud feature XYZ not work?
+.. faq::
+   What to do to run/install/fix Nextcloud App "XYZ"? Why does Nextcloud feature XYZ not work?
 
   Generally we cannot help in detail for these topics. Nextcloud internals and apps are 
   out-of-scope for the NextBox development as we use the stock Docker images provided by Nextcloud.
   Ultimately, if some NextBox/OS configuration is blocking an app to run properly we for sure will
   look into fixing it.
 
-.. faq:: Why does Nitrokey currently not recommend to use OnlyOffice or Collabora Office on the NextBox?
+.. faq::
+   Why does Nitrokey currently not recommend to use OnlyOffice or Collabora Office on the NextBox?
 
   The state of these Nextcloud apps is not yet mature (for ARM platforms). Although it is (partly)
   possible to install them we do not recommend doing so currently.
 
-.. faq:: Why does updating Nextcloud from inside Nextcloud not work?
+.. faq::
+   Why does updating Nextcloud from inside Nextcloud not work?
 
   The Nextcloud version is rolled out by us. Thus the option to update from inside Nextcloud
   is not working. 
 
-.. faq:: Can I add apps to the Nextcloud instance?
+.. faq::
+   Can I add apps to the Nextcloud instance?
 
   Yes, the Nextcloud app store is available and any app available there can be installed through
   the Nextcloud web frontend.
 
-.. faq:: My Nextcloud instance is stuck in "Maintenance Mode", how can I switch it off?
+.. faq::
+   My Nextcloud instance is stuck in "Maintenance Mode", how can I switch it off?
 
   To *force exit* the Nextcloud "Maintenance Mode", you can push the hardware button **shortly, once**. The
   NextBox will then switch-off the maintenance mode. Please avoid this, if possible.
 
-.. faq:: Why am I getting a permission warning for ``/var/www/html/custom_apps/nextbox`` inside the Nextcloud settings overview?
+.. faq::
+   Why am I getting a permission warning for ``/var/www/html/custom_apps/nextbox`` inside the Nextcloud settings overview?
 
   This is a "feature". The NextBox Nextcloud App is installed on the system
   with the Debian nextbox package. To avoid an accidental deletion of the NextBox 
   Nextcloud App from within the Nextcloud app management, the stated directory 
   can not be written by Nextcloud, this is what Nextcloud is complaining about here.
 
-.. faq:: How can I run Nextcloud's `occ`?
+.. faq::
+   How can I run Nextcloud's `occ`?
 
   As Nextcloud is running inside a Docker container, you need to be root and execute the following:
   ``docker exec -it -u www-data nextbox-compose_app_1 /var/www/html/occ``
 
-.. faq:: What to do about missing php-modules like `imagemagick`?
+.. faq::
+   What to do about missing php-modules like `imagemagick`?
 
   Similar to Apache, PHP is also provided by the Nextcloud container, therefore as we are using
   the stock Nextcloud container this will also only be resolved once this is resolved by
   the Nextcloud Team.
 
-.. faq:: Why is my Nextcloud not loading properly, instead I get a white page and a `.htaccess` error?
+.. faq::
+   Why is my Nextcloud not loading properly, instead I get a white page and a `.htaccess` error?
 
   This usually is an indication that the OS has unmounted/detached the internal
   hard-drive due to an low-power-incident. Please make sure you read and

diff --git a/source/components/nextbox/faq/remote-access.rst b/source/components/nextbox/faq/remote-access.rst
@@ -1,37 +1,42 @@
 Remote Access FAQ
 =================
 
-.. faq:: What is the correct WebDAV URL?
+.. faq::
+   What is the correct WebDAV URL?
 
   The full URL to use for WebDAV is:
   ``https://my.domain.tld/remote.php/webdav/``, there have been reports that
   for native Windows WebDAV you might need:
   ``https://my.domain.tld/remote.php/dav/files/USERNAME`` with *USERNAME* being
   the username you would like to use.
 
-.. faq:: Can I access my Nextcloud instance using WebDAV?
+.. faq::
+   Can I access my Nextcloud instance using WebDAV?
 
   Yes, please see `Nextcloud WebDAV documentation`_ for a complete overview. A
   simple mount for unix-like systems might look like this: ``mount -t davfs
   https://my.domain.tld/remote.php/webdav/ /mnt/target/path`` while making sure
   that the ``davfs2`` package is installed. For Windows please additionally
   read these :doc:`docs <../clients/windows>`.
 
-.. faq:: Why does my Android smartphone's browser not open: ``http://nextbox.local`` 
+.. faq::
+   Why does my Android smartphone's browser not open: ``http://nextbox.local``
 
   As of today the technology needed to use ``.local`` URLs is not supported by various (stock)
   Android browser(s). The mechanism is based on ``mDNS``. One possible workaround is to use a
   3rd party app like BonjourBrowser to discover all mDNS services in your network.
 
-.. faq:: Why does accessing my NextBox using: ``http://nextbox.local`` not work?
+.. faq::
+   Why does accessing my NextBox using: ``http://nextbox.local`` not work?
 
   There are several other reasons why the access using ``http://nextbox.local`` may not work, 
   further known scenarios are: 
 
   * Using a Fritz!Box with the NextBox being connected via a LAN port and the client/browser is
     connected to the network via WiFI (WLAN), the Fritz!Box will block mDNS.
 
-.. faq:: I followed all guides and still cannot acquire the TLS certificate, what can I do? 
+.. faq::
+   I followed all guides and still cannot acquire the TLS certificate, what can I do?
 
   The reason a TLS certificate cannot be acquired is nearly always the fact that
   your NextBox is not reachable from the internet. Make sure you have followed
@@ -42,7 +47,8 @@ Remote Access FAQ
   your router and thus blocking the traffic on port(s) 80 and/or 443. Switch
   them off and retry acquiring your TLS certificate.
 
-.. faq:: Why is my reachability with IPv4 not working? 
+.. faq::
+   Why is my reachability with IPv4 not working?
 
   If you have properly set up :doc:`port forwarding <../remote/port-forwarding>`
   and IPv4 connections (reachability test) are still not working there are good
@@ -56,7 +62,8 @@ Remote Access FAQ
   connections**, which should enable full bi-directional traffic for IPv4 and
   IPv6.
 
-.. faq:: Why do some devices fail to connect for my IPv6 configured NextBox?
+.. faq::
+   Why do some devices fail to connect for my IPv6 configured NextBox?
 
   Sadly, still not all ISPs and mobile-network providers (smartphones) do have
   full IPv6 support activated. This means, if your NextBox is configured for IPv6