Skip to content

Commit 7dceda8

Browse files
joshtrichardsjoshtrichards
authored
docs(admin): expand/reorganize mimetypes management chapter
Signed-off-by: Josh <[email protected]>
1 parent 17abd85 commit 7dceda8

File tree

1 file changed

+188
-55
lines changed
  • admin_manual/configuration_mimetypes

1 file changed

+188
-55
lines changed

‎admin_manual/configuration_mimetypes/index.rst‎

Lines changed: 188 additions & 55 deletions
Original file line numberDiff line numberDiff line change
@@ -1,76 +1,209 @@
1-
====================
2-
Mimetypes management
3-
====================
1+
=========
2+
Mimetypes
3+
=========
44

5-
Mimetype aliases
6-
----------------
5+
*Mapping extensions to mimetypes and configuring filetype icons.*
76

8-
Nextcloud allows you to create aliases for mimetypes, so that you can display
9-
custom icons for files. For example, you might want a nice audio icon for audio
10-
files instead of the default file icon.
7+
Extension mapping
8+
-----------------
119

12-
By default Nextcloud is distributed with
13-
``nextcloud/resources/config/mimetypealiases.dist.json``.
14-
Do not modify this file, as it will be replaced when Nextcloud is updated.
15-
Instead, create your own ``nextcloud/config/mimetypealiases.json``
16-
file with your custom aliases. Use the same syntax as in
17-
``nextcloud/resources/config/mimetypealiases.dist.json``.
10+
Administrators can control how file extensions map to mimetypes. This affects how Nextcloud detects files and which icons are shown. For example, mapping the extension ``mp3`` to the mimetype ``audio/mpeg`` causes Nextcloud to use the ``audio`` icon for MP3 files.
1811

19-
Once you have made changes to your ``mimetypealiases.json``, use the ``occ``
20-
command to propagate the changes through the system. This example is for
21-
Ubuntu Linux::
12+
The shipped defaults are in ``resources/config/mimetypemapping.dist.json`` (do not modify).
2213

23-
$ sudo -E -u www-data php occ maintenance:mimetype:update-js
14+
Extension configuration
15+
~~~~~~~~~~~~~~~~~~~~~~~
2416

25-
# you may also need to update the mimetype for existing files, see nextcloud/server#30566
26-
$ sudo -E -u www-data php occ maintenance:mimetype:update-db --repair-filecache
27-
28-
See :doc:`../occ_command` to learn more about ``occ``.
17+
To override defaults, create ``config/mimetypemapping.json`` in your Nextcloud installation's ``config/`` folder. Entries in that file take precedence over the shipped defaults.
2918

30-
Some common mimetypes that may be useful in creating aliases are:
19+
Format: ``mimetypemapping.json`` is a JSON object where each key is a file extension and each value is an array of mimetype strings. The first element is the primary mimetype; an optional second element is a secure alternative (used to avoid potential XSS when exposing a mimetype to clients).
3120

32-
image
33-
Generic image
21+
Example ``mimetypemapping.json``:
3422

35-
image/vector
36-
Vector image
23+
.. code-block:: json
3724
38-
audio
39-
Generic audio file
25+
{
26+
"mp3": ["audio/mpeg"],
27+
"m4a": ["audio/mp4"],
28+
"svg": ["image/svg+xml", "text/plain"],
29+
"md": ["text/markdown"]
30+
}
4031
41-
x-office/document
42-
Word processed document
32+
Icon mapping
33+
------------
4334

44-
x-office/spreadsheet
45-
Spreadsheet
35+
Nextcloud lets you control which icon is shown for a given mimetype. In Nextcloud an "alias" maps a mimetype (for example ``audio/mpeg``) — or a top-level type (for example ``image``) — to an icon identifier (token). The system resolves that token to a concrete icon file. For example, adding ``"audio/mpeg": "audio"`` makes MP3 files use the icon associated with the``audio``token (which resolves to icon file ``core/img/filetypes/audio.svg``). See the Icon configuration section below for how to override the shipped alias defaults and the Icon retrieval section for details on icon file resolution.
4636

47-
x-office/presentation
48-
Presentation
37+
The shipped defaults are in ``resources/config/mimetypealiases.dist.json`` (do not modify).
4938

50-
text
51-
Generic text document
39+
Icon configuration
40+
~~~~~~~~~~~~~~~~~~
5241

53-
text/code
54-
Source code
42+
To override aliases, create ``config/mimetypealiases.json`` in your Nextcloud installation's ``config/`` folder. Entries there override the shipped defaults.
5543

56-
Mimetype mapping
57-
----------------
44+
Important: an alias value is a token (an identifier), not a direct filesystem path. The shipped defaults map full mimetypes to tokens (for example ``"audio/mpeg": "audio"``). The detection code resolves tokens and then looks up icon files under the core filetypes folder (see Icon retrieval). Do not assume that setting an alias value to a path like ``apps/yourapp/img/icons/foo.svg`` will make Detection load that file.
5845

59-
Nextcloud allows administrators to specify the mapping of a file extension to a
60-
mimetype. For example files ending in ``mp3`` map to ``audio/mpeg``. Which
61-
then in turn allows Nextcloud to show the audio icon.
46+
Example ``mimetypealiases.json`` (token-based):
6247

63-
By default Nextcloud comes with ``mimetypemapping.dist.json``. This is a
64-
simple json array.
65-
Administrators should not update this file as it will get replaced on upgrades
66-
of Nextcloud. Instead the file ``mimetypemapping.json`` should be created and
67-
modified, this file has precedence over the shipped file.
48+
.. code-block:: json
49+
50+
{
51+
"audio/mpeg": "audio",
52+
"image/svg+xml": "image/vector",
53+
"application/pdf": "application-pdf"
54+
}
55+
56+
After editing, regenerate client-side icon data (run as the webserver user):
57+
58+
.. code-block:: console
59+
60+
sudo -E -u www-data php occ maintenance:mimetype:update-js
61+
62+
To update icons for existing files, repair the filecache:
63+
64+
.. code-block:: console
65+
66+
sudo -E -u www-data php occ maintenance:mimetype:update-db --repair-filecache
67+
68+
See :doc:`../occ_command` for more about ``occ``.
6869

6970
Icon retrieval
70-
--------------
71+
~~~~~~~~~~~~~~
72+
73+
When resolving an icon for a mimetype, Nextcloud follows this sequence:
74+
75+
1. Load aliases from ``config/mimetypealiases.json`` (overrides) merged over ``resources/config/mimetypealiases.dist.json`` (defaults).
76+
2. If an alias exists for the full mimetype, replace the mimetype with the alias token. Repeat while an alias exists (alias chaining is supported).
77+
3. Convert the resulting token to a filename by replacing ``/`` and ``\`` with ``-`` (for example ``image/vector`` → ``image-vector``).
78+
4. Handle directory tokens specially (``dir``, ``dir-shared``, ``dir-external``).
79+
5. Try to load ``core/img/filetypes/<token-as-filename>.svg`` via the URL generator (this honours theme overrides).
80+
6. If not found and the filename contains a dash, try the top-level part before the dash (``image-vector`` → ``image.svg``).
81+
7. If still not found, fall back to the generic ``core/img/filetypes/file.svg``.
82+
83+
Notes:
84+
- Because Detection resolves tokens and then requests core filetypes images, it does not directly load arbitrary files from other app paths. To provide a custom icon for an alias, install the icon where the URL generator will find it (see Custom icons).
85+
- Run the occ commands above after changes so client-side code picks up the updates.
86+
87+
Default icons
88+
~~~~~~~~~~~~~
89+
90+
The alias values used in the shipped defaults are tokens (often containing slashes). Nextcloud converts these tokens to dashed filenames when looking up SVGs under ``core/img/filetypes/``. If a dashed filename is missing, Nextcloud falls back to the parent token and then to ``file.svg``.
91+
92+
Common tokens used in the defaults include:
93+
94+
* ``image`` — Generic image (core/img/filetypes/image.svg)
95+
* ``image/vector`` — Vector image (lookups to core/img/filetypes/image-vector.svg; falls back to image.svg)
96+
* ``audio`` — Generic audio file (core/img/filetypes/audio.svg)
97+
* ``application-pdf`` — PDF document (core/img/filetypes/application-pdf.svg)
98+
* ``file`` — Generic file (core/img/filetypes/file.svg)
99+
* ``font`` — Font file (core/img/filetypes/font.svg)
100+
* ``mindmap`` — Mindmap file (core/img/filetypes/mindmap.svg)
101+
* ``text`` — Generic text document (core/img/filetypes/text.svg)
102+
* ``text/code`` — Source code (core/img/filetypes/text-code.svg)
103+
* ``video`` — Video file (core/img/filetypes/video.svg)
104+
* ``x-office/document`` — Word processed document (core/img/filetypes/x-office-document.svg)
105+
* ``x-office/drawing`` — (core/img/filetypes/x-office-drawing.svg)
106+
* ``x-office/presentation`` — Presentation (core/img/filetypes/x-office-presentation.svg)
107+
* ``x-office/spreadsheet`` — Spreadsheet (core/img/filetypes/x-office-spreadsheet.svg)
108+
109+
For example the alias token ``image/vector`` will result in a lookup for ``core/img/filetypes/image-vector.svg``; if that file does not exist Nextcloud falls back to ``core/img/filetypes/image.svg`` and then to the generic ``core/img/filetypes/file.svg``.
110+
111+
Custom icons
112+
~~~~~~~~~~~~
113+
114+
1. Create the icon file
115+
- Prefer SVG (scalable vector). Provide a PNG fallback if desired/needed as a fallback (for older browsers or tooling).
116+
- SVGs should be self-contained (no external fonts, scripts or linked assets).
117+
- For additional guidance, see the *Icon file guidance* section in this chapter's appendix.
118+
119+
2. Install the file where the URL generator will find it for core filetypes lookups:
120+
- Recommended (upgrade-safe): ``themes/<yourtheme>/core/img/filetypes/<token>.svg``
121+
- Fallback (not upgrade-safe): ``core/img/filetypes/<token>.svg``
122+
123+
Rationale: Detection resolves aliases to a token and requests ``core`` + ``filetypes/<token>.svg``. The URL generator checks theme overrides (``themes/<theme>/core/img/...``) first, then core. Placing files in these locations ensures Detection finds them without code changes.
124+
125+
Important: placing an icon under ``apps/<yourapp>/img/...`` will not be found by Detection's mimeTypeIcon path, because Detection requests the icon via ``imagePath('core', 'filetypes/<...>.svg')``.
126+
127+
3. Add or update an alias in ``config/mimetypealiases.json`` mapping the mimetype (or top-level type) to the token you used as the filename, for example:
128+
129+
.. code-block:: json
130+
131+
{
132+
"audio/mpeg": "audio",
133+
"image/svg+xml": "image/vector",
134+
"application/vnd.custom.foo": "custom-foo"
135+
}
136+
137+
Then install the file(s) as:
138+
139+
- ``themes/mytheme/core/img/filetypes/custom-foo.svg``
140+
141+
After editing run:
142+
143+
.. code-block:: console
144+
145+
sudo -E -u www-data php occ maintenance:mimetype:update-js
146+
147+
and, if needed:
148+
149+
.. code-block:: console
150+
151+
sudo -E -u www-data php occ maintenance:mimetype:update-db --repair-filecache
152+
153+
Troubleshooting
154+
---------------
155+
156+
* Validate your JSON (use a JSON validator).
157+
* Ensure files in ``config/`` and installed icon files are readable by the webserver user.
158+
* Clear browser cache; client-side JS may be cached.
159+
* Test custom icon URLs in a browser to confirm they are served.
160+
* If an alias references a missing file, Nextcloud falls back to the parent token icon or the generic icon.
161+
162+
----
163+
164+
Icon file guidance
165+
------------------
166+
167+
- Format
168+
- Prefer SVG (scalable vector). Provide a PNG fallback only if needed for legacy clients.
169+
- SVGs should be self-contained (no external fonts, scripts or linked assets).
170+
171+
- Match the existing core set
172+
- Core filetype icons in Nextcloud currently use either ``viewBox="0 0 16 16"`` or ``viewBox="0 0 24 24"`` (some with width/height).
173+
- To ensure consistent rendering with shipped icons, match the viewBox used by your installation's core icons and just generally try to match the existing set for consistency.
174+
175+
- File naming and fallbacks
176+
- Name files to match the alias token converted to a dashed filename, e.g. alias token ``image/vector`` → ``image-vector.svg``.
177+
- Provide a PNG fallback only if required: ``<token>.png`` (same basename as the SVG). Nextcloud will use the PNG only when no SVG exists in the theme/core lookup.
178+
- Use lowercase, dash-separated names (no spaces).
179+
180+
- Raster (PNG) sizes (if providing PNG fallbacks)
181+
- Provide at least a 1× size equivalent to the SVG canvas.
182+
- Optimize PNGs to keep file size small.
183+
184+
- Accessibility & semantics
185+
- Filetype icons are usually decorative — avoid embedding title/desc that duplicate surrounding text. The application UI should mark decorative icons as aria-hidden when appropriate.
186+
- Ensure transparent background (no opaque white rectangle).
187+
188+
- Performance & size
189+
- Keep SVGs simple and small (remove metadata and editor cruft).
190+
- Avoid very large path counts and embedded images.
191+
192+
- Testing
193+
- Place the icon in a theme location (recommended): ``themes/<yourtheme>/core/img/filetypes/<token>.svg``.
194+
- Run: ``sudo -E -u www-data php occ maintenance:mimetype:update-js``
195+
- Clear browser cache and verify the icon URL in the browser (confirm the file serves correctly).
196+
- If the dashed filename is missing, Nextcloud will fall back to the parent token icon (e.g. ``image-vector`` → ``image.svg``) then to ``core/img/filetypes/file.svg``. Test these fallbacks.
197+
198+
Minimal SVG template (copy/paste)
199+
.. code-block:: xml
71200
72-
When an icon is retrieved for a mimetype, if the full mimetype cannot be found,
73-
the search will fallback to looking for the part before the slash. Given a file
74-
with the mimetype 'image/my-custom-image', if no icon exists for the full
75-
mimetype, the icon for 'image' will be used instead. This allows specialised
76-
mimetypes to fallback to generic icons when the relevant icons are unavailable.
201+
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" width="64" height="64" role="img" aria-hidden="true">
202+
<!-- Use fill="currentColor" if you want the icon to inherit UI color -->
203+
<g fill="currentColor" stroke="none">
204+
<!-- example: simple document symbol centered with padding -->
205+
<rect x="12" y="8" width="40" height="48" rx="3" />
206+
<rect x="18" y="18" width="28" height="6" />
207+
<rect x="18" y="28" width="28" height="6" />
208+
</g>
209+
</svg>

0 commit comments

Comments
 (0)