Merge pull request #785 from CDLUC3/bug/JS-fix-issue-with-docx-download-fonts

Switched to using pandoc to address issue with font sizes in downloading .docx files

Author: jupiter007

Dockerfile

@@ -40,7 +40,8 @@ RUN apt-get -qqy update \
                           shared-mime-info \
 		                  nodejs -qqy \
                           chromium \
-    && rm -rf /var/lib/apt/lists/*
+                      pandoc \
+  && rm -rf /var/lib/apt/lists/*
 
 # Always run Node in Production for the ECS hosted environments
 ENV NODE_ENV=production

Dockerfile.dev

@@ -16,6 +16,7 @@ RUN set -ex \
     libssl-dev libstdc++6 libtool libx11-6 libx11-xcb1 libxcb1 libxcomposite1 \
     libxcursor1 libxdamage1 libxext6 libxfixes3 libxi6 libxrandr2 \
     libxrender1 libxss1 libxtst6 libyaml-dev locales lsb-release mtr \
+    pandoc \
     shared-mime-info tzdata vim wget xdg-utils xfonts-base \
     xfonts-75dpi xz-utils yarn \
     python3 make \

app/controllers/plan_exports_controller.rb

@@ -117,10 +117,40 @@ def show_text
   end
 
   def show_docx
-    # Using and optional locals_assign export_format
-    render docx: "#{file_name}.docx",
-           content: clean_html_for_docx_creation(render_to_string(partial: 'shared/export/plan',
-                                                                  locals: { export_format: 'docx' }))
+    # Use Pandoc for better HTML->DOCX conversion (handles CSS font-size correctly)
+    begin
+      html = render_to_string(partial: 'shared/export/plan', locals: { export_format: 'docx' })
+      
+      docx_path = Rails.root.join('tmp', "#{file_name}.docx")
+      html_path = Rails.root.join('tmp', "#{file_name}.html")
+      
+      # Write HTML to temp file for Pandoc
+      File.write(html_path, html)
+      
+      # Convert using Pandoc with reference document for styling
+      reference_doc = Rails.root.join('lib', 'templates', 'pandoc_reference.docx')
+      result = system('pandoc', '-f', 'html', '-t', 'docx', 
+                      "--reference-doc=#{reference_doc}", 
+                      '-o', docx_path.to_s, html_path.to_s)
+
+      if result && File.exist?(docx_path)
+        send_data File.read(docx_path, mode: 'rb'),
+                  filename: "#{file_name}.docx",
+                  type: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document'
+      else
+        raise "Pandoc conversion failed"
+      end
+    rescue StandardError => e
+      Rails.logger.error("Unable to generate DOCX with Pandoc: #{e.message}")
+      # Fallback to htmltoword method if pandoc fails for any reason
+      render docx: "#{file_name}.docx",
+             content: clean_html_for_docx_creation(render_to_string(partial: 'shared/export/plan',
+                                                                    locals: { export_format: 'docx' }))
+    ensure
+      # Cleanup temp files
+      File.delete(html_path) if File.exist?(html_path)
+      File.delete(docx_path) if File.exist?(docx_path)
+    end
   end
 
   def show_pdf

app/views/branded/shared/export/_plan.erb

@@ -22,7 +22,10 @@
       <% if @hash[:all_phases] || (@selected_phase.present? && phase[:title] == @selected_phase.title) %>
         <%# Page break before each phase %>
         <div style="page-break-before:always;"></div>
-        <h1><%= download_plan_page_title(@plan, phase, @hash) %></h1>
+        <%# Skip H1 for DOCX - Pandoc converts HTML <title> to Word Title style, making H1 redundant %>
+        <% unless local_assigns[:export_format] == 'docx' %>
+          <h1><%= download_plan_page_title(@plan, phase, @hash) %></h1>
+        <% end %>
         <% phase[:sections].each do |section| %>
           <% if display_section?(@hash[:customization], section, @show_custom_sections) && num_section_questions(@plan, section, phase) > 0 %>
             <% if @show_sections %>
@@ -42,7 +45,8 @@
 
                 <% if @show_questions %>
                   <% if (@show_unanswered && blank) || !blank %>
-                    <h3><%=  sanitize question[:text].to_s, scrubber: TableFreeScrubber.new %></h3>
+                    <%# Strip <p> tags to prevent invalid HTML structure (<h3><p>...</p></h3>) %>
+                    <h3><%=  sanitize(question[:text].to_s, scrubber: TableFreeScrubber.new).gsub(/<\/?p>/, '').html_safe %></h3>
                   <% end %>
                 <% end %>
 

app/views/shared/export/_plan.erb

@@ -22,8 +22,11 @@
       <% if @hash[:all_phases] || (@selected_phase.present? && phase[:title] == @selected_phase.title) %>
         <%# Page break before each phase %>
         <div style="page-break-before:always;"></div>
-        <h1><%= download_plan_page_title(@plan, phase, @hash) %></h1>
-        <hr />
+        <%# Skip H1 for DOCX - Pandoc converts HTML <title> to Word Title style, making H1 redundant %>
+        <% unless local_assigns[:export_format] == 'docx' %>
+          <h1><%= download_plan_page_title(@plan, phase, @hash) %></h1>
+          <hr />
+        <% end %>
         <% phase[:sections].each do |section| %>
           <% if display_section?(@hash[:customization], section, @show_custom_sections) && num_section_questions(@plan, section, phase) > 0 %>
             <% if @show_sections %>
@@ -41,11 +44,12 @@
                   <% blank = answer.present? ? answer.blank? : true %>
                   <% options = answer.present? ? answer.question_options : [] %>
                   <% if @show_unanswered %>
+                    <%# Strip <p> tags to prevent invalid HTML (<strong><p>...</p></strong> or <div><p>...</p></div>) %>
                     <%# Hack: for DOCX export - otherwise, bold highlighting of question inconsistent. %>
                     <% if local_assigns[:export_format] && export_format == 'docx' %>
-                      <strong><%=  sanitize question[:text].to_s, scrubber: TableFreeScrubber.new %></strong>
+                      <strong><%=  sanitize(question[:text].to_s, scrubber: TableFreeScrubber.new).gsub(/<\/?p>/, '').html_safe %></strong>
                     <% else %>
-                     <div class="bold"><%=  sanitize question[:text].to_s, scrubber: TableFreeScrubber.new %></div>
+                     <div class="bold"><%=  sanitize(question[:text].to_s, scrubber: TableFreeScrubber.new).gsub(/<\/?p>/, '').html_safe %></div>
                     <% end %>
                     <br>
                   <% end %>

lib/templates/pandoc.md

@@ -0,0 +1,106 @@
+# Pandoc DOCX Reference Document
+
+The file `pandoc_reference.docx` is used as a style template when generating `.docx` exports. Pandoc uses the styles defined in this file while filling in content from the app. It does **not** use the content of the reference doc, only its styles.
+
+## How it works
+
+When `show_docx` runs in `plan_exports_controller.rb`, it passes this file to `pandoc` via `--reference-doc`. Pandoc maps HTML elements to Word styles like so:
+
+| HTML element | Word style |
+|---|---|
+| `<p>` | Body Text / First Paragraph |
+| `<h1>` – `<h6>` | Heading 1 – Heading 6 |
+| `<blockquote>` | Block Text |
+| `<code>` | Verbatim Char |
+| `<a>` | Hyperlink |
+| `<hr>` | Horizontal rule paragraph (avoid — use pBdr on heading instead) |
+
+## Editing styles
+
+The styles are stored in `word/styles.xml` inside the `.docx` file. Since `.docx` files are zip archives, you need to unzip, edit, and rezip.
+
+### 1. Unzip
+
+```bash
+cd lib/templates
+unzip pandoc_reference.docx -d pandoc_ref_tmp
+```
+
+### 2. Edit
+
+Open `pandoc_ref_tmp/word/styles.xml` in any text editor and find the style you want to change.
+
+Font sizes use half-points, so:
+
+| Value | Point size |
+|---|---|
+| 20 | 10pt |
+| 22 | 11pt |
+| 24 | 12pt |
+| 26 | 13pt |
+| 28 | 14pt |
+| 32 | 16pt |
+
+Spacing values (e.g. `w:before`, `w:after`) use twentieths of a point (twips), so 240 = 12pt of space.
+
+Common styles to edit:
+
+- **`docDefaults`** — fallback font and size for anything not explicitly styled
+- **`BodyText`** — regular paragraphs
+- **`FirstParagraph`** — first paragraph after a heading
+- **`Heading1` – `Heading9`** — headings (also update the matching `Heading1Char` etc.)
+
+### 3. Rezip
+
+Run the zip command from **inside** the tmp folder — this is important, otherwise the folder itself gets included and Pandoc won't read the file correctly.
+
+```bash
+cd pandoc_ref_tmp
+zip -r ../pandoc_reference.docx .
+cd ..
+rm -rf pandoc_ref_tmp
+```
+
+### 4. Deploy
+
+Commit `pandoc_reference.docx` and deploy. Changes take effect immediately on the next export.
+
+## Editing styles using Word
+
+You can open `pandoc_reference.docx` directly in Word and modify styles visually, though it requires a few extra steps to make sure changes actually persist to the style definitions (not just the sample text).
+
+### 1. Open the file in Word
+
+Open `pandoc_reference.docx` directly. You will see sample text for each style, e.g. "Body Text.", "First Paragraph.", "Heading 1", etc.
+
+### 2. Open the Styles pane
+
+- **Mac:** Go to **Format** menu → **Style...** → **Modify**
+- **Windows:** On the **Home** tab, click the small arrow at the bottom-right corner of the Styles group
+
+### 3. Modify a style
+
+In the Styles pane, hover over the style you want to change (e.g. **Body Text**) until a dropdown arrow appears on the right side. Click it and choose **Modify Style...**. Change the font, size, spacing, etc. and click **OK**.
+
+Do **not** right-click the sample text in the document body itself — that only affects the text, not the underlying style definition.
+
+### 4. Save
+
+Save the file normally. Word should write your style changes into the underlying XML.
+
+### 5. Verify the change was saved
+
+Because Word sometimes silently fails to persist style changes, it is worth verifying by unzipping and inspecting the XML after saving:
+
+```bash
+cd lib/templates
+unzip -p pandoc_reference.docx word/styles.xml | grep -A 10 '"Body Text"'
+```
+
+Check that `<w:sz w:val="..."/>` reflects the size you set. If it does not, the change did not save and you will need to edit the XML directly instead (see **Editing styles** above).
+
+## Tips
+
+- Always back up the file before editing: `cp pandoc_reference.docx pandoc_reference_backup.docx`
+- To verify a style was saved correctly, unzip and grep: `unzip -p pandoc_reference.docx word/styles.xml | grep -A 10 '"Body Text"'`
+- Avoid using `<hr>` in the HTML template. Instead, add a bottom border to the Heading style using `<w:pBdr>` in `styles.xml` to avoid extra spacing.