How Do I Manage Documents in the Media Library?

Documents like PDFs and XLS files can be uploaded and stored in the Media Library as individual files.

 When you go into the Media Library, you can easily locate Documents that have been uploaded by selecting 'Document' within the 'Media type' dropdown box.

To delete a document that you've uploaded to your site's Media Library, select the arrow icon located to the right of the edit button. This will show a dropdown where you can select the delete button.

Managing documents in the media library

When a document is uploaded to the Media Library, it is assigned a unique media ID. This ID helps the platform identify and display the document whenever it’s needed.

For example, you may want to create a Listing Page to organize and display your uploaded documents.

Learn about Listing Pages

Learn about Listing Pages of Docs

Can you change the date for files uploaded in the Media Library?

Yes, you can change the date shown for a document by updating the following fields:

  • Display Date – This controls the date shown under the document title on the listing page.
  • Authored Information – By updating this field, you can sort and search for documents by a specific year.
File info for documents in the media library

Benefits of managing documents through the Media Library

Uploading documents directly to the Media Library makes it easier to manage and update them. Instead of looking for outdated links, you can update the file in one place. Changes will automatically apply across the entire site.

Check your document file name before uploading

Before uploading a document, ensure the file name follows best practices. Your department may have its own naming guidelines, or you can follow the State of Iowa File Naming Conventions.  

Here are some tips:

  • Length: Keep file names under 31 characters to avoid errors and improve readability.
  • Punctuation: Avoid spaces, periods, or underscores. Use hyphens instead.
  • Description: Use clear, descriptive file names that explain the file’s content.
  • Date Format: Use YYYYMMDD for chronological organization. For timestamps, use YYYYMMDDThhmm.

Example of a good document naming convention:

  • ProjectName-DocumentType-Date
    (e.g., CohortPlan-Schedule-20240511)

Internal document embedding and linking best practices

When linking to a document in the Media Library, use the document’s name instead of its full URL. Full URLs are only used when linking to an external page (one not on your site). Using a full URL (e.g., "https://..." or www.xxx) creates an absolute link, which may result in broken links and negatively impact your website's accessibility score.

You can spot an incorrect internal link if you see "No Results" in the dropdown when selecting the document.

When to use a full URL

The full URL should only be used for external links, not for documents stored within the site.

Incorrect Example:

  • Linking to internal documents with a full URL can cause "No results - No content suggestion found" to appear.
Bad URL example
1

Upload and embed a document

To upload a document to the Media Library:

  1. Click the Content link dropdown.
  2. Go to the Media link.
  3. Select Add Media, then choose Document from the sidebar dropdown.
  4. Upload the document by selecting the Upload File button in the new window.

Tip: Use an easy-to-understand naming convention to ensure the document can be easily found within the Media Library by your team and users.

Content menu add media to library screenshot

How to add content to the Media Library.

Embedding a document on a Basic Page

Once a document is uploaded, you can embed it into a Basic Page by using the Document button in the WYSIWYG editor, located above the body text field.

Embed a document from the Media Library
  • In the Document Library section, search for the document if it has already been uploaded.
  • If the document hasn’t been uploaded yet, click the Create Document link, then upload your file in the Document Source field. The document will be saved and embedded in your page.

Using a remote URL to create a document

You can create a document link for a file hosted on another website by adding it to the Media Library. Select Remote URL in the Document Source field and enter the link.

This feature is useful for automatically creating a list of both internal and external documents on your website. You can also use topic tags to organize these documents.

For agencies that have many documents but cannot upload them to their site, this feature allows linking to documents hosted on external hubs, like documents.iowa.gov.

Important: If the remote URL changes, you must update it manually to ensure the document remains accessible.

2

How to hyperlink to a document in the Media Library

To link to a document:

  1. Within the Body text field, highlight the word or phrase you want to link.
  2. Within the WYSIWYG toolbar, click the Link (chain link) icon.
How to create a link to a document

Search for the document in the link URL field

In the "Link URL" field, search for the name of the document you previously uploaded to the Media Library.

  • You can find the document name in the "Media Name" field of the Media Library or in the "Name" field within the document’s edit section.
  • Do not use the file name from the "File" field or the file URL.

Example: The name field is where you can find the document name for internal linking

Document name field

Completing the internal link

Once you enter the document’s name in the Link URL field, the system will find it in the Media Library.

  1. Select the document from the dropdown search results under the Media section.
  2. Click the green checkmark to confirm your selection.

Now, you've successfully linked to an internal document.

Successfully creating a link to a document
3

How to update a document and file name

You can quickly update documents in the Media Library. Just use the 'edit' button. This saves you from having to upload a new document with the "Add media" button. This lets the platform update all the places where the document is linked.

To check if a document follows the correct naming convention:

  1. Go to the Media Library and filter by Documents.
  2. In Table View, click the Download button next to a document to check its name.
  1. Alternatively, click the Edit button (or pencil icon) to open the document’s media item page.
  1. Scroll down to the File field to see the document’s current file name.

How to fix an incorrect file name

If the file name doesn’t follow naming conventions:

  1. Click the Remove button.
  2. The Choose a File button will appear, allowing you to upload a new version of the document with the correct file name.

Why file naming conventions matter

Following proper file naming conventions is important for:

  • Accessibility: Clear file names help screen readers.
  • Web Performance: Consistent naming improves website performance and directory organization.
  • Usability: Properly named files are easier to find and organize.

By ensuring your document files follow the correct naming guidelines, you improve both accessibility and the overall functionality of your site.