diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
index dfc640e..50da71a 100644
--- a/.github/copilot-instructions.md
+++ b/.github/copilot-instructions.md
@@ -31,6 +31,18 @@ The repository includes a `.github/workflows/copilot-setup-steps.yml` workflow t
6. Run `devtools::document()` to generate documentation
7. Run `devtools::check()` to validate your package
+## Version Management
+
+**CRITICAL**: When creating a new branch or PR from main, ALWAYS increment the development version number in the DESCRIPTION file to one version past the current main branch version.
+
+For example:
+- If main branch has version `0.0.0.9005`
+- Your new branch MUST have version `0.0.0.9006`
+
+This ensures that package versions remain unique across branches and prevents version conflicts.
+
+**Before finishing each coding session**: Fetch the main branch and increment the development version if your branch is not ahead of main, before committing and requesting review again.
+
## Development Workflow
### Building and Checking
diff --git a/.github/scripts/add-format-links.R b/.github/scripts/add-format-links.R
index e473a1b..47136bf 100755
--- a/.github/scripts/add-format-links.R
+++ b/.github/scripts/add-format-links.R
@@ -1,12 +1,12 @@
#!/usr/bin/env Rscript
# Post-process pkgdown HTML files to add "Other Formats" links
-# This script adds links to RevealJS presentations in the pkgdown HTML output
+# This script adds links to RevealJS presentations and DOCX documents in the pkgdown HTML output
cat("Adding format links to pkgdown articles...\n")
cat(sprintf("Working directory: %s\n", getwd()))
-# Find all HTML files in docs/articles that have corresponding RevealJS versions
+# Find all HTML files in docs/articles that have corresponding alternate format versions
# Exclude the RevealJS files themselves (those ending with -revealjs.html)
html_files <- list.files(
path = "docs/articles",
@@ -43,10 +43,17 @@ for (html_file in html_files) {
# Check if there's a corresponding RevealJS file
revealjs_file <- file.path("docs/articles", paste0(base_name, "-revealjs.html"))
+ # Check if there's a corresponding DOCX file
+ docx_file <- file.path("docs/articles", paste0(base_name, ".docx"))
+
cat(sprintf("Checking for RevealJS file: %s\n", revealjs_file))
+ cat(sprintf("Checking for DOCX file: %s\n", docx_file))
+
+ has_revealjs <- file.exists(revealjs_file)
+ has_docx <- file.exists(docx_file)
- if (!file.exists(revealjs_file)) {
- cat(sprintf(" RevealJS file not found, skipping %s\n", basename(html_file)))
+ if (!has_revealjs && !has_docx) {
+ cat(sprintf(" No alternate format files found, skipping %s\n", basename(html_file)))
next
}
@@ -55,14 +62,22 @@ for (html_file in html_files) {
# Read the HTML content
html_content <- readLines(html_file, warn = FALSE)
- # Create the format link HTML
+ # Build the format links HTML
+ format_links <- character()
+ if (has_revealjs) {
+ format_links <- c(format_links, sprintf('
RevealJS', base_name))
+ }
+ if (has_docx) {
+ format_links <- c(format_links, sprintf('Word', base_name))
+ }
+
format_link_html <- sprintf('
', base_name)
+', paste(format_links, collapse = "\n"))
# Find the location to insert the link (after the TOC, before main content)
# Look for the nav closing tag or the main content div
@@ -99,7 +114,12 @@ for (html_file in html_files) {
# Write the modified HTML back
writeLines(html_content, html_file)
- cat(sprintf(" Added RevealJS link to %s\n", basename(html_file)))
+
+ # Report what was added
+ added_formats <- character()
+ if (has_revealjs) added_formats <- c(added_formats, "RevealJS")
+ if (has_docx) added_formats <- c(added_formats, "DOCX")
+ cat(sprintf(" Added %s link(s) to %s\n", paste(added_formats, collapse = " and "), basename(html_file)))
} else {
cat(sprintf(" Could not find insertion point in %s\n", basename(html_file)))
}
diff --git a/.github/scripts/pre-render-quarto.R b/.github/scripts/pre-render-quarto.R
index 2e6490a..8e9a646 100755
--- a/.github/scripts/pre-render-quarto.R
+++ b/.github/scripts/pre-render-quarto.R
@@ -27,15 +27,41 @@ if (length(qmd_files) == 0) {
errors <- character()
for (qmd_file in qmd_files) {
cat(sprintf("Rendering %s...\n", qmd_file))
- tryCatch({
- # Render to all formats specified in the document YAML
- quarto::quarto_render(qmd_file, output_format = "all", quiet = FALSE)
- cat(sprintf("Successfully rendered %s\n", qmd_file))
- }, error = function(e) {
- error_msg <- sprintf("Error rendering %s: %s", qmd_file, e$message)
- cat(error_msg, "\n")
- errors <<- c(errors, error_msg)
- })
+
+ # Get the formats defined in the file's YAML
+ # We'll render each format separately to avoid hanging issues
+ formats_to_render <- c("html", "revealjs", "docx")
+
+ for (format in formats_to_render) {
+ # Try up to 2 times in case of transient failures
+ max_attempts <- 2
+ attempt <- 1
+ success <- FALSE
+
+ while (attempt <= max_attempts && !success) {
+ tryCatch({
+ if (attempt > 1) {
+ cat(sprintf("Retry attempt %d for %s to %s\n", attempt, qmd_file, format))
+ Sys.sleep(2) # Small delay before retry
+ }
+ # Render to specific format
+ quarto::quarto_render(qmd_file, output_format = format, quiet = FALSE)
+ cat(sprintf("Successfully rendered %s to %s\n", qmd_file, format))
+ success <- TRUE
+ }, error = function(e) {
+ error_msg <- sprintf("Error rendering %s to %s (attempt %d): %s", qmd_file, format, attempt, e$message)
+ cat(error_msg, "\n")
+ if (attempt >= max_attempts) {
+ errors <<- c(errors, error_msg)
+ }
+ attempt <<- attempt + 1
+ })
+
+ if (!success) {
+ attempt <- attempt + 1
+ }
+ }
+ }
}
cat("Pre-rendering complete!\n")
diff --git a/.github/workflows/pkgdown.yaml b/.github/workflows/pkgdown.yaml
index 5a6b038..9539339 100644
--- a/.github/workflows/pkgdown.yaml
+++ b/.github/workflows/pkgdown.yaml
@@ -118,11 +118,32 @@ jobs:
id: build
shell: Rscript {0}
run: |
+ # Build the site (Quarto articles are not in _pkgdown.yml to prevent pkgdown from rendering them)
pkg <- pkgdown::as_pkgdown(".")
- # Build the site locally
pkgdown::build_site(pkg, preview = FALSE, install = FALSE)
-
- - name: Post-process to add RevealJS format links
+
+ # Copy pre-rendered Quarto HTML files and alternate formats to docs/articles
+ quarto_files <- c(
+ "vignettes/quarto_vignette.html",
+ "vignettes/articles/quarto_article.html"
+ )
+ for (src in quarto_files) {
+ if (file.exists(src)) {
+ dest <- file.path("docs/articles", basename(src))
+ file.copy(src, dest, overwrite = TRUE)
+ cat("Copied:", src, "to", dest, "\n")
+ }
+ }
+
+ # Copy alternate format files (RevealJS and DOCX)
+ alt_files <- list.files("vignettes", pattern = "(-revealjs\\.html|\\.docx)$", full.names = TRUE, recursive = TRUE)
+ for (src in alt_files) {
+ dest <- file.path("docs/articles", basename(src))
+ file.copy(src, dest, overwrite = TRUE)
+ cat("Copied alternate format:", src, "to", dest, "\n")
+ }
+
+ - name: Post-process to add alternate format links
run: |
set -e
Rscript .github/scripts/add-format-links.R
diff --git a/NEWS.md b/NEWS.md
index 1ce9631..0d16401 100644
--- a/NEWS.md
+++ b/NEWS.md
@@ -1,5 +1,8 @@
# rpt (development version)
+* Added DOCX (Word document) format for Quarto vignettes and articles in pkgdown documentation, alongside existing RevealJS format. HTML pages now display an "Other Formats" section with links to both slide and Word document versions
+ * Fixed rendering issue by rendering each format separately instead of using "all" to avoid hanging
+ * Conditionally excluded Mermaid diagrams from DOCX format using `.content-visible unless-format="docx"` (Mermaid diagrams remain in HTML and RevealJS outputs)
* Updated lintr configuration to match serodynamics reference with enhanced linter rules
* PR preview comments now use `recreate: true` to ensure they always appear at the bottom of the PR conversation, preventing them from being hidden in collapsed sections (#31)
diff --git a/_pkgdown.yml b/_pkgdown.yml
index 5f84df2..6571237 100644
--- a/_pkgdown.yml
+++ b/_pkgdown.yml
@@ -14,7 +14,4 @@ articles:
navbar: ~
contents:
- getting-started
- - quarto_vignette
-- title: Advanced Topics
- contents: articles/quarto_article
diff --git a/inst/WORDLIST b/inst/WORDLIST
index f08dbe0..9872110 100644
--- a/inst/WORDLIST
+++ b/inst/WORDLIST
@@ -3,6 +3,7 @@ CMD
Callouts
CodeFactor
Codecov
+DOCX
Lifecycle
RevealJS
Tabsets
@@ -10,6 +11,7 @@ ackage
callout
callouts
cdot
+docx
emplate
foldable
frac
diff --git a/vignettes/.gitignore b/vignettes/.gitignore
index ad29309..723352b 100644
--- a/vignettes/.gitignore
+++ b/vignettes/.gitignore
@@ -1,2 +1,4 @@
/.quarto/
**/*.quarto_ipynb
+*.docx
+*-revealjs.html
diff --git a/vignettes/articles/quarto_article.qmd b/vignettes/articles/quarto_article.qmd
index 2d1aa7f..fa15a71 100644
--- a/vignettes/articles/quarto_article.qmd
+++ b/vignettes/articles/quarto_article.qmd
@@ -6,6 +6,8 @@ format:
html: default
revealjs:
output-file: quarto_article-revealjs.html
+ docx:
+ output-file: quarto_article.docx
pkgdown:
as_is: true
---
@@ -220,6 +222,7 @@ print(result) # <4>
3. Apply the example function from the package
4. Display the results
+::: {.content-visible unless-format="docx"}
## Diagrams with Mermaid
```{mermaid}
@@ -230,6 +233,7 @@ flowchart LR
C --> D[Output Results]
D --> E[Visualize]
```
+:::
## Mathematical Notation
diff --git a/vignettes/quarto_vignette.qmd b/vignettes/quarto_vignette.qmd
index b59b215..176b983 100644
--- a/vignettes/quarto_vignette.qmd
+++ b/vignettes/quarto_vignette.qmd
@@ -4,6 +4,8 @@ format:
html: default
revealjs:
output-file: quarto_vignette-revealjs.html
+ docx:
+ output-file: quarto_vignette.docx
pkgdown:
as_is: true
vignette: >