Redmine

I wrote a patch to add a simple preview for Microsoft Office documents (such as Word, Excel, and PowerPoint) on AttachmentsController#show page. The patch uses Microsoft's MarkItDown command to convert supported Office files into Markdown and renders that Markdown in Redmine. Because the preview is generated from Markdown, original layout is not preserved and non-text contents will be lost, but it enables quick content inspection without downloading the file.

This MS Office documents preview is available only when MarkItDown is installed. It is an optional dependency, so Redmine continues to work without it; only this preview feature is unavailable. To install MarkItDown, run: pip install 'markitdown[all]'.

When a user opens `AttachmentsController#show` page for a supported MS Office attachment, Redmine calls the `markitdown` command and converts the file to Markdown, which may take a few seconds. Redmine then renders the converted Markdown as the preview. Generated Markdown is cached in tmp/markdownized_previews, so subsequent accesses are much faster. Preview content is truncated to a fixed size limit of 100 KB. This caching approach follows the same pattern already used by thumbnails, which are generated via ImageMagick convert and stored in tmp/thumbnails.

Currently, for Microsoft Office attachments, Redmine does not show document content on the attachment page; users must download the file and open it locally to inspect it. This patch adds a practical inline preview that helps users quickly understand what the document contains and can reduce download/open steps in daily workflows.

Preview for a MS Word document:

Original MS Word document:

I have updated the patch.

This version uses Pandoc instead of MarkItDown to convert documents to Markdown. In my testing, Pandoc converts documents to Markdown much faster than MarkItDown. Switching to Pandoc also enables preview support for LibreOffice documents in addition to Microsoft Office documents.

Additionally, Pandoc is available from package managers on many Linux distributions, so admins can install and manage it in the same way as other Redmine dependencies, such as the database server and ImageMagick. MarkItDown usually requires Python's pip.

Setting the target version to 7.0.0.

thanks for this Go MAEDA, i like the .md convert for a preview

This additional patch provides some improvements to the initial Pandoc integration 0001-Add-Microsoft-Office-and-LibreOffice-documents-previ.patch

first i install pandoc, via apt install pandoc often provides version 3.1, which I found to be insufficient. In version 3.1, .xlsx conversion is not yet available/stable, leading to infinite loops where the process never finishes. Reliable support for .xlsx requires at least version 3.2, while .pptx is fully supported since version 3.8.3.
then i install pandoc 3.9 via .db file and the .xlsx convert runs

On my system, the timeout mechanism failed to terminate the Pandoc process.
The process continued to run until completion regardless of the timeout. I have refactored the execution to use Process.spawn with proper arguments and added Process.detach(pid).

hope you can reproduce the same behavior.

• Process.spawn with args and, Process.detach in the end
  the PID is correctly tracked and terminated when the timeout threshold is exceeded.
• pandoc version >= 3.9 in the Markownizer.available?
• set default extensions to .docx .xlsx .pptx .odt
  old office formats are not supported, and only .odt for libre office
• set extensions via config pandoc_extensions

• create the prev file asynchron
• Create a timeout file to skip future conversion attempts for files that previously failed

I also evaluated MarkItDown. Although it supports outlook .msg files and the old office extensions, its processing time for small .docx files was over 20x slower than Pandoc. Consequently, I prioritized Pandoc for its performance.
With large .xlsx files (5,000+ rows). In those specific cases, MarkItDown was actually twice as fast as Pandoc. However, for our primary use case—providing a quick preview for standard office documents—this performance gain on large files is not relevant.

Florian Walchshofer, thank you for reviewing the patch and giving feedback in #note-4. I have updated the patch.

• The Pandoc version is now checked before performing previews. When Pandoc 3.8.3 or later is installed, previews are supported for .docx and .odt, and additionally for .xlsx and .pptx. The SUPPORTED_EXTENSIONS constant has been removed. Instead, the new markdownizable_extensions method returns the list of convertible file extensions based on the detected Pandoc version.
• I have also incorporated the timeout handling that you suggested in #note-4` with slight changes. In your patch, Process.detach was placed inside the ensure block. In this patch, I moved it to immediately after Process.kill to prevent Process.detach from being called again on the success path after the PID has already been collected with Process.wait2.

The below is the diff from the previous patch: ShowHide

diff --git a/doc/INSTALL b/doc/INSTALL
index d0d72f040..aa406cfa3 100644
--- a/doc/INSTALL
+++ b/doc/INSTALL
@@ -19,7 +19,9 @@ Optional:
 * SCM binaries (e.g. svn, git...), for repository browsing (must be
   available in PATH)
 * ImageMagick (to enable Gantt export to png images)
-* Pandoc (to enable preview for Microsoft Office / LibreOffice documents)
+* Pandoc, to enable previews for Microsoft Office (.docx, .xlsx, .pptx) and
+  LibreOffice Writer (.odt) documents. Version 3.8.3 or later is recommended.
+  Older versions of Pandoc supports only .docx and .odt documents.

 Supported browsers:
 The current version of Firefox, Safari, Chrome, Chromium and Microsoft Edge.
diff --git a/lib/redmine/markdownizer.rb b/lib/redmine/markdownizer.rb
index 898ef4a9b..d84d1c676 100644
--- a/lib/redmine/markdownizer.rb
+++ b/lib/redmine/markdownizer.rb
@@ -18,6 +18,7 @@
 # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.

 require 'fileutils'
+require 'shellwords'
 require 'tempfile'
 require 'timeout'

@@ -27,10 +28,9 @@ module Redmine

     COMMAND = (Redmine::Configuration['pandoc_command'] || 'pandoc').freeze
     MAX_PREVIEW_SIZE = 100.kilobytes
-    SUPPORTED_EXTENSIONS = %w(.doc .docx .xls .xlsx .ppt .pptx .odt .ods .odp).freeze

     def self.supports?(filename)
-      SUPPORTED_EXTENSIONS.include?(File.extname(filename.to_s).downcase)
+      markdownizable_extensions.include?(File.extname(filename.to_s).downcase)
     end

     def self.convert(source, target)
@@ -39,25 +39,28 @@ module Redmine

       directory = File.dirname(target)
       FileUtils.mkdir_p(directory)
-      cmd = "#{shell_quote COMMAND} #{shell_quote source} -t gfm" 
+      args = [COMMAND, source, "-t", "gfm"]
       pid = nil
       output = Tempfile.new('markdownized-preview')

       begin
         Timeout.timeout(Redmine::Configuration['thumbnails_generation_timeout'].to_i) do
-          pid = Process.spawn(cmd, out: output.path)
+          pid = Process.spawn(*args, out: output.path)
           _, status = Process.wait2(pid)
           unless status.success?
-            logger.error("Markdown conversion failed (#{status.exitstatus}):\nCommand: #{cmd}")
+            logger.error("Markdown conversion failed (#{status.exitstatus}):\nCommand: #{args.shelljoin}")
             return nil
           end
         end
       rescue Timeout::Error
-        Process.kill('KILL', pid) if pid
-        logger.error("Markdown conversion timed out:\nCommand: #{cmd}")
+        if pid
+          Process.kill('KILL', pid)
+          Process.detach(pid)
+        end
+        logger.error("Markdown conversion timed out:\nCommand: #{args.shelljoin}")
         return nil
       rescue => e
-        logger.error("Markdown conversion failed:\nCommand: #{cmd}\nException was: #{e.message}")
+        logger.error("Markdown conversion failed:\nCommand: #{args.shelljoin}\nException was: #{e.message}")
         return nil
       ensure
         output.close
@@ -74,7 +77,7 @@ module Redmine
       return @available if defined?(@available)

       begin
-        `#{shell_quote COMMAND} --version`
+        @pandoc_version = `#{shell_quote COMMAND} --version`[/pandoc\s+([\d.]+)/, 1].split('.').map(&:to_i)
         @available = $?.success?
       rescue
         @available = false
@@ -83,6 +86,22 @@ module Redmine
       @available
     end

+    def self.markdownizable_extensions
+      return @markdownizable_extensions if defined?(@markdownizable_extensions)
+
+      if available?
+        # Microsoft Word and LibreOffice Writer files are supported by a wide
+        # range of Pandoc versions
+        @markdownizable_extensions = %w[.docx .odt]
+      else
+        return (@markdownizable_extensions = [])
+      end
+      # Pandoc >= 3.8.3 supports Microsoft Excel and PowerPoint files
+      @markdownizable_extensions += %w[.xlsx .pptx] if (@pandoc_version <=> [3, 8, 3]) >= 0
+
+      @markdownizable_extensions
+    end
+
     def self.logger
       Rails.logger
     end

I updated the patch to move markdownized_previews_storage_path under Attachment.storage_path. This changes the default location for markdownized preview files from tmp/markdownized_previews to files/markdownized_previews.

This change is for security. Markdownized preview files can contain sensitive information from attachments, and storing them in tmp may increase exposure risk in some environments. The files directory is generally expected to be managed by server administrators with appropriate restrictive permissions, so storing previews there may be safer than storing them under tmp.

Changes from the previous patch: ShowHide

diff --git a/app/models/attachment.rb b/app/models/attachment.rb
index de23ac51d..5dae50147 100644
--- a/app/models/attachment.rb
+++ b/app/models/attachment.rb
@@ -82,8 +82,13 @@ class Attachment < ApplicationRecord

   cattr_accessor :thumbnails_storage_path
   @@thumbnails_storage_path = File.join(Rails.root, "tmp", "thumbnails")
-  cattr_accessor :markdownized_previews_storage_path
-  @@markdownized_previews_storage_path = File.join(Rails.root, "tmp", "markdownized_previews")
+
+  # Since markdownized previews can contain sensitive data, they should be
+  # stored under storage_path, which is expected to have appropriately
+  # restrictive permissions.
+  def self.markdownized_previews_storage_path
+    File.join(storage_path, 'markdownized_previews')
+  end

   before_create :files_to_final_location
   after_commit :delete_from_disk, :on => :destroy

I have committed the patch in r24485.

The attachment preview now supports Microsoft Office (.docx, .xlsx, .pptx) and LibreOffice Writer (.odt) files. These files can be previewed directly on the attachment page without downloading them first.

• The preview is generated by converting supported files to Markdown with Pandoc and rendering the result in Redmine.
• The generated preview is a simplified text-based view, so the original layout and some non-text content are not preserved.
• Pandoc 3.8.3 or later is required to support Microsoft Excel (.xlsx) and PowerPoint (.pptx) files. With older Pandoc versions, only Microsoft Word (.docx) and LibreOffice Writer (.odt) files are supported.
• Many Linux distribution package managers provide older versions of Pandoc. For example, Ubuntu 24.04 provides Pandoc 3.1.3. To enable preview for .xlsx and .pptx files, I recommend installing the latest Pandoc using the installers available at https://github.com/jgm/pandoc/releases.

This additional patch makes the Pandoc preview limits configurable in config/configuration.yml instead of defining in markdownizer.rb, so server administrators can adjust them more easily. It adds markdownized_preview_max_source_size and markdownized_preview_max_output_size. Also, the default maximum source size is reduced from 20 MB to 10 MB, and the default maximum output size is reduced from 512 KB to 100 KB.

It also stops reusing thumbnails_generation_timeout for Pandoc-based preview generation and introduces a dedicated setting, markdownized_preview_generation_timeout.

Go MAEDA wrote in #note-15:

This additional patch makes the Pandoc preview limits configurable in config/configuration.yml instead of defining in markdownizer.rb, so server administrators can adjust them more easily.

Committed the patch in r24522.

The attached patch changes the cache location for attachment previews from files/markdownized_previews to files/derived_cache/markdownized_previews.

This change has two main benefits. First, the new path makes it clear that these files are cache data, not original attachments, and can be safely deleted and regenerated on demand. Second, it establishes a cleaner structure for future use: if Redmine later needs to store other cache files derived from files under files, they can be grouped under files/derived_cache/ instead of creating multiple directories directly under files.

Go MAEDA wrote in #note-17:

The attached patch changes the cache location for attachment previews from files/markdownized_previews to files/derived_cache/markdownized_previews.

Committed the change in r24592.

Go MAEDA wrote in #note-18:

Go MAEDA wrote in #note-17:

The attached patch changes the cache location for attachment previews from files/markdownized_previews to files/derived_cache/markdownized_previews.

Committed the change in r24592.

Hi there,

i updated my local redmine to 7.0.0 and installed pandoc to get the previews going. It's kind of working. In my .docx is an image, that doesnt get rendered. Is this configurable or completley intended to not preview images?