#Assets

Assets are files that you have uploaded to MercuryCMS.

#Uploading and Managing Assets

You can upload Assets to MercuryCMS using the Asset Browser. You can drag and drop any files or folders from your desktop and then manage them just like they were local files.

You can use the Asset Browser to upload, delete, rename, and move Assets as well as create Folders to organize them. You can hold Ctrl and click Assets to select multiple and move or delete them all at once. To move Assets to a parent Folder, drag them onto the name of the Folder in the breadcrumb at the top. You can also use shortcuts like pressing Del to delete Assets or F2 to rename.

#File Size

All Assets are provided unmodified. This means if you upload a .png file, that file will not be scaled, compressed, converted, etc. to be optimized for use on a website. Uploading a single 3MB .png file and using it as a background in a css file for a Page can take that Page from being a 15KB 10ms download to a 3MB 1.5s download.

The same is true for CSS files, HTML, etc. Creating style properly within MercuryCMS means the style will benefit from minification and removal of unused code. It also means the style you write for Components will only be included on Pages that use that Component. Uploading a .css file as an Asset and then directly linking to it using a <link> tag means you will not benefit from any of those features which will negatively affect performance, user experience, and page ranking.

Be careful when uploading very large Assets or folders from your desktop with GB of files. This can take a lot of time to upload, so it may be better to upload the files in steps.

After uploading large Assets, you will notice the build time take longer than usual. Once the Asset has been included in the build once successfully, the build time will return to its original speed.

#Uses for Assets

So if you should use Assets for HTML, CSS, JS, or any Media like images, videos, or audio, what should you use Assets for? You should use Assets for any downloadable files, or any files you don't want modified at all.

As a simple example, you may want the information for a property listing to be available for download. You can upload the .pdf to somewhere like /properties/someproperty/Property Information.pdf and then make it available for download on the website using <a href="/properties/someproperty/Property Information.pdf" download>Download Information</a>.

There are also times you will have files required by other websites or services to be available, such as a site verification file at /analyticsverification.json or similar. This is why the Assets you upload aren't all placed in a folder like /assets/ to prevent collisions with generated files.

You may also want to use custom fonts to use in your CSS. You can upload the font files into a folder like /fonts/ and then reference them within your CSS. Be sure to put this CSS in a Layout or Page that actually uses the font to avoid loading it unnecessarily on every Page.

#Build

All uploaded Assets are publicly available, whether you actually use them on any Pages or not. At Build time, all Assets are merged into the website's files. Because of this, don't upload files you don't want people to find and download, and also, don't create files that conflict with existing files.

For example, if you create a Page at the path /about, MercuryCMS will automatically create /about/index.html, which is what is loaded by the user's browser when they visit http://example.com/about. All Assets are merged into the website's files at build time. This means if you create an asset at /about/info.pdf, you will have both index.html and info.pdf within the /about folder.

If you were to put a file called /about/index.html in the Asset Browser, this would conflict with the website's files.

Here's a list of files to avoid overwriting:

<pagePath>/
  index.html
  style.css
  script.js
media/*
index.html
style.css
script.js
sitemap.xml
robots.txt
favicon.png

#Using Assets in Markup and Style

To access files that you have uploaded within your Pages, simply write out the path to the file as you normally would. For example, if you go to the Asset Browser and create a folder called "someapp" and then upload a file called "Installer.zip", you can make a download link for that by writing <a href="/someapp/Installer.zip" download>Download App</a>.

You can also click "Insert Asset Path" above markup in Layouts, Pages, and Components to browse to an Asset using the Asset Browser and have MercuryCMS automatically insert the path for you where your cursor is.

#Asset Fields

You can also allow users of MercuryCMS to upload Assets when creating Collection Entries. For example, let's say you made a Collection called "Applicant". Each Applicant has a Full Name, a Position they can select that they're applying for, and a spot to upload their resume. You can make this an Asset Field.

You can select which Folder you want the files to be uploaded to by writing out the path manually, or by clicking "Browse" and picking a Folder using the Asset Browser. Note that if the folder doesn't exist when the user uploads the file, the path to the Folder will be automatically created.

In the case that an Asset Field is configured to upload files to /somefolder, and the file /somefolder/somefile.docx exists in it, and the user tries to upload a new file called somefile.docx to it, it will not overwrite the existing file. Instead, it will automatically rename the new file /somefolder/somefile_0.docx and continue incrementing each time a new conflicting file is uploaded.

Users can also use an Asset Field to browse for an existing Asset rather than uploading a new one.

For more information about Asset Fields, see Collections.