docs: add missing feature docs and rearrange sidebar for progressive learning by GOODBOY008 · Pull Request #882 · apache/fesod

GOODBOY008 · 2026-03-10T04:03:50Z

Background

While refactoring the example module, I found several features and usages that were not documented. This PR adds the missing documentation and reorganizes the sidebar for a better reading experience.

New Documentation (EN + zh-CN)

sheet/advanced/password — Password protection for reading and writing Excel files
sheet/advanced/custom-converter — Building and registering custom type converters
sheet/advanced/large-file — Large file writing with batch processing and temp file compression
sheet/read/format — Data formatting (`@DateTimeFormat`, `@NumberFormat`) when reading
sheet/write/converter — Per-field and global converter usage when writing
sheet/write/merge — Cell merging strategies (annotation, strategy, and custom)

Sidebar Reorganization

Added the missing `download` page to the sidebar
Reordered `read` and `write` categories to follow a progressive learning path: basics → data mapping → formatting → specialized formats → framework integration

Other Changes

Simplified the introduction page examples and linked to Quick Start
Minor heading consistency fix in `sheet/read/pojo.md`"

Copilot

Pull request overview

Reorganizes the Docusaurus documentation sidebar to follow a more progressive learning path, and adds several missing topic pages (EN + zh-cn) to match the new navigation flow.

Changes:

Added the download doc into the sidebar immediately after the introduction.
Reordered the read and write doc sequences to move from basic to advanced topics.
Added new docs for read formatting, write converter/merge, and advanced topics (password protection, custom converter, large-file writing), plus streamlined the introduction examples.

Reviewed changes

Copilot reviewed 16 out of 16 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
website/sidebars.js	Inserts `download` into the sidebar and reorders read/write/advanced sections for progressive learning.
website/i18n/zh-cn/docusaurus-plugin-content-docs/current/sheet/write/merge.md	Adds zh-cn write “merge” documentation page.
website/i18n/zh-cn/docusaurus-plugin-content-docs/current/sheet/write/converter.md	Adds zh-cn write “converter” documentation page.
website/i18n/zh-cn/docusaurus-plugin-content-docs/current/sheet/read/format.md	Adds zh-cn read “format” documentation page.
website/i18n/zh-cn/docusaurus-plugin-content-docs/current/sheet/advanced/password.md	Adds zh-cn “password protection” advanced doc.
website/i18n/zh-cn/docusaurus-plugin-content-docs/current/sheet/advanced/large-file.md	Adds zh-cn “large file writing” advanced doc.
website/i18n/zh-cn/docusaurus-plugin-content-docs/current/sheet/advanced/custom-converter.md	Adds zh-cn “custom converter” advanced doc.
website/i18n/zh-cn/docusaurus-plugin-content-docs/current/introduce.md	Simplifies zh-cn introduction examples and links to Quick Start.
website/docs/sheet/write/merge.md	Adds EN write “merge” documentation page.
website/docs/sheet/write/converter.md	Adds EN write “converter” documentation page.
website/docs/sheet/read/pojo.md	Minor heading language consistency fix (“Code Example”).
website/docs/sheet/read/format.md	Adds EN read “format” documentation page.
website/docs/sheet/advanced/password.md	Adds EN “password protection” advanced doc.
website/docs/sheet/advanced/large-file.md	Adds EN “large file writing” advanced doc.
website/docs/sheet/advanced/custom-converter.md	Adds EN “custom converter” advanced doc.
website/docs/introduce.md	Simplifies EN introduction examples and links to Quick Start.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-03-10T04:08:24Z

website/docs/sheet/advanced/password.md

+
+## Overview
+
+Fesod supports Excel's built-in password encryption for both reading and writing. Use `.password("xxx")` on the builder to encrypt output files or decrypt input files. The encryption uses Excel's native AES encryption for `.xlsx` files, compatible with all Excel versions.


The overview currently claims password protection uses AES and is "compatible with all Excel versions", but Fesod’s writer-side .password(...) has important caveats (it’s implemented via POI encryption for XLSX and is documented in code as memory-intensive, and XLS behaves differently). Please adjust this section to avoid over-claiming compatibility and document the memory/format limitations (e.g., XLSX encryption + high memory usage; XLS is write-protect behavior).

Suggested change

Fesod supports Excel's built-in password encryption for both reading and writing. Use `.password("xxx")` on the builder to encrypt output files or decrypt input files. The encryption uses Excel's native AES encryption for `.xlsx` files, compatible with all Excel versions.

Fesod supports Excel's built-in password protection for both reading and writing. Use `.password("xxx")` on the builder to encrypt/decrypt files. For `.xlsx` output, Fesod uses Apache POI's encryption (AES-based) which can be memory‑intensive for large workbooks. For legacy `.xls` files, password protection behaves as write‑protection rather than full content encryption, so behavior and security guarantees differ from `.xlsx`.

Copilot · 2026-03-10T04:08:25Z

website/i18n/zh-cn/docusaurus-plugin-content-docs/current/sheet/advanced/password.md

+## 概述
+
+Fesod 支持 Excel 内置的密码加密功能，适用于读取和写入操作。在构建器上使用 `.password("xxx")` 即可加密输出文件或解密输入文件。加密使用 Excel 原生的 AES 加密方式（适用于 `.xlsx` 文件），兼容所有 Excel 版本。
+
+## 带密码写入


中文文档的概述段落同样写到“Excel 原生 AES 加密方式…兼容所有 Excel 版本”，且未提示 .password(...) 写入端加密会非常耗内存/并且不同格式（XLS/XLSX）行为不同。建议在这里补充格式限制与内存开销说明，并避免“兼容所有版本”的绝对表述。

Copilot · 2026-03-10T04:08:25Z

website/docs/sheet/write/merge.md

+    protected void merge(Sheet sheet, Cell cell, Head head, Integer relativeRowIndex) {
+        if (relativeRowIndex != null && relativeRowIndex % 2 == 0 && head.getColumnIndex() == 0) {
+            int startRow = relativeRowIndex + 1;
+            int endRow = startRow + 1;
+            sheet.addMergedRegion(new CellRangeAddress(startRow, endRow, 0, 0));
+        }


In CustomMergeStrategy, computing startRow as relativeRowIndex + 1 implicitly assumes exactly one header row. Since relativeRowIndex is already “data-row relative” (and header rows are skipped), this example can produce wrong row indexes when headRowNumber is not 1 (multi-row headers) or when writing starts at an offset. Consider using cell.getRowIndex() (actual sheet row) or documenting/deriving the header-row offset explicitly to make the sample copy/paste safe.

Copilot · 2026-03-10T04:08:25Z

website/docs/sheet/advanced/large-file.md

+        WriteSheet writeSheet = FesodSheet.writerSheet("Template").build();
+        // Write 100,000 rows in batches of 100
+        for (int i = 0; i < 1000; i++) {
+            excelWriter.write(data(), writeSheet);
+        }


The sample’s comments state “Write 100,000 rows in batches of 100”, but the code calls excelWriter.write(data(), ...) in a loop without showing that data() returns 100 rows. As written, the row counts in the comment aren’t verifiable/copy‑pastable; either include a data() implementation that returns the batch size you describe, or adjust the comments to avoid claiming specific row totals/batch sizes.

Copilot · 2026-03-10T04:08:25Z

website/i18n/zh-cn/docusaurus-plugin-content-docs/current/sheet/advanced/large-file.md

+        WriteSheet writeSheet = FesodSheet.writerSheet("模板").build();
+        // 分批写入 100,000 行，每批 100 行
+        for (int i = 0; i < 1000; i++) {
+            excelWriter.write(data(), writeSheet);
+        }


代码注释写到“分批写入 100,000 行，每批 100 行”，但示例里循环调用 excelWriter.write(data(), ...)，并未给出 data() 每批返回 100 行的实现（对读者来说无法验证/直接复制）。建议补充 data() 的批次数据构造（明确 100 行），或把注释改为不依赖具体行数的描述。

Copilot · 2026-03-10T04:08:26Z

website/docs/sheet/read/format.md

+
+| Excel Cell Value | Annotation | Java Field Value |
+|:---|:---|:---|
+| `Hello` | `@ExcelProperty(converter = CustomStringStringConverter.class)` | `"Custom：Hello"` |


In the conversion table, the example output uses a fullwidth colon ("Custom：Hello"). This is inconsistent with the converter examples (which use Custom:) and reads like a typo; please change it to a normal ASCII colon ("Custom: Hello").

Suggested change

| `Hello` | `@ExcelProperty(converter = CustomStringStringConverter.class)` | `"Custom：Hello"` |

| `Hello` | `@ExcelProperty(converter = CustomStringStringConverter.class)` | `"Custom: Hello"` |

Copilot · 2026-03-10T04:08:26Z

website/docs/sheet/write/converter.md

+
+    @DateTimeFormat("yyyy年MM月dd日HH时mm分ss秒")
+    @ExcelProperty("Date Title")
+    private Date date;


This English doc uses a Chinese-locale date pattern (yyyy年MM月dd日HH时mm分ss秒) in @DateTimeFormat. That’s likely confusing for the English docs; consider switching to a locale-neutral pattern like yyyy-MM-dd HH:mm:ss (or explicitly note that the pattern is arbitrary) so readers can copy/paste safely.

- Add custom converter documentation covering per-field and global registration - Add large file writing guide for handling 100,000+ row datasets - Add password protection documentation for secure spreadsheets - Add read format guide documenting supported Excel formats - Add write converter guide with practical examples - Add merge cells documentation for complex layouts - Simplify introduction examples to focus on quick start patterns - Update POJO read documentation with enhanced examples - Add Chinese translations for all new documentation pages - Update sidebar navigation to include new advanced topics

…d remove extra blank lines

…llwidth colon, batch comments, and merge strategy caveat

psxjoy

LGTM

Copilot AI review requested due to automatic review settings March 10, 2026 04:03

Copilot started reviewing on behalf of GOODBOY008 March 10, 2026 04:04 View session

Copilot AI reviewed Mar 10, 2026

View reviewed changes

GOODBOY008 added 2 commits March 10, 2026 14:21

docs: fix markdownlint errors - add language to fenced code blocks an…

b2fb514

…d remove extra blank lines

GOODBOY008 force-pushed the main-doc branch from 33b5664 to b2fb514 Compare March 10, 2026 06:21

docs: address PR review comments - fix password docs, date format, fu…

8514515

…llwidth colon, batch comments, and merge strategy caveat

GOODBOY008 changed the title ~~docs: rearrange sidebar doc order for progressive learning flow~~ docs: add missing feature docs and rearrange sidebar for progressive learning Mar 10, 2026

psxjoy approved these changes Mar 10, 2026

View reviewed changes

psxjoy merged commit 62c46e8 into apache:main Mar 10, 2026
5 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: add missing feature docs and rearrange sidebar for progressive learning#882

docs: add missing feature docs and rearrange sidebar for progressive learning#882
psxjoy merged 3 commits intoapache:mainfrom
GOODBOY008:main-doc

GOODBOY008 commented Mar 10, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Mar 10, 2026

Uh oh!

Copilot AI Mar 10, 2026

Uh oh!

Copilot AI Mar 10, 2026

Uh oh!

Copilot AI Mar 10, 2026

Uh oh!

Copilot AI Mar 10, 2026

Uh oh!

Copilot AI Mar 10, 2026

Uh oh!

Copilot AI Mar 10, 2026

Uh oh!

psxjoy left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants


		## Overview

		Fesod supports Excel's built-in password encryption for both reading and writing. Use `.password("xxx")` on the builder to encrypt output files or decrypt input files. The encryption uses Excel's native AES encryption for `.xlsx` files, compatible with all Excel versions.

	\| `Hello` \| `@ExcelProperty(converter = CustomStringStringConverter.class)` \| `"Custom：Hello"` \|
	\| `Hello` \| `@ExcelProperty(converter = CustomStringStringConverter.class)` \| `"Custom: Hello"` \|

Conversation

GOODBOY008 commented Mar 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Background

New Documentation (EN + zh-CN)

Sidebar Reorganization

Other Changes

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Mar 10, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 10, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 10, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 10, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 10, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 10, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 10, 2026

Choose a reason for hiding this comment

Uh oh!

psxjoy left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

GOODBOY008 commented Mar 10, 2026 •

edited

Loading