[Proposal] Add PDF Block to Base Installation
See Github ticket. Please provide feedback before Dec 16, 2025.
TL;DR Summary
Many universities and institutions rely on PDFs for important course content. Currently, in Open edX, there’s no built-in way to display PDFs directly in a course.
We plan to introduce an official, supported PDF embed feature so institutions no longer need to install different plug-ins to make it work.
Problem
Universities and other institutions have datasheets, syllabi, and other documents, which they need to make available to learners. While we encourage teams to use web-native formats where possible, not being able to easily show PDFs directly in a course makes it harder and more expensive for institutions to move their materials online.
Several different companies have created their own versions of the PDF XBlock over the years. Most trace their origin to a single contributed (and subsequently abandoned) version, which several companies have forked (that is, copied and modified.) OpenCraft’s current fork of the block, which we use for our customers, is forked from a fork of a fork. Nearly all of our clients have explicitly requested the ability to embed PDFs, and as a result, nearly all of our clients have installed the PDF XBlock. We believe that this functionality should be in the base install of the platform and not required as a third party installation.
Use Cases
As a platform administrator, I want one reliable, officially supported way to embed PDFs so I don’t have to try several different ones I find online.
As an author, I want to easily embed PDFs in my course so learners can access important documents right where they need them.
As an instructor, I want to provide PDF content for my learners to work with offline so I can provide a mixed media experience.
As an instructor, I want to provide PDF content so learners use that content offline as needed.
As a learner, I want to view PDF content without having to leave the LMS so that I can stay in context with my learning session.
Proposed Solution
Several different companies have forked and modified the PDF XBlock over the years. OpenCraft’s current fork of the block, which we use with our customers, is forked from a fork of a fork. Nearly all of our (OpenCraft’s) clients have explicitly requested the ability to embed PDFs, and as a result, nearly all of our clients have installed the PDF XBlock.
We propose contributing our current version of the block, which has been updated to work with modern versions of the platform. Preferably, we believe this block should be included with the base installation due to the fact it is so popular. It can then centralize further improvements to the block to provide a consistent experience and make upgrading easier for institutions everywhere.
The PDF XBlock works similarly to other historical XBlocks: you add it as a component in Studio and then configure settings as needed,, including specifying the URL of the PDF, and whether to show a download link:
Scrolling down on the editing modal reveals additional fields:
Here is how the PDF block currently renders in the LMS:
Implementation Plan
The PDF XBlock will be added to the default-installed xblocks-contrib repository.
The PDF XBlock should be audited with an eye for contribution to the core, and any current blocking deficiencies addressed. Known blocking deficiencies include:
Refactor file uploads for PDFs to use the course "Files" resources.
The PDF XBlock will be included in the base installation as an advanced block that instructors can add to their courses. We believe that by default, this advanced module should be enabled, so that no special action will be needed by course authors to use it.
The PDF XBlock will be considered the officially supported way to embed PDFs in courses.
Our client is offering to sponsor the contribution of this XBlock to the project and so this work is expected to be funded.
The repository for the block is at 
GitHub - open-craft/xblock-pdf: Course component (Open edX XBlock) that provides an easy way to embed a PDF .
There are multiple forks of the block available, which can be traced from our block, the block we forked from, and RaccoonGang’s block. While each provides some adjustments and customization, none of these, save for one, changes anything about the fields. The aforementioned block adds a field for setting the height of the embed, which should degrade gracefully if replaced by this block.
Accordingly, we will keep the block’s original name of ‘pdf’ and it should ‘just work’ with all known existing blocks in courses. Teams who have maintained forks are encouraged to contribute changes to the newly official block.
Long-term Ownership and Maintenance Plans
We anticipate that several teams will need this functionality, and core contributors from OpenCraft will be actively involved in its development. These contributors will continue to assist with maintenance. If needed, one or more point persons can be designated as the primary contact for this code after its release.
Contact person
Fox Piacenti (fox at http://opencraft.com )
Other Approaches Considered
The current approach of keeping this XBlock a third party extension creates difficulties for multiple reasons:
PDF embedding is so common that we’ve found desire for this plugin to be near universal among our clients.
There are several forks which may appear authoritative. For instance, RacoonGang also maintains a fork with a common ancestry. This makes it difficult for institutions to determine which version of the block to install.
The various forks are at risk of diverging in compatibility. They use the same entry points and names, but may have varying fields. While some forking and customization is to be expected, it is preferable if it is only done when contributing to an authoritative source or when deliberately electing to diverge from the mainline, rather than finding a random fork, and then forking that due to there not being an official, maintained version to contribute back to.
Another alternative could be requiring course authors to either use downloadable PDFs only, from the files functionality. However, the existence of this XBlock and its years of history is evidence that course authors do not find this to be sufficient for the course experiences they wish to present.
A third alternative would be to require course authors to re-implement any content constrained to PDF to more web-native and accessible presentation modes, such as HTML. For many institutions who are doing blended learning, this may be impractical, as they may have offline needs for the media they’re embedding. For others who are migrating to online instruction, this introduces significant added cost.
On that note, accessibility is likely the strongest objection to natively embedding PDFs. PDFs are not typically accessible, as they are instructions for laying out print media which may only incidentally contain text. PDFs are not designed to be viewed on screens. While this is true, the harms can be mitigated. Fields could be added for alt text, warnings could be added, and it should be possible for institutions with strong accessibility requirements to put boundaries around its usage.
These are preferable to fragmentation, since institutions have proven willing to install the block at high rates even with the downsides. From their perspective, Open edX is ‘not letting them embed PDFs’, and the consequences of using them may not even be considered. A block that displays accessibility warnings can prompt discussions in organizations that would otherwise install a random block and not think about it further. These are only example methods, and we invite comments on how to best address these issues from a product perspective.
Competitive Research
Both Moodle and Canvas (the two LMSes this author had ready access to) support direct embedding of PDF files.
Moodle
Moodle uses a universal ‘File Embed’ module that allows you to upload a PDF. It can then select from different dispositions when displaying it:
The default choice presents a download link. However, an embedded view is selectable. The resulting embedded view looks like this:
Canvas
The canvas pages rich editor allows the insertion of files. Like Moodle, the default disposition is a link, which is added to the page. However, editing that link’s properties allows for selecting inline viewing:
The resulting embed looks like this: