Skip to content

docs(admin): clarify MIME type customization #16053

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
joshtrichards wants to merge 1 commit into
base: master
Choose a base branch
from
Open

docs(admin): clarify MIME type customization #16053

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
228 changes: 175 additions & 53 deletions admin_manual/configuration_mimetypes/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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

Check failure on line 183 in admin_manual/configuration_mimetypes/index.rst

View workflow job for this annotation

GitHub Actions / Lint RST files 

trailing whitespace (trailing-whitespace)
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.
Loading