From bda9cc25f36c2b8bb98807c6e5b0643ddc400d19 Mon Sep 17 00:00:00 2001 From: Josh Date: Sat, 14 Nov 2026 11:23:10 -0500 Subject: [PATCH] docs(admin): improve MIME type customization guidance Improve explanations of extension mappings versus aliases, including their configuration files and maintenance commands. Document MIME type display names. Clarify secure MIME alternatives which was too vague previously to be actionable. Improve explanation of icon selection and fallback, and the limits of custom icon support. Move and qualify the database repair guidance and command instructions. Add a mapping example (AMR audio). Assisted-by: Copilot:gpt-6.1-terra Signed-off-by: Josh --- .../configuration_mimetypes/index.rst | 228 ++++++++++++++---- 1 file changed, 175 insertions(+), 53 deletions(-) diff --git a/admin_manual/configuration_mimetypes/index.rst b/admin_manual/configuration_mimetypes/index.rst index 91d7a4d17d3..73cf4198bd8 100644 --- a/admin_manual/configuration_mimetypes/index.rst +++ b/admin_manual/configuration_mimetypes/index.rst @@ -1,76 +1,198 @@ -==================== -Mimetypes management -==================== +============================================= +Customizing MIME Types, Extensions, and Icons +============================================= -Mimetype aliases ----------------- +MIME types help Nextcloud know how to handle and present files. Nextcloud comes +with definitions for many common and less common file types. You can customize +MIME types, file extensions, and icon associations to suit the file types used +in your organization. -Nextcloud allows you to create aliases for mimetypes, so that you can display -custom icons for files. For example, you might want a nice audio icon for audio -files instead of the default file icon. +For example, you can associate a file extension with a MIME type, choose an +icon category for a MIME type, or provide a descriptive human-readable label. -By default Nextcloud is distributed with -``nextcloud/resources/config/mimetypealiases.dist.json``. -Do not modify this file, as it will be replaced when Nextcloud is updated. -Instead, create your own ``nextcloud/config/mimetypealiases.json`` -file with your custom aliases. Use the same syntax as in -``nextcloud/resources/config/mimetypealiases.dist.json``. +In Nextcloud: -Once you have made changes to your ``mimetypealiases.json``, use the ``occ`` -command to propagate the changes through the system. This example is for -Ubuntu Linux:: +- a MIME type *mapping* associates a file extension with a MIME type identifier. +- a MIME type *alias* associates a MIME type with an icon category or another alias. +- a MIME type *name* associates a MIME type with a human-readable display name + (such as "PDF document", rather than the MIME type identifier ``application/pdf``). - $ sudo -E -u www-data php occ maintenance:mimetype:update-js +Mappings affect MIME type detection. Aliases and names affect presentation and +some user interface behavior; they do not change the file's detected MIME type. - # you may also need to update the mimetype for existing files, see nextcloud/server#30566 - $ sudo -E -u www-data php occ maintenance:mimetype:update-db --repair-filecache +The default baseline definitions are in ``resources/config/``: -See :doc:`../occ_command` to learn more about ``occ``. +- ``mimetypemapping.dist.json`` +- ``mimetypealiases.dist.json`` +- ``mimetypenames.dist.json`` -Some common mimetypes that may be useful in creating aliases are: +Do not edit the ``resources/config/*.dist.json`` files: they are overwritten +when Nextcloud is updated. Instead, create corresponding custom JSON files in +``config/``. Custom entries override matching defaults; other defaults remain +in effect. -image - Generic image +After changing a custom definition, run the ``occ`` command shown in the +corresponding section. The examples below are for Ubuntu Linux. Run them from +the Nextcloud installation directory as the HTTP user; see +:doc:`../occ_command` for more information. -image/vector - Vector image +MIME type mapping +----------------- -audio - Generic audio file +Mappings associate file extensions with MIME types. -x-office/document - Word processed document +.. note:: A mapping identifies the file type; it does not itself add support for + opening a given file type. -x-office/spreadsheet - Spreadsheet +Create ``config/mimetypemapping.json`` as a JSON object. The keys are +lowercase extensions without a leading dot, and each value is an array whose +first element is the MIME type. For example:: -x-office/presentation - Presentation + { + "amr": ["audio/amr"], + "adoc": ["text/asciidoc", "text/plain"] + } -text - Generic text document +The first value is the file's MIME type. An optional second value specifies a +safer alternative for contexts where Nextcloud uses a secure MIME type, +including WebDAV file responses, to reduce the risk of active content being +executed by a browser. For example, the default mapping +``"html": ["text/html", "text/plain"]`` identifies an HTML file as +``text/html`` but can serve it as plain text. This does not sanitize or change +the file. -text/code - Source code +If the second value is omitted, the first is used as the secure type. For formats +that can contain active content, consider an appropriate alternative such as +``text/plain`` for text or ``application/octet-stream`` for binary data. Retain shipped +alternatives unless you understand the consequences. Mappings that share a MIME +type should use consistent alternatives. See the shipped +``mimetypemapping.dist.json`` for examples. -Mimetype mapping ----------------- +Filename-based detection uses the final extension, ignoring its case. When +using combined filename and content detection, Nextcloud attempts content +detection if the filename yields ``application/octet-stream``. -Nextcloud allows administrators to specify the mapping of a file extension to a -mimetype. For example files ending in ``mp3`` map to ``audio/mpeg``. Which -then in turn allows Nextcloud to show the audio icon. +After changing mappings, update the mimetype database and file cache:: -By default Nextcloud comes with ``mimetypemapping.dist.json``. This is a -simple json array. -Administrators should not update this file as it will get replaced on upgrades -of Nextcloud. Instead the file ``mimetypemapping.json`` should be created and -modified, this file has precedence over the shipped file. + sudo -E -u www-data php occ maintenance:mimetype:update-db --repair-filecache + +Without ``--repair-filecache``, the command updates cached files only for +mimetypes newly added to the database. With the option, it processes all +configured mappings and updates matching cached files, not just files affected +by the changed mapping. + +MIME type aliases +----------------- + +Aliases let multiple MIME types use the same icon category. They may also +affect the Files app's type filter. An alias does not change the file's MIME type. + +Create ``config/mimetypealiases.json`` as a JSON object. For example, to use +the image icon instead of the default whiteboard icon for Excalidraw files:: + + { + "application/vnd.excalidraw+json": "image" + } + +The values are icon categories or other aliases; they are not necessarily +standard MIME types. Aliases can reference other aliases, provided they do +not form a circular dependency. See +``resources/config/mimetypealiases.dist.json`` for the defaults. + +After changing aliases, regenerate the client-side mimetype list:: + + sudo -E -u www-data php occ maintenance:mimetype:update-js + +Aliases select from available icons; they do not create new icons. + +Some available icon categories are: + +``file`` + Generic file + +``image``, ``audio``, ``video`` + Images, audio, and video + +``text``, ``text/code`` + Text and source code + +``text/calendar``, ``text/vcard`` + Calendar and contact files + +``x-office/document``, ``x-office/spreadsheet`` + Documents and spreadsheets + +``x-office/presentation``, ``x-office/drawing`` + Presentations and drawings + +``x-office/form``, ``x-office/form-template`` + Forms and form templates + +``font``, ``link``, ``location``, ``mindmap``, ``whiteboard`` + Fonts, links, location data, mind maps, and whiteboards + +``package/x-generic`` + Archives and packages + +This list is not exhaustive. See ``core/img/filetypes/`` for the +icons shipped with your installation. Icon filenames replace slashes with +hyphens; for example, ``x-office/drawing`` uses ``x-office-drawing.svg``. +Aliases are resolved before looking up an icon. + +.. note:: Custom file-type icons can be supplied through a legacy custom theme, however, + this approach is deprecated. The Theming app's branding settings do not + currently provide an interface for adding them. + +MIME type names +--------------- + +To customize human-readable file type names, create ``config/mimetypenames.json`` +as a JSON object mapping mimetypes to names. For example:: + + { + "application/x-example": "Example document" + } + +See ``resources/config/mimetypenames.dist.json`` for the defaults. After changing +names, regenerate the client-side mimetype list:: + + sudo -E -u www-data php occ maintenance:mimetype:update-js Icon retrieval -------------- -When an icon is retrieved for a mimetype, if the full mimetype cannot be found, -the search will fallback to looking for the part before the slash. Given a file -with the mimetype 'image/my-custom-image', if no icon exists for the full -mimetype, the icon for 'image' will be used instead. This allows specialised -mimetypes to fallback to generic icons when the relevant icons are unavailable. +For icon lookup, Nextcloud first resolves any aliases, then looks for an icon +for the resulting value. If no specific icon exists, it will use a more general +one. For example, ``image/my-custom-image`` can fall back to the ``image`` +icon. If no matching icon is available, the generic ``file`` icon is used. + +Example: AMR audio (``audio/amr``) +---------------------------------- + +For example, *AMR audio* is an audio compression codec used for speech +recordings. It uses a dedicated file format (``.amr``). At the time of this +writing, the default mappings do not include ``.amr``, so you would need to +add it. + +Place the following in ``config/mimetypemapping.json``:: + + { + "amr": ["audio/amr"] + } + +.. tip:: If the ``config/mimetypemapping.json`` file already exists, an app or + another administrator may have added a custom MIME type mapping. If so, + add the ``"amr"`` entry to its existing JSON object (the part between + the ``{ ... }``) instead of replacing the entire contents of the file. + +This maps ``.amr`` files to the RFC-registered ``audio/AMR`` media type. No alias +is needed for the generic audio icon to be utilized for this newly added MIME type: +icon lookup falls back from ``audio/amr`` to the broader ``audio`` icon when no +more specific icon or alias applies. + +Update the mimetype database and existing file cache entries:: + + sudo -E -u www-data php occ maintenance:mimetype:update-db --repair-filecache + +.. note:: The mapping identifies the file type; it does not itself add playback + support.