How Do I Manage Documents in the Media Library?

Documents, such as PDF and XLS files, can be stored in the Media Library as individually uploaded files.

When a document is uploaded to the Media Library, it is assigned a media ID (media library identification number). This unique ID helps the platform identify and serve the document wherever needed.

For example, you may want to create a Listing Page to organize and display 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 adjust the date displayed for a document by editing the appropriate fields:

  • Display Date – This section controls the date shown under the document’s title on the listing page.
  • Authored Information – Updating this field allows the document to be sorted and searched by a specific year.
decorative

Benefits of Managing Documents Through the Media Library

Uploading documents directly to the Media Library ensures easy management and updates. Instead of searching for outdated external document links, you can update a file in one place, and the changes will automatically apply across the entire site.

Check Your Document File Name Before Uploading

Before uploading a document, ensure that the file name follows best practices. Your department may have its own naming conventions, or you can follow the State of Iowa File Naming Conventions.  Here are a few tips:

  • Length: Keep file names under 31 characters to reduce errors and improve readability.
  • Punctuation: Avoid spaces, periods, or underscores. Use hyphens instead.
  • Description: Use clear, descriptive file names that provide enough context.
  • 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")

Example of a good document naming convention:

  • Project Name-Document Type-Date: (e.g., "CohortPlan-Schedule-20240511")

Internal Document Embedding/Linking Best Practices

When linking to a document in the Media Library, always use the document’s name rather than its full URL.

Using a full URL (e.g., "https://...") creates an absolute link, which can result in broken links and negatively impact your website’s accessibility score.

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

When to Use a Full URL:
The full "https://-" URL should only be used for external links—not for documents stored within the site.

Incorrect Example (Linking to Internal Documents Using a Full URL will cause a "No results - No content suggestion found" text to appear where the media header should be):

decorative
1

Upload and Embed a Document

To upload a document to the media library, click the Content link dropdown, then navigate to the Media link. From the dropdown menu, select Add Media link, and then choose Document link from the sidebar dropdown list of available media types. This will allow you to add the document to the site's media library by selecting the upload file button within the new window that the document link will bring you to. 

Always remember to name your document following an easy to understand naming convention so that it can be easily found within the media library by your team and when users download the file they also understand what the file is from the file name.

decorative

Embedding a Document on a Basic Page

Once the document is uploaded to the media library, you can easily embed it into a Basic Page using the Document button within the WYSIWYG editor that hovers above the Body free text field.

decorative

Within the Document Library section, you can search for the document you want to embed if it has already been added to the media library.

decorative

If the document has not yet been uploaded, you can also add it from this section. Click the Create Document link on the right side of the Document Library, then upload your file in the Document Source field. The document will be saved in the media library and embedded within your page.

decorative

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. In the Document Source field, select Remote URL and enter the link.

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

This feature is also useful for agencies who may have a lot of documents and they are unable to upload them on to their site but instead are using a document library hub like documents.iowa.gov.

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

decorative
2

How to Hyperlink to a Document in the Media Library

You can easily link to a document using the same process as linking to internal pages on your site with the Link tool in the toolbar.

  1. Highlight the word or phrase you want to link to the document.
  2. Click the "Link" (paperclip) icon.
how to link to google documents

Searching for the Document in the Link URL Field

In the "Link URL" field, search for the name of the document you 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

decorative

Completing the Internal Link

Once you enter the document media name in the "Link URL" field, the system will locate 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 on your site!

decorative
3

How to Update a Document & File Name

To verify that the document files you uploaded to the Media Library follow the correct naming convention, follow these steps:

  1. Go to the Media Library and filter the media item types by Documents.
  2. If you are using Table View, click the Download button next to the document media item. This allows you to easily download the file and check its name.
    • decorative
  3. Alternatively, you can select the Edit button or the pencil icon (depending on whether you are in Table or Grid View) to open the document’s media item page.
    • decorative
  4. On the Edit Page, scroll down to the "File" field. Here, you will see the document file name currently stored in the Media Library.
decorative

How to Fix an Incorrect File Name

If the file name in the "File" field does not follow naming convention best practices:

  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.
decorative

Why File Naming Conventions Matter

Following proper file naming conventions is important for:

  • Accessibility – Screen readers rely on clear and structured file names.
  • Web Performance – Consistent naming helps with web pages and directories.
  • Usability – Properly named downloadable files (such as PDFs, Word documents, and Excel spreadsheets) are easier to organize and find.

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