Management

Streamlined Content: Effortless PDF Display & Management in Drupal

July 21, 2025

Look, sometimes clients just want users to see a PDF, not download it. But more importantly, sometimes they've got recurring documents, like various annual reports, and the content management gets messy.

I recently had a client who produces these annual reports every single year. Their process? Uploading the new PDF as a brand new media item. What happened? They'd either forget to update all the links pointing to the old PDF across the site, or they'd miss an old embed on some forgotten page. The result: users hitting outdated reports, and a content management headache every single year.

That's inefficient and leads to a terrible user experience. Drupal's Media module is great, but getting it to show PDFs right in the browser, and making it easy to update those annual reports without breaking links, takes a specific setup. We'll use core features and one slick contributed module to make it happen.

A Common Mistake: Linking Directly to the File Entity (and Why It's Bad)

Before we get to the proper solution, let's address a common pitfall I see all the time on Drupal sites: linking directly to the file itself. You know, like /sites/default/files/2024-annual-report.pdf.

This feels intuitive, right? It's the direct path to the file.But …

It's a trap!

Here's why you should never do this:

  • Broken Links on File Updates: When your client uploads the 2025 Annual Report, Drupal will typically rename the file (e.g., /sites/default/files/2025-annual-report_0.pdf) to avoid overwriting, or the new file might have a slightly different name. The old link is instantly dead. Your old /sites/default/files/2024-annual-report.pdf link is now pointing to nothing. This is exactly what my client was doing, leading to forgotten, broken links all over the site.
  • No Revisioning: You lose all the benefits of Drupal's revisioning system. There's no history of changes for that specific file.
  • Bypassed Access Control: If you're dealing with private files, linking directly to them can sometimes bypass Drupal's built-in access control, exposing content that shouldn't be public. The Media module handles permissions properly.
  • Limited Display Options: You can't easily control how the file is displayed (download vs. in-browser) or add metadata, image styles (for other media types), or anything else Drupal's Media system offers. It's just a raw file.

Using the Media module, with its associated entity, solves all these problems by giving you a stable, revisionable, and manageable asset.

This guide will show you how to set up your Drupal site to display PDF files directly in the browser, leveraging the Media module's revisioning and the Media Entity Download module; solving that annual report nightmare for good, and preventing the "direct file link" headache. We'll also cover a handy trick for more granular control over individual links, and a bonus tip for direct page linking.

Why Display PDFs In-Browser?

Simple:

  • Better UX: Quick previews, no cluttered downloads. Users always see the current version.
  • Faster Access: View it instantly.
  • Stay on Site: Keeps users focused on your content.
  • Streamlined Management (The Big Win!): Update your PDF, and all links automatically point to the new version, thanks to media revisions. No more hunting down old links!

What I Am Using

  • Drupal Core Media Module: Handles all your digital stuff.
  • Revisioning: Essential for document changes. Keeps a history and ensures links always point to the latest.
  • Media Entity Download Module: The key to changing that pesky download default.

The Setup

Assuming Drupal is running and Media is enabled, here's the drill:

1. Get Media Entity Download

First, grab the module using Bash:

composer require drupal/media_entity_download
drush en media_entity_download

2. Configure Your Document Media Type

Head to Structure > Media types. Edit your "Document" media type (or make one if you don't have it).

  • Make sure you have a File field (e.g.,field_media_document_file) set up to accept PDFs.
  • Handle the form and display settings as you normally would for your editors and front end.
  • Crucially, ensure "Create new revision" is checked for this media type. This is what allows you to simply upload a new file to the same media item, creating a new version while keeping the same stable URL.

3. Critical: Set Media Entity Download (Global Method)

This is where you make PDFs show up by default, site-wide.

  • Go to Configuration > Media > Media download settings (/admin/config/media/media-download).
  • Find your "Document" media type.
  • Locate the File field (e.g., field_media_document_file).
  • Change the "Download method" from "Force download" to "Display in browser".
  • Save it. Done. This will now apply to all links generated by the Media module for this type.

3a. Using A Query String (The Flexible Method)

What if you don't want to change the global behavior for all PDFs, but just for specific links? Or perhaps you generally want PDFs to download, but a few select ones should display in the browser?

The Media Entity Download module has a neat trick for this: add ?inline=1 to the end of your media download URL.

Let's say your media item's download URL is something like /media/123/download. If you want that specific PDF to display in the browser, change the link to:

/media/123/download?inline=1

This overrides the global setting for that specific link, telling the browser to display the PDF inline if possible. This gives you maximum flexibility if your needs aren't a blanket "display all PDFs."

4. Upload and Test

Now, try it out:

  • Create a new Media item, upload a PDF (e.g., your 2024 Annual Report).
  • Embed it on a page or link directly to the media entity's canonical download URL (e.g., /media/123/download). Hint: If you're using the global setting, this URL will automatically display inline. If you're not using the global setting, or want to override it, manually add ?inline=1 to the URL.
  • Check the page. The PDF should now display in the browser, not download.

5. The Annual Update Test!

Next year, when the annual report comes out:

  • Do NOT create a new media item.
  • Edit the existing "2024 Annual Report" media item (or whatever you named it).
  • Upload the new 2025 PDF file to the same file field. Because "Create new revision" is checked, this will replace the old file but keep the same media item ID and URL.
  • View the page where it's embedded. It should now show the 2025 report, without you changing a single link or embed on the site. This is the real content management win.

How Revisions Play In (The Real Problem Solver)

This is the game-changer for clients with annual reports. When you have the Media module's revisioning enabled for your "Document" media type, every time you upload a new version of a PDF (like replacing the 2024 report with the 2025 one), a new revision is created. The Media Entity Download module works seamlessly with these revisions. When a user views the media item, they will always see the current, published version of the PDF displayed in the browser, adhering to your "Display in browser" setting (either globally or via the query string ?inline=1).

This ensures that even if you're frequently updating documents, the user experience remains consistent and current, without needing to reconfigure download settings for each revision or, more importantly, without needing to hunt down and update every single link or embed across your entire website. That alone is worth the setup.

Bonus Tip: Linking to a Specific Page In A PDF File

Another common question that I get about linking to PDF files is, "Can I link directly to page 5 of this 100-page report?" Yes, you can! PDF viewers support a URL parameter to jump to a specific page.

Combine this with the ?inline=1 trick for powerful direct linking. The parameter to use is #page=[page number]. (Caution: verify your page numbers; page numbers in your document may differ from the PHYSICAL page number! ALWAYS USE THE PHYSICAL PAGE NUMBER!)

So, if you want to link to page 10 of a PDF that you also want to display in the browser, your URL would look like this:

/media/123/download?inline=1#page=10

Just append #page= followed by the desired page number to the end of your media download URL. This works whether you're using the global "Display in browser" setting or the ?inline=1 override. Keep in mind that browser support for this feature can vary slightly, but it's generally well-supported by modern PDF viewers.

A Few Things to Note

  • Browser Compatibility: While most modern browsers handle in-browser PDF display and page linking, older browsers or specific user settings might still prompt a download or ignore the page parameter. This is generally outside of Drupal's control but is increasingly rare.
  • Large Files: For very large PDF files, displaying them in the browser might still take a moment to load. Consider offering an optional "Download" link for users who prefer that method.
  • Security: This doesn't bypass Drupal's permissions. If a PDF is sensitive, make sure its access is restricted accordingly.

Conclusion

That's it. This setup gives your users a smoother experience with PDFs on your Drupal site and, more importantly, saves your content editors a ton of headache with recurring document updates. Media, revisioning, and Media Entity Download: a solid combo for display, not download, and intelligent content management.

Drop a comment below and let me know how you handle document management or if you have questions or comments about how I do it.

Author

Ron Ferguson

0 Comments

Login or Register to post comments.