1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118---
title: Tutorial — Process your first PDF with WordPress
date: 2026-04-16
author: Equalify Tech Team
description: Install the Equalify Reflow for WordPress plugin, configure it against a running Reflow instance, and convert your first PDF end-to-end.
---
# Tutorial: Process your first PDF with WordPress
By the end of this walkthrough you will have installed the Equalify Reflow for WordPress plugin, pointed it at a running Reflow API, and converted a real PDF from the Media Library into an accessible viewer page. Plan for **~20 minutes** on a site that already has WordPress running.
For day-to-day reference on the plugin's features, see [use the WordPress plugin](../how-to/use-the-wordpress-plugin.md). This tutorial walks you through the path end-to-end; that page is the task reference after you're set up.
## What you need
- **A WordPress site** (single or multisite) where you have administrator access. WordPress 6.0+ recommended.
- **A Reflow API instance** you can reach over HTTPS and its `X-API-Key` credential. If your organisation uses the UIC-hosted instance, that's `https://reflow.equalify.uic.edu`; partners receive the API key through onboarding.
- **A PDF** already uploaded to your Media Library, or one you'll upload during the tutorial.
If you don't yet have partner access, see [getting started § partners](../getting-started.md#for-partners).
## 1. Install the plugin
Download the latest release from the [equalify-reflow-wp releases page](https://github.com/EqualifyEverything/equalify-reflow-wp/releases) and extract it into your WordPress plugins directory:
```bash
unzip equalify-reflow-wp-*.zip -d wp-content/plugins/
```
In the WordPress admin, go to **Plugins > Installed Plugins** and activate **Equalify Reflow**. On a multisite, use **Network Activate** instead so individual sites can configure their own API targets.
## 2. Configure the API connection
Navigate to **Settings > Equalify Reflow** and fill in:
- **API URL** — the base URL of your Reflow instance, e.g. `https://reflow.equalify.uic.edu`
- **API Key** — the `X-API-Key` you were provided
- **Client API URL** — leave blank unless your server-side and browser-side addresses differ (common only in local Docker setups)
Save. The plugin does a quick connectivity check; if the green "Connected" indicator doesn't appear, see [Troubleshooting](#troubleshooting) below.
## 3. Upload or find a PDF
In the WordPress admin, go to **Media > Library**. Either upload a new PDF or click an existing one. The attachment detail panel opens.
Scroll to the **Equalify Reflow** section. If the plugin is configured correctly, you'll see a **Run Equalify Reflow** button.
## 4. Start the conversion
Click **Run Equalify Reflow**.
The plugin submits the PDF to the Reflow API and shows a progress bar for the five public phases:
1. **Extraction** — Docling parses the PDF structure
2. **Analysis** — document classification and outline
3. **Headings** — heading hierarchy normalisation
4. **Translation** — per-page content and formatting fixes
5. **Assembly** — cross-page boundary fixes and cleanup
Expected duration for a 6–10 page document: **~2–5 minutes**. Larger documents or ones with complex layouts scale roughly linearly. If the SSE connection drops, the plugin falls back to polling every 5 seconds; you'll see progress continue.
## 5. See the accessible viewer
When processing completes, the attachment panel shows:
- **Status: Ready**
- A link to the public viewer at `/equalify-reflow/{attachment-id}/{slug}/`
Open the viewer link. You should see:
- The document rendered as accessible HTML
- A **table of contents** down the side, generated from the document's headings
- A **search** box that highlights matches across the document
- Download links for the original PDF and the accessible markdown
Click through the table of contents to confirm the heading hierarchy matches what you'd expect for this document. This is the single most important quality check — see [interpret the output](../how-to/interpret-the-output.md) for the full 4-minute quality scan.
## 6. Check the media library updated
Back in **Media > Library**, notice:
- The extracted figures from the PDF are now separate Media Library entries (they're "attached" to the original PDF)
- Each figure has alt text generated by the pipeline's image subagent
## 7. Explore what else the plugin does
Now that the document is processed, the plugin has automatically activated a few features:
- **PDF link annotation** — anywhere you link to this PDF in a post or page, an accessibility icon appears next to the link. Clicking it opens the accessible viewer instead of downloading the PDF.
- **Document index** — `/equalify-reflow/` lists every processed and enabled document on the site.
- **Download bundle** — append `/download/` to the viewer URL to get a ZIP of the markdown plus figures.
## 8. Enable feedback (optional)
In **Settings > Equalify Reflow**, turn on **Enable Feedback** and point it at a feedback service (e.g. `https://feedback.equalify.example/api`). Readers of the accessible viewer can now:
- Report issues with category tagging (content, formatting, accessibility, structure)
- Propose specific text corrections (select text → suggest edit)
Feedback flows to the centralised [Equalify Reflow Feedback Service](https://github.com/EqualifyEverything/equalify-reflow-feedback), which aggregates reports across every connected WordPress site and informs pipeline improvements.
## Troubleshooting
| Problem | First thing to try |
|---|---|
| "Connection failed" when saving settings | Confirm the API URL is reachable from the WordPress server (not just your browser) — try `curl -H "X-API-Key: $KEY" $API_URL/health` from SSH. |
| Progress bar stuck at 0% | Browser console may show SSE errors. The plugin falls back to polling; give it 30 seconds. |
| Processing completes but figures don't appear | Check `wp-content/uploads/` is writable by the web server. |
| Viewer URL returns 404 | Go to **Settings > Permalinks > Save Changes** (no changes needed, just save — this flushes rewrite rules). |
| Processing completes suspiciously fast with poor-quality output | The Reflow instance's AWS Bedrock or Anthropic credentials likely expired on the server side. Ask the instance operator to refresh credentials and restart. |
## Where to go next
- [Use the WordPress plugin](../how-to/use-the-wordpress-plugin.md) — day-to-day reference (managing documents, re-processing, multisite setup)
- [Interpret the output](../how-to/interpret-the-output.md) — the reviewer's quality checklist
- [Provide feedback](../how-to/provide-feedback.md) — how to submit corrections and issue reports
- [How it works](../explanation/how-it-works.md) — what the pipeline is actually doing during those five phases