Favicon Studio Plugin

Favicon Studio creates the main favicon formats for a Publii website from one PNG, JPEG, WebP, or SVG image. It provides separate settings for browser, Apple touch, standard web app, and maskable icons, then adds the generated files and metadata during Publii rendering.

Image processing takes place on your computer inside Publii. The plugin does not upload the source image to an external favicon generator or require a native image-processing dependency.

Installing and Activating Favicon Studio

Download Favicon Studio from the Publii Marketplace.
Open the three-dot application menu in Publii and select Plugins.
Select Install Plugin and choose the downloaded plugin package.
Open the website that will use the favicon set.
Go to Tools & Plugins, find Favicon Studio, and enable its switch.
Click the plugin card to open the editor.

Publii enables plugins separately for each website. Creating a favicon set for one site does not change the settings of another site.

See the Publii plugin guide for general installation and activation instructions.

Preparing the Master Image

Favicon Studio accepts PNG, JPEG, WebP, and SVG files. A square image measuring at least 512 × 512 pixels gives the most predictable result, although the plugin can center and contain artwork with other proportions.

Maximum file size - 15 MB.
Maximum raster dimensions - 8192 pixels on either side.
Transparency - Available with suitable PNG, WebP, and SVG sources. JPEG files do not contain transparency.
Recommended vector source - A self-contained SVG with a valid viewBox and text converted to outlines.

Small raster images can be accepted, but they do not contain enough source detail for a sharp 512 × 512 pixel web app icon. Increasing the dimensions of a small bitmap before upload does not restore missing detail.

SVG fonts: Convert text to outlines before export. Favicon Studio does not load external font files, and another computer may not have the font used by the original document.

Creating and Publishing a Favicon Set

Drag an image onto the Master image area or use the file control to choose one.
Review the Browser, Apple touch, Web app, and Maskable previews.
Select each preview and adjust its settings in the panel below.
Review the Site identity and Advanced sections.
Select Generate & save favicon set.
Create a Publii Preview or publish the website.

Saving changes: Selecting an image or changing a control updates the previews, but it does not update the saved production set. Use Generate & save favicon set after every change that should appear on the generated website.

The button briefly changes to Generated & saved after the source, settings, and generated assets have been stored. Publii writes the physical files into the rendered website during the next Preview or Publish operation.

Generated Files

A PNG, JPEG, or WebP source creates eight files:

favicon.ico - A multi-size ICO containing 16 × 16, 32 × 32, and 48 × 48 pixel browser icons.
favicon-96x96.png - A 96 × 96 pixel browser icon.
apple-touch-icon.png - A 180 × 180 pixel Apple touch icon.
web-app-manifest-192x192.png - A 192 × 192 pixel standard web app icon.
web-app-manifest-512x512.png - A 512 × 512 pixel standard web app icon.
web-app-manifest-192x192-maskable.png - A 192 × 192 pixel maskable web app icon.
web-app-manifest-512x512-maskable.png - A 512 × 512 pixel maskable web app icon.
site.webmanifest - The web app manifest that connects the app identity, icons, colors, start address, scope, and display mode.

An SVG source also creates favicon.svg, bringing the set to nine files. Raster sources do not produce an SVG wrapper.

Favicon Studio Plugin Options

The four square previews are also navigation controls. Select a preview to open the related settings. The pixel values below the previews show the files produced for that variant; they do not change when you move an artwork-size slider.

Master Image

Choose file - Selects the source PNG, JPEG, WebP, or SVG image.
Replace - Selects another source while retaining the current variant settings.
Remove - Clears the stored source and generated bundle. The plugin stops adding favicon files and markup on subsequent builds until a new set is generated.

Removing the source does not reset every control to its original default. This lets you upload another image without rebuilding the configuration from the beginning.

Browser

The Browser settings produce the ICO entries, the 96 × 96 pixel PNG, and the optional SVG favicon.

Artwork size - Sets the maximum area occupied by the source from 35% to 100%. The default is 82%, which keeps small favicons legible while leaving a narrow margin.
Transparent background - Keeps the background transparent. This option is enabled by default.
Background - Sets a solid browser-icon background when transparency is disabled.
Corner radius - Rounds a solid browser background from 0% to 50%. The default for a new configuration is 22%. The control is hidden while the background is transparent.

The Browser settings also control the appearance of favicon.svg when the master image is SVG.

Apple Touch

The Apple touch settings produce apple-touch-icon.png at 180 × 180 pixels.

Artwork size - Sets the source size from 35% to 100%. The default is 72%.
Background - Sets the solid background placed behind the artwork.

Favicon Studio generates a square file without baking a platform-specific rounded shape into it. iOS applies the appropriate mask when it displays the icon. Apple documents the 180 × 180 pixel touch icon and app-title metadata in its web application configuration guide.

Web App

The Web app settings produce the 192 × 192 and 512 × 512 pixel icons whose manifest purpose is any.

Artwork size - Sets the source size from 35% to 100%. The default is 72%.
Transparent background - Keeps the standard web app icon transparent. This option is enabled by default.
Icon background - Sets a solid icon background when transparency is disabled. The control is hidden while transparency is enabled.
Launch screen background - Sets the manifest background_color. The preview uses this color around a transparent standard web app icon. The initial value is #70757d.
Browser theme - Sets the manifest theme_color and, when no other component supplies one, the page's <meta name="theme-color"> value. The default is #ffffff.

The launch-screen background is a color value, not a generated startup image. Browsers decide how the manifest color is used during installation and launch.

Maskable

The Maskable settings produce separate 192 × 192 and 512 × 512 pixel icons with purpose: "maskable".

Full-bleed source - Fills the entire square with a prepared maskable source. The plugin uses a cover fit and crops the image when its proportions do not match the square. The option is disabled by default.
Artwork size - Adjusts contained artwork from 35% to 80%. The default is 58%. This control is hidden when Full-bleed source is enabled.
Icon background - Sets the solid color behind the maskable artwork.

The dashed circle in the preview represents the minimum safe area. The Web Application Manifest specification defines it as a centered circle with a radius equal to 40% of the icon size. Content outside this circle can be removed by a platform mask. See the W3C icon mask and safe-zone specification.

In the default contained mode, Favicon Studio adjusts the actual scale for the source proportions so the artwork fits within that circle. The displayed percentage controls how much of the available safe scale is used; it is not a literal percentage of the full square. Full-bleed mode is intended for an icon whose background already reaches every edge and whose important content remains inside the safe area.

Site Identity

The manifest normally uses the website name and description from Publii's Site settings. Leave both override fields empty for this behavior.

App name override - Replaces the manifest name and the Apple web app title. The field accepts up to 45 characters.
Short name override - Replaces the manifest short_name. The field accepts up to 15 characters.

If the short-name override is empty, the manifest uses the resolved app name. The description always comes from Publii's Site settings when one is available; Favicon Studio does not provide a separate description override.

Advanced

Cache-busting suffix - Adds a revision query such as ?v=… to icon and manifest URLs. The option is disabled by default.

Favicon Studio creates a new revision value each time you select Generate & save favicon set. When cache busting is enabled, the revision is added to the URLs in the page head and to icon URLs inside the manifest. It does not rename the generated files.

Enable the suffix when browsers continue to display an older published icon. After changing this option, generate and save the set again, then create a new Preview or publish the site.

Automatic Background Selection

When a master image is first loaded, Favicon Studio samples its visible pixels and compares them with three neutral backgrounds: #70757d, #f6f6f9, and #313339. It chooses the candidate that provides the strongest result across the sampled artwork.

The selected candidate is assigned to the Browser, Apple touch, Web app icon, and Maskable backgrounds that remain in automatic mode. Selecting a color for a variant changes that background to manual mode. A manually selected color is retained when you replace the master image, while automatically managed backgrounds are evaluated again.

The automatic process does not change the launch-screen background or Browser theme color. These values remain under direct user control.

Color Pickers and Contrast Warnings

Select a color value to open its picker. The format control cycles between HEX, RGB, and HSL fields. Saved colors are normalized to six-digit hexadecimal values.

Favicon Studio samples the rendered artwork and displays a warning when it may blend into a selected background. An exclamation badge identifies each affected preview. The check runs after a short pause in color adjustment so the live preview remains responsive.

A transparent Browser icon has no fixed background, so the plugin does not show a background-contrast warning for it.
A transparent standard Web app icon is checked against the selected launch-screen background shown in its preview.
Full-bleed Maskable artwork is not checked because the source itself covers the icon surface.
A warning does not block generation or saving.

The contrast check is an editing aid for icon visibility. It is not a WCAG conformance test, and operating systems can display transparent icons against surfaces that differ from the preview.

SVG Requirements and Processing

SVG sources must be self-contained. Favicon Studio parses and sanitizes the document before using it.

Scripts, embedded HTML, iframes, objects, audio, video, canvas elements, and SVG animation elements are removed.
Event-handler attributes such as onclick are removed.
Document type and entity declarations are rejected.
External images, stylesheets, imported CSS, and web fonts are rejected.
Internal fragment references and embedded raster images stored as supported data URLs are allowed.
If the document has no viewBox, the plugin derives one from numeric width and height values. Exporting a correct viewBox from the design application remains preferable.

The sanitized SVG is retained as vector artwork for favicon.svg. ICO, Apple touch, standard web app, and maskable files are rendered separately as PNG data at their required sizes.

Raster Rendering and Image Quality

PNG, JPEG, and WebP uploads remain raster sources. Favicon Studio does not convert them to WebP or place them inside an SVG wrapper.

Each output is rendered from the retained source. The plugin uses high-quality canvas smoothing, renders at up to four times the target dimensions where the source permits it, and downsamples progressively. The working canvas is capped at 2048 pixels to control memory use.

A large, clean source still determines the available detail. Fine lines and small text can disappear in a 16 × 16 pixel favicon even when the master image is sharp. Check the Browser preview and simplify artwork that does not remain recognizable at small sizes.

Web Manifest Contents and Paths

Favicon Studio writes these members to site.webmanifest:

name and short_name from Publii's site identity or the plugin overrides;
description from Publii's Site settings when a description is present;
start_url and scope pointing to the generated site's root;
standard and maskable icon entries at 192 × 192 and 512 × 512 pixels;
theme_color from Browser theme;
background_color from Launch screen background;
display set to standalone.

The manifest and its icons are published together in media/plugins/faviconStudio. Icon entries therefore use filenames without a longer directory path. The relative ../../../ values used for start_url and scope resolve from the plugin media directory to the root of the Publii website, including sites published in a subdirectory.

Favicon Studio does not add an explicit manifest id. Under the manifest processing rules, the browser derives the application identity from the start URL when id is absent. See the Web Application Manifest specification for the current processing rules.

A generated manifest with no name overrides and cache busting disabled has this structure:

{
  "name": "Example Website",
  "short_name": "Example Website",
  "description": "Example website description.",
  "start_url": "../../../",
  "scope": "../../../",
  "icons": [
    {
      "src": "web-app-manifest-192x192.png",
      "sizes": "192x192",
      "type": "image/png",
      "purpose": "any"
    },
    {
      "src": "web-app-manifest-512x512.png",
      "sizes": "512x512",
      "type": "image/png",
      "purpose": "any"
    },
    {
      "src": "web-app-manifest-192x192-maskable.png",
      "sizes": "192x192",
      "type": "image/png",
      "purpose": "maskable"
    },
    {
      "src": "web-app-manifest-512x512-maskable.png",
      "sizes": "512x512",
      "type": "image/png",
      "purpose": "maskable"
    }
  ],
  "theme_color": "#ffffff",
  "background_color": "#70757d",
  "display": "standalone"
}

The names and description in this example are replaced during rendering with the current values from the site and plugin settings.

How Favicon Markup Is Added

During a Publii Preview or Publish operation, Favicon Studio performs the following work:

The beforeRender event writes the saved assets into the site's plugin media directory.
The globalContext modifier suppresses the favicon selected in the active theme while a Favicon Studio set is active.
The native publiiHead insertion adds the theme color, browser icons, Apple touch icon, Apple web app title, and manifest link.
The final htmlOutput modifier removes competing favicon and manifest tags and prevents duplicate Favicon Studio blocks.

The cleanup covers icon, shortcut icon, Apple touch icon, Apple touch precomposed, mask icon, manifest, and Apple web app title tags. It leaves stylesheets, canonical links, scripts, and unrelated metadata in place.

If a theme or another plugin already adds a theme-color meta element, Favicon Studio preserves the existing value and omits its own. This allows plugins that provide separate light and dark theme colors to keep control of those tags.

The final HTML pass also provides a fallback for a theme that contains hard-coded favicon markup or does not place the Publii insertion where expected. It adds the Favicon Studio block before the first script, style, or noscript element in the head, or before the closing head tag when no such element exists.

With an SVG master image and no external theme color, the generated block contains these elements:

<meta name="theme-color" content="#ffffff">
<link rel="icon" type="image/png" href="https://example.com/media/plugins/faviconStudio/favicon-96x96.png" sizes="96x96">
<link rel="icon" type="image/svg+xml" href="https://example.com/media/plugins/faviconStudio/favicon.svg" sizes="any">
<link rel="icon" href="https://example.com/media/plugins/faviconStudio/favicon.ico">
<link rel="apple-touch-icon" sizes="180x180" href="https://example.com/media/plugins/faviconStudio/apple-touch-icon.png">
<meta name="apple-mobile-web-app-title" content="Example Website">
<link rel="manifest" href="https://example.com/media/plugins/faviconStudio/site.webmanifest">

The SVG link is omitted for a raster source. Revision queries are appended to these URLs when cache busting is enabled.

Local Storage and Publishing

The source image, settings, and generated asset bundle are stored per site in:

input/config/plugins/faviconStudio/favicon-studio.json

During rendering, Publii creates the static files under:

input/media/plugins/faviconStudio

The generated website references the corresponding public media/plugins/faviconStudio directory. Favicon Studio does not make a network request while reading or processing the master image.

Replacing or Removing the Source

Replace loads another master image and keeps the current variant settings. Automatically managed icon backgrounds are recalculated for the replacement; backgrounds that you selected manually remain unchanged.

Replacing an SVG with a raster source removes favicon.svg from the newly saved set and from generated head markup. Replacing a raster source with an SVG adds the vector file after the next Generate and save operation.

Remove clears the saved source and generated bundle without a confirmation dialog. On subsequent builds, the plugin stops suppressing the theme favicon and no longer inserts Favicon Studio markup.

Removing or replacing a set does not guarantee that an older, unreferenced file is deleted immediately from an already published server. Publii and the selected synchronization method control remote-file cleanup. The old asset is no longer referenced by newly generated pages.

Scope of the Plugin

Favicon Studio generates the main browser, Apple touch, and web app icon files described above. It does not generate a Safari pinned-tab mask-icon, a Windows browserconfig.xml file, platform-specific startup images, manifest screenshots, or a service worker.

An existing rel="mask-icon" tag is treated as competing favicon markup and removed while a Favicon Studio set is active. The plugin does not replace it with a new pinned-tab file.

The web manifest and icons provide web app identity and presentation data. They do not add offline caching or turn the website into a complete Progressive Web App by themselves.

Troubleshooting

Generate & save favicon set is disabled - Choose a valid master image first. The button also remains disabled while the plugin is processing or saving a file.
The editor says that changes are not saved - Select Generate & save favicon set, then create a new Preview or publish the site.
The image is rejected - Confirm that it is a PNG, JPEG, WebP, or SVG file no larger than 15 MB. Raster images cannot exceed 8192 pixels on either side.
An SVG cannot be processed - Remove scripts, external images, imported styles, external fonts, document declarations, and unsupported embedded content. Convert text to outlines and export a self-contained SVG.
Text is missing from the generated SVG - Convert the text to vector outlines before upload. The plugin does not load an external font referenced by the source document.
A white or dark logo is difficult to see - Choose a contrasting solid background for that variant. Use the warning badge to identify the affected preview.
A transparent Web app preview appears on a color - The checkerboard shows transparency inside the icon. The surrounding color represents the manifest launch-screen background used to evaluate the preview.
Maskable artwork is cropped - Disable Full-bleed source for ordinary logo artwork. Keep the important content inside the dashed safe-area circle.
Full-bleed artwork leaves unexpected edges - Use a source whose background reaches every edge. Non-square full-bleed sources are centered and cropped to cover the output square.
The browser still shows an older favicon - Enable Cache-busting suffix, generate and save the set again, publish the site, and reload the public page. Browser and intermediary caches can retain favicon files for an extended period.
The theme favicon still appears - Confirm that Favicon Studio is enabled for the current site, a set has been generated and saved, and the website has been regenerated.
The selected Browser theme color is not used - Inspect the generated head for another theme-color element. Favicon Studio gives an existing theme or plugin value priority to avoid overwriting it.
The manifest contains the wrong app name - Check the website name under Publii's Site settings and the two Site identity overrides in Favicon Studio. Generate and publish the set again after changing either source.
The manifest icon entries contain filenames without folders - This is expected. The icons and site.webmanifest are stored in the same plugin media directory, so the paths are relative to the manifest file.
Old favicon files still exist after Remove - Newly generated pages no longer reference them. Remote deletion depends on the Publii synchronization method and server state.