Skip to content

docs: initial setup for pdf block #1386

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
sarina merged 3 commits into from
Feb 11, 2026
+105 −4
Merged

docs: initial setup for pdf block #1386

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
37ffc71
docs: pdf block
Kelketek Feb 3, 2026
a70f973
docs: address notes on pdf embeds
Kelketek Feb 10, 2026
bca6ffc
fix: headers in PDF embed tutorial
Kelketek Feb 11, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Binary file added source/_images/educator_references/pdf_embed.png
View file
Open in desktop
Copy link
Contributor

@samuelallan72 samuelallan72 Feb 9, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor

@samuelallan72 samuelallan72 Feb 10, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@Kelketek did you have thoughts on this one?

Copy link
Contributor Author

@Kelketek Kelketek Feb 10, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@samuelallan72 I missed the original comment, but I don't think this should be changed as it matches how screenshots are handled in other parts of the documentation, like here.

Copy link
Contributor

@samuelallan72 samuelallan72 Feb 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Got it, that's fair. Thanks for checking. :)

Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
45 changes: 45 additions & 0 deletions source/educators/concepts/advanced_features/pdf_embed.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,45 @@
.. _PDF Embed:

##############################
Embedding PDFs in Your Course
##############################

.. tags:: educator, concept

The PDF embed tool allows you to add PDF documents to your course. It uses an
the browser's built-in PDF viewing capability, and provides options for
downloading the document or its original source.

.. image:: /_images/educator_references/pdf_embed.png
:alt: An embedded PDF showing trigonometry functions.
:width: 500

PDFs have significant accessibility challenges. They are finalized documents intended
for printing exactly specified copies. This makes them difficult for screen readers
and other assistance technology to interpret. You are strongly encouraged to
use alternative means of presenting the information in these documents, such as
a :ref:`text component<Working with Text Components>`. Please visit the
:ref:`Accessibility Best Practices Checklist` for more information, which also
includes a guide on improving PDF accessibility if they must be used.

Additionally, viewing PDFs on mobile devices results in a poor learner
experience.

Nevertheless, the PDF embed block exists to handle the case of a document
being unavailable in other formats, or for when variations in representing the
document are unacceptable.

.. seealso::


:ref:`Enable PDF Embed Tool` (how-to)

:ref:`Add Embedded PDF` (how-to)

**Maintenance chart**

+--------------+-------------------------------+----------------+--------------------------------+
| Review Date | Working Group Reviewer | Release | Test situation |
+--------------+-------------------------------+----------------+--------------------------------+
| 09/02/2026 | Fox Piacenti | master | Pass |
+--------------+-------------------------------+----------------+--------------------------------+
67 changes: 67 additions & 0 deletions source/educators/how-tos/course_development/exercise_tools/add_embedded_pdf.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,67 @@
.. _Add Embedded PDF:

Add an Embedded PDF in Open edX Studio
#######################################

.. tags:: educator, how-to

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

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

#. Under **Add New Component** click **Advanced** and then select **PDF**.

The new component is added to the unit with a default example PDF embedded.

.. image:: /_images/educator_references/pdf_embed.png
:alt: The PDF embed component in Studio.
:width: 400

#. In the new component, click the **Edit button, or pencil icon**.

#. In the **Name** field, enter the name for the new component. This will be
displayed above the component as a title.

#. In the **PDF URL** field, set the URL of the PDF you would like to embed.

If you do not have an existing URL for your PDF, you may upload the PDF by
:ref:`adding a course file<Add Course Files>` and copy the
URL of the resulting handout.

#. Toggle the **PDF Download Allowed** field to optionally display a
download link for the PDF.

.. note::

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
of the PDF document.

This might be, for instance, the power point or word document this PDF is
based on. Providing a source URL is heavily encouraged, as source files
tend to have better accessibility than PDFs. Please visit the
:ref:`Accessibility Best Practices Checklist` for more information.

#. In the **Source document button text** field, you can change the display
text of the source download link.

#. Select **Save**.


.. seealso::


:ref:`PDF Embed` (concept)

:ref:`Enable PDF Embed Tool` (how-to)


**Maintenance chart**

+--------------+-------------------------------+----------------+--------------------------------+
| Review Date | Working Group Reviewer | Release | Test situation |
+--------------+-------------------------------+----------------+--------------------------------+
| 09/02/2026 | Fox Piacenti | master | Pass |
+--------------+-------------------------------+----------------+--------------------------------+
28 changes: 28 additions & 0 deletions ...e/educators/how-tos/course_development/exercise_tools/enable_pdf_embed_tool.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
.. _Enable PDF Embed Tool:

Enable the PDF Embed Tool
##########################

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

@sarina sarina Feb 10, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this something that site operators will need to install?

Copy link
Contributor Author

@Kelketek Kelketek Feb 10, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@sarina No, not once the dependencies for this PR are resolved.


To enable the pdf embed tool in Studio, add the ``"pdf"`` key to the
**Advanced Module List** on the **Advanced Settings** page. (Be sure to include
the quotation marks around the key value.) For more information, see
:ref:`Enable Additional Exercises and Tools`.

.. seealso::


:ref:`PDF Embed` (concept)

:ref:`Add Embedded PDF` (how-to)


**Maintenance chart**

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

@sarina sarina Feb 10, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Contributor Author

@Kelketek Kelketek Feb 10, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@sarina It would be Verawood. I'll update it. I copied use of master from this line in this PR. Should this be corrected or are there cases where master should used? In what cases would those be?

Copy link
Contributor

@sarina sarina Feb 11, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I missed that, then. "master" isn't a good point in time indicator, especially for educator's docs.

Copy link
Contributor Author

@Kelketek Kelketek Feb 11, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@samuelallan72 See the above, please!

Copy link
Contributor

@sarina sarina Feb 11, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think that's one where I was okay with master, actually, because it was a site ops document.

Copy link
Contributor Author

@Kelketek Kelketek Feb 11, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah, OK!

+--------------+-------------------------------+----------------+--------------------------------+
19 changes: 15 additions & 4 deletions source/educators/navigation/content_creation_management.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -66,15 +66,15 @@ Manage Text Components

.. toctree::
:maxdepth: 1
:glob:
:glob:

../references/course_development/text_components/text_components.rst
../how-tos/course_development/text_components/manage_text.rst
../how-tos/course_development/text_components/manage_html.rst
../how-tos/course_development/text_components/manage_latex.rst
../how-tos/course_development/exercise_tools/add_mathjax.rst
../how-tos/course_development/exercise_tools/manage_full_screen_image.rst

.. _Add Video Components:

Manage Video Components
Expand Down Expand Up @@ -130,7 +130,7 @@ Add Mathjax
:glob:

../references/course_development/exercise_tools/mathjax_studio.rst


Add Tags
*******************************************************
Expand Down Expand Up @@ -165,6 +165,17 @@ Google Drive Tool
../how-tos/course_development/exercise_tools/enable_google_drive_tool.rst
../how-tos/course_development/exercise_tools/add_google_drive.rst

Embed PDFs
*******************************************************

.. toctree::
:maxdepth: 1
:glob:

../concepts/advanced_features/pdf_embed.rst
../how-tos/course_development/exercise_tools/enable_pdf_embed_tool.rst
../how-tos/course_development/exercise_tools/add_embedded_pdf.rst

Embed IFrames
*******************************************************

Expand Down Expand Up @@ -213,7 +224,7 @@ initiative.
.. toctree::
:maxdepth: 1
:glob:

../how-tos/course_development/migrate_legacy_libraries.rst
../concepts/instructional_design/libraries.rst
../how-tos/course_development/create_library.rst
Expand Down