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

It is helpful to make sure when you upload media onto your site you properly have the relevant division, topics, and document type tagged so when your team downloads the document report you can have a clear view of what that media item is.

Learn more about how to access the report of all the documents and content on your site.

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.

Managing documents in the media library

Benefits of managing documents through the Media Library

Benefits to uploading documents directly to the Media Library include: 

  • Easier document management
  • All files are updated in one place. It saves time looking for links in your website.
  • Changes will apply automatically across the entire site.

Check your document file name before uploading

Before uploading a document, ensure the file name follows best practices. 

You can follow the State of Iowa File Naming Conventions if your department does not have its own.

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.

Tips on 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)

Create a document

Create a document by uploading a file

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.

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.

Unique media ID

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. 

You can use the media ID in place of the document name.

1

Create a document

Create a document by uploading a file

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.

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.

Unique media ID

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. 

You can use the media ID in place of the document name.

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.

location of document page on the WYSIWYG editor

In the Document Library section, search for the document if it has already been uploaded.

document library while working on a web page

If the document hasn’t been uploaded yet, click the Create Document link, then upload your file in the Document Source field.

uploading document while working on a web page

The document will be saved and embedded in your page.

2

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.

location of document page on the WYSIWYG editor

In the Document Library section, search for the document if it has already been uploaded.

document library while working on a web page

If the document hasn’t been uploaded yet, click the Create Document link, then upload your file in the Document Source field.

uploading document while working on a web page

The document will be saved and embedded in your page.

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.
Successfully creating a link to a document

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

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

demonstrating how to not do internal document linking

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

3

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.
Successfully creating a link to a document

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

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

demonstrating how to not do internal document linking

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

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.

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.

Can I 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.
where to change the authoring information on a document page
4

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.

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.

Can I 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.
where to change the authoring information on a document page

Deleting a document

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.

how to delete document in media library

You can also edit the document and select the Delete option at the bottom of the screen.

delete button when editing a document
5

Deleting a document

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.

how to delete document in media library

You can also edit the document and select the Delete option at the bottom of the screen.

delete button when editing a document