pengjunjie/ragflow
1
0
Fork 1
mirror of https://github.com/infiniflow/ragflow.git synced 2025-12-17 19:22:55 +08:00
Code Issues Packages Projects Releases Wiki Activity
Files
f9510edbbca08aebe2f61489480b7a2e65f313d7
ragflow/docs/guides/agent/agent_component_reference/docs_generator.md
PentaFDevs f9510edbbc Feature/docs generator (#11858) 
### Type of change

- [x] New Feature (non-breaking change which adds functionality)


### What problem does this PR solve?

This PR introduces a new Docs Generator agent component for producing
downloadable PDF, DOCX, or TXT files from Markdown content generated
within a RAGFlow workflow.

### **Key Features**

**Backend**

- New component: DocsGenerator (agent/component/docs_generator.py)
- 
- Markdown → PDF/DOCX/TXT conversion
- 
- Supports tables, lists, code blocks, headings, and rich formatting
- 
- Configurable document style (fonts, margins, colors, page size,
orientation)
- 
- Optional header logo and footer with page numbers/timestamps
- 

**Frontend**

- New configuration UI for the Docs Generator
- 
- Download button integrated into the chat interface
- 
- Output wired to the Message component
- 
- Full i18n support

**Documentation**

Added component guide:
docs/guides/agent/agent_component_reference/docs_generator.md

**Usage**

Add the Docs Generator to a workflow, connect Markdown output from an
upstream component, configure metadata/style, and feed its output into
the Message component. Users will see a document download button
directly in the chat.

**Contributor Note**

We have been following RAGFlow since more than a year and half now and
have worked extensively on personalizing the framework and integrating
it into several of our internal systems. Over the past year and a half,
we have built multiple platforms that rely on RAGFlow as a core
component, which has given us a strong appreciation for how flexible and
powerful the project is.

We also previously contributed the full Italian translation, and we were
glad to see it accepted. This new Docs Generator component was created
for our own production needs, and we believe that it may be useful for
many others in the community as well.

We want to sincerely thank the entire RAGFlow team for the remarkable
work you have done and continue to do. If there are opportunities to
contribute further, we would be glad to help whenever we have time
available. It would be a pleasure to support the project in any way we
can.

If appropriate, we would be glad to be listed among the project’s
contributors, but in any case we look forward to continuing to support
and contribute to the project.

PentaFrame Development Team

---------

Co-authored-by: PentaFrame <info@pentaframe.it>
Co-authored-by: Kevin Hu <kevinhu.sh@gmail.com>
2025-12-12 14:59:43 +08:00

8.1 KiB
Raw Blame History

sidebar_position, slug
sidebar_position slug
35 /docs_generator

Docs Generator component

A component that generates downloadable PDF, DOCX, or TXT documents from markdown-style content with full Unicode support.

The Docs Generator component enables you to create professional documents directly within your agent workflow. It accepts markdown-formatted text and converts it into downloadable files, making it ideal for generating reports, summaries, or any structured document output.

Key features

  • Multiple output formats: PDF, DOCX, and TXT
  • Full Unicode support: Automatic font switching for CJK (Chinese, Japanese, Korean), Arabic, Hebrew, and other non-Latin scripts
  • Rich formatting: Headers, lists, tables, code blocks, and more
  • Customizable styling: Fonts, margins, page size, and orientation
  • Document extras: Logo, watermark, page numbers, and timestamps
  • Direct download: Generates a download button for the chat interface

Prerequisites

  • Content to be converted into a document (typically from an Agent or other text-generating component).

Examples

You can pair an Agent component with the Docs Generator to create dynamic documents based on user queries. The Agent generates the content, and the Docs Generator converts it into a downloadable file. Connect the output to a Message component to display the download button in the chat.

A typical workflow looks like:

Begin → Agent → Docs Generator → Message

In the Message component, reference the download output variable from the Docs Generator to display a download button in the chat interface.

Configurations

Content

The main text content to include in the document. Supports markdown formatting:

  • Bold: **text** or __text__
  • Italic: *text* or _text_
  • Inline code: `code`
  • Headings: # Heading 1, ## Heading 2, ### Heading 3
  • Bullet lists: - item or * item
  • Numbered lists: 1. item
  • Tables: | Column 1 | Column 2 |
  • Horizontal lines: ---
  • Code blocks: ``` code ```

:::tip NOTE Click (x) or type / to insert variables from upstream components. :::

Title

Optional. The document title displayed at the top of the generated file.

Subtitle

Optional. A subtitle displayed below the title.

Output format

The file format for the generated document:

  • PDF (default): Portable Document Format with full styling support.
  • DOCX: Microsoft Word format.
  • TXT: Plain text format.

Logo image

Optional. A logo image to display at the top of the document. You can either:

  • Upload an image file using the file picker
  • Paste an image path, URL, or base64-encoded data

Logo position

The horizontal position of the logo:

  • left (default)
  • center
  • right

Logo dimensions

  • Logo width: Width in inches (default: 2.0)
  • Logo height: Height in inches (default: 1.0)

Font family

The font used throughout the document:

  • Helvetica (default)
  • Times-Roman
  • Courier
  • Helvetica-Bold
  • Times-Bold

Font size

The base font size in points. Defaults to 12.

Title font size

The font size for the document title. Defaults to 24.

Page size

The paper size for the document:

  • A4 (default)
  • Letter

Orientation

The page orientation:

  • Portrait (default)
  • Landscape

Margins

Page margins in inches:

  • Margin top: Defaults to 1.0
  • Margin bottom: Defaults to 1.0
  • Margin left: Defaults to 1.0
  • Margin right: Defaults to 1.0

Filename

Optional. Custom filename for the generated document. If left empty, a filename is auto-generated with a timestamp.

Output directory

The server directory where generated documents are saved. Defaults to /tmp/pdf_outputs.

Add page numbers

When enabled, page numbers are added to the footer of each page. Defaults to true.

Add timestamp

When enabled, a generation timestamp is added to the document footer. Defaults to true.

Watermark text

Optional. Text to display as a diagonal watermark across each page. Useful for marking documents as "Draft", "Confidential", etc.

Output

The Docs Generator component provides the following output variables:

Variable name Type Description
file_path string The server path where the generated document is saved.
pdf_base64 string The document content encoded in base64 format.
download string JSON containing download information for the chat interface.
success boolean Indicates whether the document was generated successfully.

Displaying the download button

To display a download button in the chat, add a Message component after the Docs Generator and reference the download variable:

  1. Connect the Docs Generator output to a Message component.
  2. In the Message component's content field, type / and select {Docs Generator_0@download}.
  3. When the agent runs, a download button will appear in the chat, allowing users to download the generated document.

The download button automatically handles:

  • File type detection (PDF, DOCX, TXT)
  • Proper MIME type for browser downloads
  • Base64 decoding for direct file delivery

Unicode and multi-language support

The Docs Generator includes intelligent font handling for international content:

How it works

  1. Content analysis: The component scans the text for non-Latin characters.
  2. Automatic font switching: When CJK or other complex scripts are detected, the system automatically switches to a compatible CID font (STSong-Light for Chinese, HeiseiMin-W3 for Japanese, HYSMyeongJo-Medium for Korean).
  3. Latin content: For documents containing only Latin characters (including extended Latin, Cyrillic, and Greek), the user-selected font family is used.

Supported scripts

Script Unicode Range Font Used
Chinese (CJK) U+4E00–U+9FFF STSong-Light
Japanese (Hiragana/Katakana) U+3040–U+30FF HeiseiMin-W3
Korean (Hangul) U+AC00–U+D7AF HYSMyeongJo-Medium
Arabic U+0600–U+06FF CID font fallback
Hebrew U+0590–U+05FF CID font fallback
Devanagari (Hindi) U+0900–U+097F CID font fallback
Thai U+0E00–U+0E7F CID font fallback

Font installation

For full multi-language support in self-hosted deployments, ensure Unicode fonts are installed:

Linux (Debian/Ubuntu):

apt-get install fonts-freefont-ttf fonts-noto-cjk

Docker: The official RAGFlow Docker image includes these fonts. For custom images, add the font packages to your Dockerfile:

RUN apt-get update && apt-get install -y fonts-freefont-ttf fonts-noto-cjk

:::tip NOTE CID fonts (STSong-Light, HeiseiMin-W3, etc.) are built into ReportLab and do not require additional installation. They are used automatically when CJK content is detected. :::

Troubleshooting

Characters appear as boxes or question marks

This indicates missing font support. Ensure:

  1. The content contains supported Unicode characters.
  2. For self-hosted deployments, Unicode fonts are installed on the server.
  3. The document is being viewed in a PDF reader that supports embedded fonts.

Download button not appearing

Ensure:

  1. The Message component is connected after the Docs Generator.
  2. The download variable is correctly referenced using / (which appears as {Docs Generator_0@download} when copied).
  3. The document generation completed successfully (check success output).

Large tables not rendering correctly

For tables with many columns or large cell content:

  • The component automatically converts wide tables to a definition list format for better readability.
  • Consider splitting large tables into multiple smaller tables.
  • Use landscape orientation for wide tables.