docs: initial setup for pdf block #1386

Kelketek · 2026-02-06T19:01:35Z

Description

This merge request documents the PDF Block. It documents the block's current functionality as initially contributed, and follow-up PRs will be added as other elements of the PDF Proposal are completed, to keep the documentation up to date.

Supporting information

PDF Block Proposal

Dependencies

The merge request for adding the PDF block to XBlocks-Contrib should be merged before merging this PR.
Once that PR is merged, one more PR is expected for updating the version of xblocks-contrib in edx-platform. This has not yet been created.

Deadline

This documentation must be merged before Verawood, which is when the PDF block will be standardized.

openedx-webhooks · 2026-02-06T19:01:41Z

Thanks for the pull request, @Kelketek!

This repository is currently maintained by @openedx/wg-maintenance-docs.openedx.org.

Once you've gone through the following steps feel free to tag them in a comment and let them know that your changes are ready for engineering review.

🔘 Get product approval

If you haven't already, check this list to see if your contribution needs to go through the product review process.

If it does, you'll need to submit a product proposal for your contribution, and have it reviewed by the Product Working Group.
- This process (including the steps you'll need to take) is documented here.
If it doesn't, simply proceed with the next step.

🔘 Provide context

To help your reviewers and other members of the community understand the purpose and larger context of your changes, feel free to add as much of the following information to the PR description as you can:

Dependencies

This PR must be merged before / after / at the same time as ...
Blockers

This PR is waiting for OEP-1234 to be accepted.
Timeline information

This PR must be merged by XX date because ...
Partner information

This is for a course on edx.org.
Supporting documentation
Relevant Open edX discussion forum threads

🔘 Get a green build

If one or more checks are failing, continue working on your changes until this is no longer the case and your build turns green.

Details

Where can I find more information?

If you'd like to get more details on all aspects of the review process for open source pull requests (OSPRs), check out the following resources:

When can I expect my changes to be merged?

Our goal is to get community contributions seen and reviewed as efficiently as possible.

However, the amount of time that it takes to review and merge a PR can vary significantly based on factors such as:

The size and impact of the changes that it introduces
The need for product review
Maintenance status of the parent repository

💡 As a result it may take up to several weeks or months to complete a review and merge your PR.

Kelketek · 2026-02-06T19:34:55Z

@samuelallan72 This is ready for you.

samuelallan72

Thanks @Kelketek ! In general things look pretty good. I left some requests though. :)

samuelallan72 · 2026-02-09T00:06:59Z

source/educators/concepts/advanced_features/pdf_embed.rst

+--------------+-------------------------------+----------------+--------------------------------+
+| Review Date  | Working Group Reviewer        |   Release      |Test situation                  |
+--------------+-------------------------------+----------------+--------------------------------+
+|              |                               |                |                                |


@Kelketek please add your information here to confirm they work - see #1376 (comment) for context.

samuelallan72 · 2026-02-09T00:07:44Z

source/educators/how-tos/course_development/exercise_tools/enable_pdf_embed_tool.rst

+##########################
+
+Before you can add an embedded PDF to your course, you must enable the pdf embed
+tool in Studio or OLX (open learning XML).


Suggested change

tool in Studio or OLX (open learning XML).

tool in Studio.

It's confusing to me, mentioning to enable it in the OLX, when there is no example of enabling it in the OLX.

samuelallan72 · 2026-02-09T00:08:06Z

source/educators/how-tos/course_development/exercise_tools/enable_pdf_embed_tool.rst

+Before you can add an embedded PDF to your course, you must enable the pdf embed
+tool in Studio or OLX (open learning XML).
+
+To enable the pdf embed tool in Studio, you add the ``"pdf"`` key to the


Suggested change

To enable the pdf embed tool in Studio, you add the ``"pdf"`` key to the

To enable the pdf embed tool in Studio, add the ``"pdf"`` key to the

samuelallan72 · 2026-02-09T00:10:39Z

source/educators/how-tos/course_development/exercise_tools/add_embedded_pdf.rst

+
+.. tags:: educator, how-to
+
+#. On the Course Outline page, open the unit where you want to add the PDF.


Since the PDF block will be disabled by default, I think this needs a pre-requisite step of "ensure the pdf tool is enabled in the course".

samuelallan72 · 2026-02-09T00:13:53Z

source/_images/educator_references/pdf_embed.png

I feel like this would be a more useful screenshot if it included some of the Studio UI (eg. with the edit button, etc.). That might provide some more context, especially for where it's used to demonstrate what it should look like once you've selected the pdf component to add in studio.

@Kelketek did you have thoughts on this one?

samuelallan72 · 2026-02-09T00:16:22Z

source/educators/how-tos/course_development/exercise_tools/add_embedded_pdf.rst

+   If you do not have an existing URL for your PDF, you may upload the PDF by
+   :ref:`adding it as a handout<Add Course Updates and Handouts>` and copy the
+   URL of the resulting handout.


Do you mean adding a course file ( https://docs.openedx.org/en/latest/educators/how-tos/course_development/manage_course_files.html#add-course-files ) instead?

I don't think a course handout is relevant here.

samuelallan72 · 2026-02-09T00:17:29Z

source/educators/how-tos/course_development/exercise_tools/add_embedded_pdf.rst

+    PDF display is handled by the browser's built-in PDF viewer. The option to hide the download button will not hide the browser's built-in download button if it provides one. A determined learner will always be able to download a PDF.
+
+
+#. In the **Source document URL** field, optionally add the URL to the source


This list numbering is restarted due to the note block above. Perhaps the note block can be indented to not break the list flow?

Kelketek · 2026-02-09T19:43:43Z

Thanks, @samuelallan72 . I've addressed your notes. I also adjusted the wording of the warnings for accessibility in the PDF Concepts document since it turns out the accessibility checklist mentions several things you can do to improve their accessibility.

samuelallan72

@Kelketek thanks! Everything looks good to me. Github wouldn't let me resolve the threads, but please consider them resolved.

Just the one comment about the screenshot; I pinged you again on it in case you hadn't seen it. I wouldn't consider it a blocker, I just had a suggestion about including some of the Studio UI in the screenshot to give it more context. I'll leave that up to you.

Please also link BB-10504 to the PR description. :)

👍

I tested this: checked the rendered pages for rendering issues, checked all links, checked the new instructions for accuracy and readability (I didn't retest on a pdf xblock, but the instructions match my recent memory and make sense).
I read through the code
I checked for accessibility issues
Includes documentation

sarina · 2026-02-10T15:56:46Z

source/educators/concepts/advanced_features/pdf_embed.rst

+Embedding PDFs in Your Course
+##############################
+
+.. tags:: educator, concept


Why is this a concept and not a how-to? The title lends itself to a how-to ("How To.... Embed PDFs in your course"). I honestly think fragmenting the text between a Concept and a How-To is not the best reading experience.

sarina · 2026-02-10T15:57:47Z

source/educators/how-tos/course_development/exercise_tools/enable_pdf_embed_tool.rst

+--------------+-------------------------------+----------------+--------------------------------+
+| Review Date  | Working Group Reviewer        | Release        | Test situation                 |
+--------------+-------------------------------+----------------+--------------------------------+
+| 09/02/2026   | Fox Piacenti                  |  master        | Pass                           |


We do release names, not master. The release here would be Verawood, no?

sarina · 2026-02-10T15:58:06Z

source/educators/how-tos/course_development/exercise_tools/enable_pdf_embed_tool.rst

+##########################
+
+Before you can add an embedded PDF to your course, you must enable the pdf embed
+tool in Studio.


Is this something that site operators will need to install?

sarina · 2026-02-10T15:59:31Z

source/educators/how-tos/course_development/exercise_tools/add_embedded_pdf.rst

+
+.. tags:: educator, how-to
+
+#. Ensure the PDF embed tool is :ref:`enabled in your course<Enable PDF Embed Tool>`.


Do you think this should be a separate how-to? It's quite short.

openedx-webhooks added the open-source-contribution PR author is not from Axim or 2U label Feb 6, 2026

openedx-webhooks added this to Contributions Feb 6, 2026

github-project-automation bot moved this to Needs Triage in Contributions Feb 6, 2026

Kelketek force-pushed the fox/pdf-block branch from 1729837 to 5602e89 Compare February 6, 2026 19:32

samuelallan72 suggested changes Feb 9, 2026

View reviewed changes

Kelketek force-pushed the fox/pdf-block branch 2 times, most recently from 465c0c7 to 01076a7 Compare February 9, 2026 19:19

docs: pdf block

37ffc71

Kelketek force-pushed the fox/pdf-block branch from 01076a7 to 37ffc71 Compare February 9, 2026 19:41

mphilbrick211 moved this from Needs Triage to Waiting on Author in Contributions Feb 9, 2026

samuelallan72 approved these changes Feb 10, 2026

View reviewed changes

sarina requested changes Feb 10, 2026

View reviewed changes

	To enable the pdf embed tool in Studio, you add the ``"pdf"`` key to the
	To enable the pdf embed tool in Studio, add the ``"pdf"`` key to the


		.. tags:: educator, how-to

		#. On the Course Outline page, open the unit where you want to add the PDF.

		PDF display is handled by the browser's built-in PDF viewer. The option to hide the download button will not hide the browser's built-in download button if it provides one. A determined learner will always be able to download a PDF.


		#. In the Source document URL field, optionally add the URL to the source


		.. tags:: educator, how-to

		#. Ensure the PDF embed tool is :ref:`enabled in your course<Enable PDF Embed Tool>`.

docs: initial setup for pdf block #1386

Are you sure you want to change the base?

docs: initial setup for pdf block #1386

Uh oh!

Conversation

Kelketek commented Feb 6, 2026

Description

Supporting information

Dependencies

Deadline

Uh oh!

openedx-webhooks commented Feb 6, 2026

Uh oh!

Kelketek commented Feb 6, 2026

Uh oh!

samuelallan72 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Kelketek commented Feb 9, 2026

Uh oh!

samuelallan72 left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

samuelallan72 left a comment •

edited

Loading