Add DOCX format support to pkgdown documentation #33

d-morrison · 2026-01-27T12:04:38Z

still necessary?

Yes, still necessary. The as_is: true setting tells pkgdown to include the Quarto-rendered HTML as-is without wrapping it in pkgdown's article template. This is needed because Quarto documents produce complete, self-contained HTML pages with their own styling and features. Without this setting, pkgdown would wrap the Quarto HTML in its own template, which could cause display issues with Quarto-specific elements like callouts, tabsets, and cross-references.

-Original file line number
+Diff line change
@@ Expand Up @@
 . Run `devtools::document()` to generate documentation
 . 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
@@ Expand Down @@

-Original file line number
+Diff line change
@@ -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",
@@ Expand Down Expand Up / @@ -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
       }
@@ Expand All / @@ -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('<li><a href="%s-revealjs.html"><i class="bi bi-file-slides"></i>RevealJS</a></li>', base_name))
+      }
+      if (has_docx) {
+        format_links <- c(format_links, sprintf('<li><a href="%s.docx"><i class="bi bi-file-word"></i>Word</a></li>', base_name))
+      }
       format_link_html <- sprintf('
     <div class="quarto-alternate-formats">
     <h2>Other Formats</h2>
     <ul>
-    <li><a href="%s-revealjs.html"><i class="bi bi-file-slides"></i>RevealJS</a></li>
+    %s
     </ul>
-    </div>', base_name)
+    </div>', 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
@@ Expand Down Expand Up / @@ -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)))
       }
@@ Expand Down @@

-Original file line number
+Diff line change
@@ Expand Up / @@ -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")
@@ Expand Down @@

-Original file line number
+Diff line change
@@ Expand Up / @@ -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
@@ Expand Down @@

-Original file line number
+Diff line change
@@ -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)
@@ Expand Down @@

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add DOCX format support to pkgdown documentation #33

Diff view

Diff view

There are no files selected for viewing

Uh oh!

d-morrison Jan 27, 2026

Uh oh!

Copilot AI Jan 27, 2026

Uh oh!

Uh oh!

-Original file line number
+Diff line change
@@ Expand Up / @@ -14,7 +14,4 @@ articles: @@
       navbar: ~
       contents:
       - getting-started
-      - quarto_vignette
-    - title: Advanced Topics
-      contents: articles/quarto_article

-Original file line number
+Diff line change
@@ Expand Up / @@ -3,13 +3,15 @@ CMD @@
     Callouts
     CodeFactor
     Codecov
+    DOCX
     Lifecycle
     RevealJS
     Tabsets
     ackage
     callout
     callouts
     cdot
+    docx
     emplate
     foldable
     frac
@@ Expand Down @@

-Original file line number
+Diff line change
@@ -1,2 +1,4 @@
     /.quarto/
     **/*.quarto_ipynb
+    *.docx
+    *-revealjs.html

-Original file line number
+Diff line change
@@ Expand Up / @@ -6,6 +6,8 @@ format: @@
       html: default
       revealjs:
         output-file: quarto_article-revealjs.html
+      docx:
+        output-file: quarto_article.docx
     pkgdown:
       as_is: true
     ---
@@ Expand Down Expand Up / @@ -220,6 +222,7 @@ print(result) # <4> @@
 . Apply the example function from the package
 . Display the results
+    ::: {.content-visible unless-format="docx"}
     ## Diagrams with Mermaid
     ```{mermaid}
@@ Expand All / @@ -230,6 +233,7 @@ flowchart LR @@
         C --> D[Output Results]
         D --> E[Visualize]
     ```
+    :::
     ## Mathematical Notation
@@ Expand Down @@

Add DOCX format support to pkgdown documentation #33

Are you sure you want to change the base?

Add DOCX format support to pkgdown documentation #33

Uh oh!

Uh oh!

Diff view

Diff view

There are no files selected for viewing

Uh oh!

d-morrison Jan 27, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 27, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!