Add portable CHM and PDF Markdown export

[johnml1135]

A help change is currently a 5 MB opaque binary diff. This publishes the same content as Markdown — one file per topic, with images, frontmatter and a full table of contents — on a markdown-export branch that nothing hand-edits. Diffs become readable text, one changed file per edited topic, and the AI bot ingests about 65% fewer tokens (~2.14M → ~759K) with the prose intact.

tools/convert.py builds the corpus; .github/workflows/markdown-export.yml validates every pull request and publishes on pushes to develop and on release tags. Each build also emits author-report.md for RoboHelp and PDF authors, and author-report.json for automation.

Verified: 2 CHMs, 1,630 topics, 13 PDFs, 583 images, 0 fatal — against both the CHM this branch was written against and the current one on develop. 222 tests and ruff run before anything publishes. Validation is green on this repo's own runners; publishing correctly skips on pull_request.

Two findings worth reading before merge: this workflow had never once run, and six links have been broken on the export branch since the first publish. Both are fixed here and explained in the comment below.

[johnml1135]

This workflow had never once run. jobs.validate.env referenced ${{ runner.temp }}, a context GitHub refuses in job-level env. That fails at load time, so every run ended in seconds with no jobs and no logs to diagnose it from. The export has never been built by CI.

Fixing that surfaced two more — and the last is not a CI bug at all. Six links have been broken on markdown-export since the first publish. Three Parser topics link to using_tools/texts_&_words_tools/… while those topics live under Using_Tools/Texts_&_Words_tools/…. RoboHelp resolves that case-insensitively, so the links open in the CHM and 404 on GitHub.

They stayed hidden behind Path.resolve(), which rewrites a path to its real on-disk case on Windows: a Windows build passed while Linux failed the same corpus. Link checking is now case-exact on every platform, the exporter republishes each link in the case its file really has, and the drift is reported to authors as a new source_link_case advisory.

Verified end to end on a fork, publish job included — 0 fatal against both the CHM this branch was written against and the current one on develop.

The three fixes

Fix	Effect
runner context out of job-level env	The workflow parses, so it can run at all
--repo . under uv run --directory src	--repo src resolved to src/src, dying before one topic converted
Case-exact link checking, canonicalized output	Six live 404s corrected; Windows and Linux now agree

Each has a regression test. The suite is 222 tests plus ruff, both run by validation before anything publishes.

Verification

Build	Fatal	Advisory
CHM this branch was written against	0	276
CHM at current develop, merged in here	0	255

The recent link repairs on develop clear 21 advisories: missing links 16→0, duplicate titles 4→0, stale TOC 1→0. The six case mismatches remain, and are now reported rather than silently published.

Publishing safety

Publishing is a separate job behind needs: validate, holding the only contents: write permission. It runs on push and non-dry-run dispatch, never on pull_request, and appends to markdown-export rather than force-pushing it. Pandoc is pinned by SHA-256, and every action by commit SHA.

Two things for a maintainer: GITHUB_TOKEN needs contents: write — the job declares it, but if this org restricts default workflow permissions the publish step fails on first run. And markdown-export does not exist here yet; the job creates it as an orphan branch on that first run, which also fixes the README's ../../tree/markdown-export link.

[MarlonH]

Six links have been broken on markdown-export since the first publish Three Parser topics link to using_tools/texts_&_words_tools/... while the topics live under Using_Tools/Texts_&_Words_tools/.... RoboHelp resolves that case-insensitively, so the links open in the CHM and 404 on GitHub. So is it 6 or 3? I reset each link I could find in Parser topics that pointed to T & Wds overview. I have not pushed the updates to the Amazon bucket yet because I think there are some updates/changes in Help that are not yet out in the world.... only patches

…

________________________________ From: John Lambert ***@***.***> Sent: Wednesday, September 9, 2026 2:29 PM To: sillsdev/FwHelps ***@***.***> Cc: Subscribed ***@***.***> Subject: Re: [sillsdev/FwHelps] Add portable CHM and PDF Markdown export (PR #3) [https://avatars.githubusercontent.com/u/13733556?s=20&v=4]johnml1135 left a comment (sillsdev/FwHelps#3)<#3 (comment)> The workflow on this branch had never successfully run. Three fixes, each verified end to end on a fork before posting here. The workflow never loaded jobs.validate.env referenced ${{ runner.temp }}, a context GitHub does not evaluate in job-level env. That is a load-time error, so every run ended in seconds with no jobs and no logs to diagnose it from — the export has never actually been built by CI. The three build paths are now resolved from $RUNNER_TEMP in a first step. The convert step pointed one directory too deep uv run --directory src already moves into the checkout, so --repo src resolved to src/src and the build died before converting a topic. Now --repo .. Six links have been broken on markdown-export since the first publish Three Parser topics link to using_tools/texts_&_words_tools/... while the topics live under Using_Tools/Texts_&_Words_tools/.... RoboHelp resolves that case-insensitively, so the links open in the CHM and 404 on GitHub. They stayed invisible because corpus_validation resolved link targets with Path.resolve(), which on Windows rewrites a path to its real on-disk case — a Windows build passed while Linux failed. .. is now normalized lexically and existence is checked against the emitted paths, which is case-exact on every platform. The exporter canonicalizes link case against the extracted source before conversion, so a working link ships now, and reports the drift as a new source_link_case advisory so the RoboHelp source can be corrected at leisure. Verification Full pipeline green on johnml1135/FwHelps, including the publish job writing to markdown-export: Build Fatal Advisory CHM at the time this branch was written 0 276 CHM at current develop (merged in here) 0 255 The recent link repairs on develop clear 21 advisories — missing links 16 to 0, duplicate titles 4 to 0, stale TOC 1 to 0. The 6 case mismatches remain and are now reported to authors. Each fix has a regression test; the suite is 222 tests plus ruff, both run by the validate job before anything is published. Two things worth a maintainer's eye * GITHUB_TOKEN needs contents: write. The publish job declares it, but if this org restricts default workflow permissions the publish step will fail on the first run. Everything else is proven. * markdown-export does not exist on this repo yet. The publish job creates it as an orphan branch on the first run, which also fixes the README's ../../tree/markdown-export link. Publishing is a separate job behind needs: validate, runs only on push and non-dry-run dispatch, never on pull_request, and never force-pushes. — Reply to this email directly, view it on GitHub<#3?email_source=notifications&email_token=AAUU3TSCYSLAODZMNSZQHLD5OGVQZA5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTKNRQG42TENJUGQZ2M4TFMFZW63VKON2WE43DOJUWEZLEUVSXMZLOOSWGM33PORSXEX3DNRUWG2Y#issuecomment-5607525443>, or unsubscribe<https://github.com/notifications/unsubscribe-auth/AAUU3TRX55L7OBRU6BFZTCL5OGVQZAVCNFSNUABDKJSXA33TNF2G64TZHM2TOMBWGIYDGO2JONZXKZJ3GUZDCNRTHE3DCOBTUF3AE>. Triage notifications, keep track of coding agent tasks and review pull requests on the go with GitHub Mobile for iOS<https://github.com/notifications/mobile/ios/AAUU3TU3T2MUHVN5V57ZSKT5OGVQZA5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTKNRQG42TENJUGQZ2M4TFMFZW63VKON2WE43DOJUWEZLEUVSXMZLOOSVGM33PORSXEX3JN5ZQ> and Android<https://github.com/notifications/mobile/android/AAUU3TW7NIFJOJUUXXPCUO35OGVQZA5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTKNRQG42TENJUGQZ2M4TFMFZW63VKON2WE43DOJUWEZLEUVSXMZLOOSXGM33PORSXEX3BNZSHE33JMQ>. Download it today! You are receiving this because you are subscribed to this thread.Message ID: ***@***.***>

[johnml1135]

6 links across 3 topics — 2 in each. "Three" was topics, "six" was links; that read ambiguously, sorry.

Your repairs did land. Every Texts_and_Words_overview.htm and interlinear_views_colors.htm link in those three topics is now correct case. The six that remain point at two other files, which is why searching for the T & Wds overview link wouldn't have surfaced them:

Topic (User_Interface/Menus/Parser/)	Wrong-case targets
Default_XAmple_parser_overview.htm	Analyze_Text_overview.htm, specify_the_word_gloss.htm
Parsing_words_overview.htm	the same two
Phonological_Rule_Based_parser_overview.htm	the same two

All six spell it using_tools/texts_&_words_tools/…; the files live at Using_Tools/Texts_&_Words_tools/…. Verified against the CHM currently on develop, so with your fixes already in.

Parsing_words_overview.htm shows it most clearly — it links to Analyze_Text_overview.htm twice, once as Using_Tools/Texts_%26_Words_tools/… and once as using_tools/texts_&_words_tools/…. Same source topic, same destination, two different spellings.

Nothing is blocked on this. The exporter republishes all six in the case the files really have, so the Markdown branch is correct as of this PR. The advisory only records that the RoboHelp source still differs — worth tidying whenever it suits, not before merge.

Your other repairs cleared 21 advisories: missing links 16→0, duplicate titles 4→0, stale TOC 1→0.

On the S3 bucket — no interaction. The export reads the CHM committed to this repo, so it tracks what's on develop regardless of when the bucket is refreshed.