docs: convert vignettes to .md for GitHub rendering - #73
Merged
Conversation
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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
GitHub renders
.Rmdfiles 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..Rmd→.md, old files deleted): faq, redcap-troubleshooting, google-troubleshooting, abs-troubleshooting, docker-troubleshooting, ci-troubleshooting# titlekept),{r ... eval=FALSE}/{bash, eval=FALSE}chunk fences → plain fenced code blocks (display-only — plain Markdown cannot execute code), one stale prose parenthetical "(eval = FALSEin every chunk)" → "(plain Markdown, so GitHub renders it without running anything)".mdvignettes/faq.mdvignettes/faq.md; fenced-block extraction now detects code blocks by content (comment/assignment/Rscript/env-var lines) since.mdhas no{r}chunk headers; eval=FALSE chunk test replaced with a no-knitr-fences guard (hermeticity trivially satisfied by plain Markdown)VignetteBuilder: knitr+Suggests: knitrremoved (dead config with no.Rmdleft; knitr stays installed via rmarkdown Imports, renv.lock untouched)Verification
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:repo_read("Makefile")can't open the file (Makefile isn't in the check tarball; the guard is designed fordevtools::test(), notR CMD check) + 2file.exists()failures in test-run-initial-function (extdata paths resolved against the check dir).mdfiles (no ERROR, build completes); they're just not recognized as vignettes. Options: (a) accept the WARNING+NOTE as-is, (b) move.mddocs to adocs-md/folder outsidevignettes/(your suggested alternative — then update README/skill/test paths too), (c) excludevignettes/via.Rbuildignore. I did NOT pick — flagging per the task instructions..Rmdgrep: 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)
Still stuck?section) updated.Rmd→.md— Task 1 said preserve links verbatim, but the.Rmdtargets are deleted, so leaving them would 404. Links must follow the rename.eval = FALSEin every chunk" is false for a file with no chunks.Test plan
Rscript -e 'devtools::test()'— 490 PASS / 0 FAILmake lint— before/after compared (see above), only the expected vignette WARNING+NOTE added.Rmdgrep — zero live refsACs
N/A — fast-track, no linked issue.