Linking to documents

Learn best practices in linking to documents.

Currently, there are several ways to add/link documents to pages in edit.mass.gov. We’re continuing to improve and develop this experience, but below you can find information about the best way to add documents.

Recommended way to link to documents

At the moment, there are 2 visual cues to know you’re adding documents in the most stable way possible. Either you’re interacting with an autocomplete field or you’re adding a document to a page via a file browser. Any documents in these fields will automatically be updated if the document it refers to is changed. (See below to learn how to update existing document files.) Here’s what these fields look like:

File browser shown in edit.mass.gov.

Additional Resources” section with an autocomplete field.

Generally, you’ll find these fields in the Additional Resources or Downloads sections in most content types. A key benefit of this method is that it give users a consistent experience across Mass.gov. You can find these fields in most content types.*

*On some content types, such as the Service Detail and the Information Detail, the “Additional resources” and “Downloads” sections you use to upload documents are not visible until you’ve created a section.

Creating inline links to documents

You can also 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:

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:

Scroll down to and click the “Select files” button. Important: when linking to documents this way, you can only select one at a time.

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.

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.

Let us know how you’re using inline links by completing our inline links insight form.

Was this article helpful?

Tell us what you think button