Linking to documents

Learn best practices in linking to documents.

Currently, there are 2 main ways to add documents to pages in the CMS, and both involve using a file browser.

Recommended way to link to documents

You can access the file browser, a sort of internal search engine to find available documents, both in the rich text editor and "Additional Resources" or "Downloads" sections of many content types.

Any documents added to pages via the file browser will automatically be updated if the underlying document file is changed. (See below to learn how to update existing document files.) Here’s what the file browser looks like:

File browser

Creating inline links to documents

You can add a document using the rich text editor. When users click this kind of rich text link, their document will download or display. They won’t be taken to a separate page. The link will also update whenever you replace the document. Here’s how it works:

Step 1: Make sure your cursor is positioned where you want the link to appear. Don’t write any link text (yet).

Step 2: Click the “Insert Link to Document” button. Its icon is a document with a down arrow.

Step 3: An interface will open that allows you to search for and select the document you want to link. You can select 1 document at a time.

Step 4: Click on the check box next to the document's name and then scroll down to and click the “Select file” button. Important: when linking to documents this way, you can only select one at a time.

"Select file" to insert from a list

Step 5: The link will appear on the page as the document title.

Changing the link text when inline linking to documents

You’ll probably want to change the name of the link so that it’s accessible and more intuitive for users. Here’s how you do that.

Step 1: First, click the “Source” button on the far right of the editor.

Click the "Source" icon

Step 2: You’ll be shown the code that the editor generates. Next, you’ll need to find the link in the code. It will begin with an <a href> tag and end with an </a> tag. You’ll know it’s the right link because the name of your document will appear between them:

Step 3: Change the link text to whatever you’d like the link to read. This is a good time to think about how the link would sound if read aloud, as that’s how users with screen readers experience it. “Learn more about the migration” makes sense, but “click here” does not.

Linking to documents via "Additional Resources" and "Downloads" sections

The Links autofill field under "Additional Resources" is for adding links to other Mass.gov pages or external URLs.

The "Downloads" section beneath that is where documents can be added to pages.

"Additional Resources" and "Downloads" section

Step 1: If you want to make a new document available via the CMS, we recommend doing so via the "Add Document" process outside of the page you are working on, rather than using the "Add new media item" button. Once the file has been added to the system, you can access it via the "Add existing media item" button shown in the screenshot above.

Step 2: Clicking on "Add existing media item" will bring up the file browser introduced earlier in this article. However, there is 1 important difference between how the file browser looks in a rich text editor and via "Downloads."

Step 3: Once you have selected the document you want to add, you need to be sure to scroll down and click "Select file," as when using the file browser in a rich text editor. That will link the document from your page.

Note: Don't be tempted to click on the "Add media item" button underneath the file browser, as it will not do anything.

Use "Select file," not "Add media item"

Was this article helpful?

Tell us what you think button