Documents (PDFs) in Drupal

A Couple Rules

  1. PDFs are the only document type that is approved for upload into Drupal. No Word docs, no PowerPoints, no Excel Spreadsheets, etc.
  2. All PDFs must pass latest WCAG 2.1, Level AA Accessibility standards before they are uploaded into Drupal. That is your responsibility to ensure. Please read through our PDF Accessibility page.
  3. All PDFs must be optimized for Web. They must be less than 10 MB in size or they will not successfully upload into Drupal. See this helpful video for guidance.
  4. Flipbooks are prohibited.

Related Training Guides

On this page:

  • Rules around PDF use
  • PDFs vs Basic Pages: when should you create a Basic Page for your content instead of uploading a PDF?
  • How to Upload a new PDF into Drupal (Ex: this is new content with no existing version of this PDF in existence on Drupal already)
  • How to Link to a PDF
  • How to Update a current PDF in Drupal (Ex: there is an existing PDF already in Drupal but you need to upload a newer version)

PDF vs Basic Page

A Basic Page is always going to be the ADA compliant (Accessible) option. PDFs should really only be used for print-ready items that are static and don't update often, like a flyer or a report. There is a very small use-case for such exceptions on our sites. For these reasons we strongly discourage the use of PDFs. Flipbooks are prohibited.

Default rule

Create a Basic Page by default. Use PDFs only by exception, and only when you can meet accessibility requirements for that PDF (or have a documented technical/legal constraint and you have ensured that PDF meets AA level accessibility requirements).

Use a Basic Page when

Choose a Basic Page when the content is meant to be read, navigated, searched, or updated on screen, including:

  • Patient instructions, clinic prep, aftercare, FAQs, policy pages, directions, pricing/financial assistance explanations
  • Anything that changes periodically (hours, eligibility, program details)
  • Anything that needs to work well on mobile or with large text settings
  • Anything with multiple related pages/sections where navigation matters
  • Forms people must complete online (use accessible web forms, not PDF forms, when feasible)

Rationale: Public digital services should be delivered as structured web pages. Major public-sector publishing guidance explicitly discourages PDFs for on-screen reading and favors HTML (basic pages).

Use a PDF when (exception cases)

A WCAG 2.1, AA Level accessible PDF is reasonable when there is a real format need, for example:

  • Print fidelity is essential (e.g., a poster/flyer meant to be printed as-is)
  • A document must be distributed as a fixed “record” version (e.g., board packet, formal report snapshot) and you will keep it accessible
  • A third-party or system-generated document where HTML isn’t feasible right now (must still be AA Level accessible)

Even in these cases, require that the PDF be accessible (tagged, structured, etc.).

A simple decision rubric you can follow

Ask these questions in order:

  1. Is this primarily “web content” (read/scan/use on a phone)?
    → Publish as Basic Page.
  2. Will this change in the next 6–12 months?
    → Publish as Basic Page (PDFs drift out of date quickly and are harder to maintain at scale).
  3. Does it need to be filled out online or interacted with?
    → Use a Basic Page with fillable form (submit a request via our intake form to have this created for you). If a PDF form is unavoidable, it must be an accessible PDF form and tested.
  4. Is there a print/legal record requirement that truly needs fixed layout?
    → PDF is allowed, but only if it’s authored accessibly to WCAG 2.1, AA Level standards.
This is for new content with no existing version currently in existence on Drupal already

How to Upload a new PDF into Drupal

Step 1: Prepare the PDF for Upload

  • Ensure the document is in an optimized, accessible, PDF format. (Word, PowerPoint, and Excel files are not allowed)
  • The file name must be clear and simple (e.g. annual-report-2025-q2.pdf)
    • Separate words with hyphens instead of spaces
    • Use all lowercase letters
screenshot of the document upload screen in Drupal

Step 2: Upload the PDF to Drupal

  • Log in to Drupal
  • Hover over Content > Media > Add Media > Document
  • In the Name field, enter a human-readable, brief description of the PDF. This is separate from the file name in Step 1 and is what screen readers will announce to users. (e.g. "Q2 2025 Annual Report" or "Meeting Minutes - June 5, 2025")
    • Use capital letters and spaces for readability
  • Click Choose File and select the PDF from your computer
  • Enter a description in the Description box
  • Enter copyright information in the Copyright section. If you created it yourself just say that in the field.
  • Ensure both boxes in the Visibility section are checked
  • Skip the Revision information section (unless updating an existing document)
  • Click Save to upload the file

 

How to Link to a PDF

Link to the PDF

  • Make sure you are logged in to your Drupal site
  • Navigate to the page where you want to add the PDF link.
  • Click Edit to modify the page content.
    • If hyperlinking text in a WYSIWYG field, select/highlight the text where you want the link to appear.
  • Click the Link button.

 

screenshot of the hyperlink field in a WYSIWYG
  • In the Link URL field, start typing the human readable name you gave the PDF. A list of items with that name will appear.
  • Select the correct file from the dropdown under the Media - Document category.
  • Click the blue Apply button to save your work

 

screenshot of the PDF selection on a url field
  • If you are not choosing to link to your PDF via hyperlinked text, the other option is a simple URL field in any given component (Button, CTA, etc.) that has styling for a link built in to the functionality. In that case you simply start typing the human readable name of the PDF (same as you would in the example above) in the appropriate URL field.
    • The Link text field is where you would type the text that displays as the clickable item that takes a user to the PDF. Unless, of course you have otherwise selected the entire component to act as the hyperlinked object. Please reach out to the Digital Experience team if you need more clarification around this.
  • Click the blue Apply button to save your work.

 

screenshot of the URL field in a Drupal component
This is for updating an existing PDF with a newer version

How to update a current PDF in Drupal

Update an existing document (PDF) in Drupal

  • Log in to your Drupal site.
  • Hover over the Content tab in the admin toolbar then select Media from the dropdown
  • On the Media page, type keywords from the human readable name of the current PDF into the Media name search field then click Filter
  • In the results that appear, click Edit on the right-hand side of the name of the appropriate document you wish to update
  • In the edit window, scroll down to the Document section and click the grey Remove button to remove the existing file.
  • Then click Choose File and upload the new version.
    • If applicable, update the Name field to reflect the new version of the document (e.g. 2024 to 2025, etc.)
  • Click Save.
  • Done! Your document is now updated. All current links to this document will remain intact.

If you have any questions or run into any issues, please submit a ticket via our intake form.