Converting Maths Documents to Accessible HTML: A Guide for Staff

Making your maths teaching materials accessible benefits all students. Converting LaTeX and Quarto documents to HTML creates content that works with screen readers, adapts to different devices, and reaches a wider audience.

This guide walks you through four practical workflows. Each has its strengths, so you can choose what works best for your content and workflow.

Why HTML matters for accessibility

Unlike PDFs, which lack structure for screen readers to distinguish elements, screen readers can navigate the HTML tag structure effectively, maths equations can be read aloud (when properly formatted), and content can be resized more effectively on different screen sizes. By converting your materials to HTML, you're making them more inclusive and easier to use for everyone.

Workflow 1: LaTeX to HTML with TeX4ht

TeX4ht converts LaTeX documents directly to HTML while preserving mathematical notation. It's been around for years and handles complex LaTeX documents well.

What you'll need

• A LaTeX distribution (TeX Live or MiKTeX)

• Your LaTeX source files

• Command line access (Terminal on Mac/Linux, Command Prompt on Windows)

Step-by-step guide

1. Open your command line interface.

   • On Mac: Open Terminal from Applications > Utilities

   • On Windows: Search for "Command Prompt" in the Start menu

   • On Linux: Open your preferred terminal application

2. Navigate to your document folder.

   cd path/to/your/latex/folder

   Replace path/to/your/latex/folder with the actual location of your LaTeX file.

3. Run the conversion command.

   make4ht filename.tex "mathml,mathjax,sections+"

   Replace filename.tex with your actual file name.

   The commands within the quotation marks are called 'options'. mathml, mathjax refer to the maths formatting support. Due to varying levels of browser support, it's recommended to include both options. sections+ creates titles in the sections that link to the table of contents.

4. Check the output. Look for a new HTML file in the same folder. Open it in your web browser to review.

Tips

• TeX4ht works best with standard LaTeX packages. If you're using unusual or custom packages, you might need to adjust your document.

• Do not use images of equations, but rather write them out.

• Mathematical equations are converted to MathML by default, which screen readers can interpret with the proper setup.

• Images and graphics should be in standard formats (PNG, JPG) for best results.

Workflow 2: LaTeX to HTML with Pandoc

Pandoc is a versatile document converter that handles many formats, including LaTeX to HTML. It's particularly good at creating clean, readable HTML.

What you'll need

• Pandoc installed on your computer (download from Pandoc)

• Your LaTeX source file(s)

• Command line access

Step-by-step guide

1. Install Pandoc.

   • Visit http://pandoc.org/installing.html

   • Download the installer for your operating system

   • Run the installer and follow the prompts

2. Open your command line and navigate to your document.

   cd path/to/your/latex/folder

3. Convert your document.

   For basic conversion:

   pandoc filename.tex -o output.html --mathjax

   Replace filename.tex with your actual file name.

   For a standalone HTML file with better styling:

   pandoc filename.tex -o output.html --mathjax --standalone --css=style.css

   Replace filename.tex and style.css with your actual file names. --mathjax uses MathJax to render equations. --standalone creates a complete HTML document with proper headers. --css=style.css lets you add custom styling (which is optional). Check out the Pandoc documentation for more information about your options.

4. View your HTML file. Open the output file in a web browser.

Tips

• Pandoc handles standard LaTeX well but might struggle with complex custom commands. Consider simplifying your LaTeX before conversion.

• If you have bibliographies, use --citeproc to process citations.

• For multiple chapters or sections, you can convert several files at once.

Workflow 3: LaTeX to HTML with Chirun Web

Chirun is designed specifically for creating accessible course materials. It converts LaTeX to HTML and can build a complete course website with navigation between multiple pages.

What you'll need

• Your LaTeX source file(s)

• Internet access

Step-by-step guide

1. Access the web frontend at https://lti.chirun.org.uk .

2. Select Create a new package.

3. Gather your file(s) via Upload files, then click Upload.

4. If you did not include a YAML file in your upload, you'll see ‘Your package didn't contain a config file, so we've created one. Please review the configuration’. Scroll down the page and add in your package metadata, license information, and build options.

   1. Note, you can simultaneously generate PDFs of your content by selecting Build PDFs.

   2. URL to load MathJax from can be left blank, as the default option is sufficient.

5. Click Save at the top of the page.

6. Select Download the generated content as a .zip file.

Tips

• You can include different types of content (PDFs, videos, external links) alongside your LaTeX documents.

• There is a Chirun command line interface (CLI) tool, though it has a larger learning curve and works best for Linux and Mac devices (with a workaround for Windows). Find out more on Chirun’s CLI documentation.

Workflow 4: R Markdown to HTML with Quarto

If R Markdown is your preferred language, Quarto helps to create accessible HTML output, even including HTML accessibility checks in your workflow.

What you'll need

• R and RStudio installed (download from the LSE App Store, also known as Self Service)

• Quarto installed (download from the LSE App Store, also known as Self Service)

• Your R Markdown files

Step-by-step guide

1. Install Quarto.

   • On Mac: Download Quarto from datajar.mobi > Self Service

   • On Windows laptops: Download Quarto from LSE App Store

   • On LSE Windows Desktops: Download Quarto from LSE Self Service

2. Convert your R Markdown to Quarto format. Open your .Rmd file in RStudio. Quarto works with R Markdown files directly, but you can rename them to .qmd if you prefer.

3. Add Quarto configuration. At the top of your document, update the YAML header:

   --- title: "Your Document Title" format: html: toc: true axe: true ---

   toc: true creates a Table of Contents.

   axe: true runs automated HTML accessibility checking using axe-core, an open-source accessibility package. Automated accessibility checking can catch some accessibility issues, such as colour contrast, but having no issues does not mean the document is fully accessible. Any accessibility concerns will show in the browser's console via the browser's developer tools.

4. Render to HTML.

   Option A: In RStudio

   • Click the Render button (it replaces the old Knit button)

   Option B: Command line

   quarto render filename.qmd

   Replace filename.qmd with your actual file name.

5. Review your HTML document. Quarto creates an HTML file in the same folder. Open it to check the output.

Tips

• Use code-fold: true to hide code by default, letting students reveal it when they want to see the details.

• Add toc: true for a table of contents, which helps with navigation.

Choosing the right workflow: A comparison

Adding your converted HTML document(s) to Moodle

1. Zip your folder containing your HTML file(s) and any supporting files, such as CSS or image files.

2. Go to your course page and Turn editing on. Scroll to the section where you would like your document(s) to be displayed, and click Add an activity or resource and pick File from the Resource tab.

Expand to view 'Add file resource' screenshot

Open

Select File from the Resources tab.

3. Like the typical File upload process, add a Name and an optional Description.

4. In the Select file area, either drag and drop your zipped folder or use the File picker to select your zipped folder.

Expand to view 'Select files' screenshot

Open

Add a file with the File picker '+' button or drag-and-drop your zipped folder to the specified area.

5. Click on the file to open a dialog window titled 'Edit <your file name>'. Select Unzip.

Expand to view 'unzip' screenshot

Open

Select Unzip.

6. Click on the unzipped folder, then click on your HTML file. If you have multiple HTML files, select your index.html file. Select Set main file, then Save.

Expand to view 'Set main file' screenshot

Open

Select Set main file.

7. Return to the root folder by selecting Files underneath the File picker button.

Expand to view 'return to root folder' screenshot

Open

Select Files to go back to the root folder.

8. Click on the original zip file, then select Delete. Confirm the deletion. The zip file is no longer needed.

9. Under Appearance, ensure that Display is set to New window.

Expand to view 'display new window' screenshot

Open

Set Display to New window.

10. Click Save and return to course. Your HTML file(s) are now on your course.

Next steps

Start with a small test document to try out your chosen workflow. Each tool has an active community, so you'll find plenty of help online if you run into difficulties.

Remember that converting to HTML is an ongoing process. As you create new materials, build accessibility into your workflow from the start rather than converting everything retrospectively.

If you need support with these tools or want to discuss which workflow suits your teaching, please get in touch with eden.digital@lse.ac.uk.