Skip to content

docs: convert vignettes to .md for GitHub rendering - #73

Merged
mcmullarkey merged 4 commits into
mainfrom
vignettes-to-md
Aug 14, 2026
Merged

docs: convert vignettes to .md for GitHub rendering#73
mcmullarkey merged 4 commits into
mainfrom
vignettes-to-md

Conversation

@mcmullarkey

Copy link
Copy Markdown
Collaborator

Summary

GitHub renders .Rmd files as raw source, so the 6 troubleshooting vignettes were unreadable on the repo. Converted them to plain Markdown (.md) so GitHub renders them as formatted pages.

  • 6 vignettes converted (.Rmd.md, old files deleted): faq, redcap-troubleshooting, google-troubleshooting, abs-troubleshooting, docker-troubleshooting, ci-troubleshooting
  • Content preserved verbatim (prose, tables, headings, links) except: knitr/rmarkdown YAML frontmatter removed (plain # title kept), {r ... eval=FALSE} / {bash, eval=FALSE} chunk fences → plain fenced code blocks (display-only — plain Markdown cannot execute code), one stale prose parenthetical "(eval = FALSE in every chunk)" → "(plain Markdown, so GitHub renders it without running anything)"
  • README Troubleshooting section: links + wording updated for .md
  • abmdash-guide skill: vignettes link → vignettes/faq.md
  • test-faq-verbatim.R: reads vignettes/faq.md; fenced-block extraction now detects code blocks by content (comment/assignment/Rscript/env-var lines) since .md has no {r} chunk headers; eval=FALSE chunk test replaced with a no-knitr-fences guard (hermeticity trivially satisfied by plain Markdown)
  • DESCRIPTION: VignetteBuilder: knitr + Suggests: knitr removed (dead config with no .Rmd left; knitr stays installed via rmarkdown Imports, renv.lock untouched)

Verification

  • Tests: devtools::test()490 PASS / 0 FAIL / 0 WARN (faq-verbatim context: 61 assertions, including all verbatim error-string + OKF-link checks)
  • make lint (devtools::check()) before/after:
    • Before (main): 1 ERROR, 5 WARNINGs, 4 NOTEs
    • After: 1 ERROR, 6 WARNINGs, 5 NOTEs
    • Same 1 ERROR on both (pre-existing, NOT caused by this change): 3 test failures under R CMD check — repo_read("Makefile") can't open the file (Makefile isn't in the check tarball; the guard is designed for devtools::test(), not R CMD check) + 2 file.exists() failures in test-run-initial-function (extdata paths resolved against the check dir)
    • +1 WARNING +1 NOTE — the expected vignette issue, flagged for your decision:
      • WARNING "checking files in 'vignettes' ... Files in the 'vignettes' directory but no files in 'inst/doc'"
      • NOTE "checking package vignettes ... Package has 'vignettes' subdirectory but apparently no vignettes."
      • R CMD build tolerates the .md files (no ERROR, build completes); they're just not recognized as vignettes. Options: (a) accept the WARNING+NOTE as-is, (b) move .md docs to a docs-md/ folder outside vignettes/ (your suggested alternative — then update README/skill/test paths too), (c) exclude vignettes/ via .Rbuildignore. I did NOT pick — flagging per the task instructions.
  • Stray .Rmd grep: zero live references outside git history. Remaining hits are only in .opencode/plans/repo-usability/ — historical committed plan/spec records for the completed feature (they document what existed at the time; not live docs, left untouched).

Deviations (reported honestly)

  1. faq.md internal cross-links (Still stuck? section) updated .Rmd.md — Task 1 said preserve links verbatim, but the .Rmd targets are deleted, so leaving them would 404. Links must follow the rename.
  2. One prose parenthetical in faq.md updated (see Summary) — "eval = FALSE in every chunk" is false for a file with no chunks.
  3. No changes to R/ source, workflows, docs/ (dashboard), or .Rbuildignore — check did not demand any.

Test plan

  • Rscript -e 'devtools::test()' — 490 PASS / 0 FAIL
  • make lint — before/after compared (see above), only the expected vignette WARNING+NOTE added
  • Stray-.Rmd grep — zero live refs

ACs

N/A — fast-track, no linked issue.

GitHub shows raw source for .Rmd files; plain Markdown renders as
formatted pages. Convert all 6 troubleshooting vignettes to .md:

- strip knitr/rmarkdown YAML frontmatter, keep plain markdown titles
- convert {r}/{bash} chunk fences to plain fenced code blocks
  (display-only; plain Markdown cannot execute code)
- preserve all prose, tables, headings verbatim
- update faq.md internal cross-links to the renamed .md vignettes
- update README Troubleshooting section + abmdash-guide skill link
- read vignettes/faq.md instead of faq.Rmd
- fenced-block extraction now detects code blocks by content (comment/
  assignment/Rscript/env-var lines) since .md has no {r} chunk headers
- replace the eval=FALSE chunk test with a no-knitr-fences guard
  (plain Markdown cannot execute code, so hermeticity is trivially
  satisfied; the guard stops chunk fences from creeping back)
- README pointer assertion now expects vignettes/faq.md
No .Rmd vignettes remain, so VignetteBuilder: knitr and Suggests:
knitr are dead config. knitr stays installed via rmarkdown (Imports),
so the renv.lock entry is untouched.
@mcmullarkey
mcmullarkey merged commit d35af4b into main Aug 14, 2026
1 check passed
@mcmullarkey
mcmullarkey deleted the vignettes-to-md branch August 14, 2026 00:05
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant