docs: expand the write/fill pages and replace their screenshots with grids by nkuprins · Pull Request #979 · apache/fesod

nkuprins · 2026-07-28T13:21:36Z

Purpose of the pull request

Closed: #978

What's changed?

Screenshots in the write/ and fill/ docs become HTML grids styled by website/src/css/xl-sheet.css.
In general, some screenshots were not aligned with the code and vice versa. For example, Fill Multiple Lists Together, had data1 horizontal on the image, but the code never used WriteDirectionEnum.HORIZONTAL. In that case, I updated the code snippet with the horizontal part. Where a page leaned on the screenshot for what the text never said, the explanation is added too.

Page	Change
`fill/fill.md`	New placeholder syntax section: `{name}` vs `{.name}` vs `{list.name}`, escaping, unsupplied placeholders
`write/image.md`	Field type → converter table, multi-image `WriteCellData`, `UrlImageConverter` fetch policy
`write/head.md`	Merge strategies corrected, one result grid per strategy under its own heading
`write/pojo.md`	`includeColumnFieldNames` ordering and `index` gaps, both grouped under Column Order; fixes a typo and a Java 9 `Set.of` call
`write/merge.md`	The text-art result becomes a grid; the Merged Cells section from `write/extra.md` is consolidated here
`write/extra.md`	Comment and dropdown results; dropdown handler registration snippet; merged cells moved to `write/merge.md`
`write/sheet.md`	Sheet tabs in results; each `WriteTable` writes its own header
`write/simple.md`	Adds the result grid the page never had
`write/style.md`, `write/format.md`	Grids shortened, value-named style classes
Site	`.xl-sheet` rules moved out of `custom.css` into `src/css/xl-sheet.css`, with light/dark theming; `div` and `p` allowed in `MD033`; deletes the 31 replaced PNGs

Collaboration

@delei joined this PR as a collaborator and contributed the xl-sheet CSS rework
(container element, light/dark theme support, palette and spacing), the Chinese wording pass,
and the documentation restructuring/rewording listed above.

Browsers

Verified in the latest Microsoft Edge, Firefox, Brave, and Chrome

Chinese

The zh-cn pages mirror the English ones. I don't speak Chinese, so they started out AI-translated. @delei has since reviewed and corrected the wording.

Checklist

I have read the Contributor Guide.
I have written the necessary doc or comment.
I have added the necessary unit tests and all cases have passed.

Replaces the PNG screenshots of template and result spreadsheets with semantic HTML tables styled via a new .xl-sheet ruleset, so the examples are selectable, searchable and theme-aware instead of fixed-size images. Also swaps sample data placeholders to locale-neutral names in the English docs.

nkuprins · 2026-07-28T13:23:27Z

This is intentionally a draft because I still have to polish and reverify... But the core part is already done.

The .xl-sheet rules leave custom.css for src/css/xl-sheet.css, registered as a second customCss entry. Geometry is expressed in Excel's own units and classes are named after the spreadsheet value they render (xl-fill-red, xl-fs-20). Adds styles for pictures, comment and dropdown overlays, and sheet tabs.

Each grid keeps its first and last data rows with an ellipsis row between, and uses the value-named style classes.

Adds a table of the {name}, {.name}, {list.name} and escaped forms with what fills each, plus notes on mixing placeholders with text and on unfilled placeholders being cleared. Result grids are shortened.

Drops the trailing empty column and the repeated data rows.

The strategy example now uses a three-level header where names repeat in both directions, with one grid per strategy, and explains why AUTO leaves a vertical merge below the first header row unmerged.

Adds a table mapping each field type to its converter, notes that a picture is stretched to its cell, and documents the multi-image WriteCellData form. The result screenshots become grids drawing a sample SVG.

Documents that includeColumnFieldNames follows the POJO field order unless orderByIncludeColumn is set, and that @ExcelProperty index is an absolute position, so a skipped index leaves an empty column. Also fixes the includeColumnFiledNames typo and the Java 9 Set.of call.

The grids now carry the sheet tabs they produce, so the single-sheet, multi- sheet and table results are told apart, with a line on what each writes.

Shows what the three approaches write. The Chinese page also switches its sample data to 字符串, matching write/merge.

The comment and dropdown results are drawn open in the grid, and the dropdown handler gains the usage snippet that registers it.

The 19 PNGs under static/img/docs/write are no longer referenced by any page.

Includes listFill_file.png, which only appears as a path inside a code sample in the contribute-doc guide and is not loaded by any page.

delei · 2026-08-02T06:37:05Z

Hi, @nkuprins
:) A excellent PR.

Regarding the Chinese documentation, could you please consider me as a collaborator for this PR? I would like to assist in modifying the Chinese documentation and directly submit it to this PR.

I have preliminarily reviewed the PR content and I think I might make some changes:

Optimize the CSS of the xl-sheet
Update some of the descriptions in the Chinese documentation

Please let me know if you need any help.

nkuprins · 2026-08-02T06:46:05Z

Hi, @nkuprins :) A excellent PR.

Regarding the Chinese documentation, could you please consider me as a collaborator for this PR? I would like to assist in modifying the Chinese documentation and directly submit it to this PR.

I have preliminarily reviewed the PR content and I think I might make some changes:

Optimize the CSS of the xl-sheet

Update some of the descriptions in the Chinese documentation

Please let me know if you need any help.

Sure! You are very welcome to help!

delei · 2026-08-02T09:21:30Z

Optimize the CSS of the xl-sheet:

add a container div
adjust the CSS to adapt to light and dark themes

This is the local preview result. How about it?

nkuprins · 2026-08-02T09:33:38Z

Optimize the CSS of the xl-sheet:
* add a container div

* adjust the CSS to adapt to light and dark themes
This is the local preview result. How about it?

Good!

…kuprins/fesod into pr/979

delei · 2026-08-02T12:58:05Z

I have preliminarily reviewed the PR content and I think I might make some changes:

Optimize the CSS of the xl-sheet

Update some of the descriptions in the Chinese documentation

Please let me know if you need any help.

Hi, @nkuprins

I have completed these modifications. Please preview the website effect locally and review it.

BTW, since I was involved in the collaboration of this PR, the code review process will be handled by other community members.

nkuprins · 2026-08-02T15:09:15Z

Have u seen the style page? For me, the tables lack colours now except for the header

Before:

Now:

nkuprins · 2026-08-02T15:49:30Z

All the css style changes now LGTM!
Verified in the latest Microsoft Edge, Firefox, Brave, and Chrome

I will verify the text changes later

nkuprins · 2026-08-02T22:38:27Z

At docs/sheet/fill/#simple-fill

The change was from John Doe to John.
However, C2, D2 still hold John Doe.

I am also confused by this change, because other sections still use John Doe. For consistency, it might be better to stick with 1 option for all sections, either John or John Doe.

Btw, I just noticed a problem with the data() function. The write docs define their data(), but the fill docs don't. This is at least inconsistent. Also, it can be confusing for junior readers.
Do you think it might be worth adding smth like this:

Data List

The examples further down all fill from this helper:

private List<FillData> data() {
    List<FillData> list = ListUtils.newArrayList();
    for (int i = 0; i < 10; i++) {
        FillData fillData = new FillData();
        fillData.setName("John Doe" + i);
        fillData.setNumber(5.2);
        fillData.setDate(new Date());
        list.add(fillData);
    }
    return list;
}

If we do this, note that at docs/sheet/fill/#horizontal-fill in the results table, you removed columns from G to L. This implies cutting the filled data from 10 items to 4, which would violate data() count. The fix would be to add a ⋯ column, as we do at docs/sheet/fill/#fill-multiple-lists-together in the results tables.

At docs/sheet/write/image.md:191

I think there is a typo.Fefault should be Default
At docs/sheet/write/extra.md:25

The merged section was removed, but we still mention it: This chapter introduces how to write extra information such as comments, hyperlinks, formulas, merged cells, etc. The fix:
This chapter introduces how to write extra information such as comments, hyperlinks, formulas, etc.

nkuprins · 2026-08-02T22:46:59Z

I also updated PR description

Thank you for the help and collaboration!

…kuprins/fesod into pr/979

delei · 2026-08-03T12:38:59Z

At docs/sheet/fill/#simple-fill

The change was from John Doe to John.
However, C2, D2 still hold John Doe.

I am also confused by this change, because other sections still use John Doe. For consistency, it might be better to stick with 1 option for all sections, either John or John Doe.

Btw, I just noticed a problem with the data() function. The write docs define their data(), but the fill docs don't. This is at least inconsistent. Also, it can be confusing for junior readers.
Do you think it might be worth adding smth like this:

Data List

The examples further down all fill from this helper:
private List<FillData> data() {
    List<FillData> list = ListUtils.newArrayList();
    for (int i = 0; i < 10; i++) {
        FillData fillData = new FillData();
        fillData.setName("John Doe" + i);
        fillData.setNumber(5.2);
        fillData.setDate(new Date());
        list.add(fillData);
    }
    return list;
}
If we do this, note that at docs/sheet/fill/#horizontal-fill in the results table, you removed columns from G to L. This implies cutting the filled data from 10 items to 4, which would violate data() count. The fix would be to add a ⋯ column, as we do at docs/sheet/fill/#fill-multiple-lists-together in the results tables.

At docs/sheet/write/image.md:191

I think there is a typo.Fefault should be Default

At docs/sheet/write/extra.md:25

The merged section was removed, but we still mention it: This chapter introduces how to write extra information such as comments, hyperlinks, formulas, merged cells, etc. The fix:
This chapter introduces how to write extra information such as comments, hyperlinks, formulas, etc.

Thank you for the review. These have been revised and completed.

nkuprins · 2026-08-03T13:16:01Z

LGTM

Copilot

Pull request overview

Note

Copilot couldn't run its full agentic review because it didn't start before the timeout. Make sure your repository has a runner available, or add a copilot-code-review.yml file specifying one with the runs-on attribute. See the docs for more details.

Updates the write/fill documentation to replace screenshot-based results with HTML/CSS-rendered “Excel-like” grids, improving alignment between examples and outputs and consolidating/expanding explanations.

Changes:

Add a dedicated xl-sheet.css stylesheet and wire it into Docusaurus to style spreadsheet-like result grids.
Replace many PNG screenshots in write/fill docs (English + zh-cn) with HTML table grids and updated narrative/code snippets.
Relax markdownlint’s inline-HTML allowlist to permit elements used by the new grids.

Reviewed changes

Copilot reviewed 23 out of 55 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
website/static/img/docs/write/sample-image.svg	Adds an SVG placeholder image used by the new grid-based image examples.
website/src/css/xl-sheet.css	Introduces the core CSS for rendering Excel-like grids with light/dark styling and overlays.
website/i18n/zh-cn/docusaurus-plugin-content-docs/current/sheet/write/style.md	Replaces screenshot results with HTML grids for style examples (zh-cn).
website/i18n/zh-cn/docusaurus-plugin-content-docs/current/sheet/write/simple.md	Updates sample strings and adds a rendered result grid (zh-cn).
website/i18n/zh-cn/docusaurus-plugin-content-docs/current/sheet/write/sheet.md	Replaces screenshots with grids; updates table-writing snippet and adds explanatory note (zh-cn).
website/i18n/zh-cn/docusaurus-plugin-content-docs/current/sheet/write/pojo.md	Expands column include/exclude/index ordering explanations and adds grids (zh-cn).
website/i18n/zh-cn/docusaurus-plugin-content-docs/current/sheet/write/merge.md	Replaces ASCII-art result with an HTML grid using rowspan (zh-cn).
website/i18n/zh-cn/docusaurus-plugin-content-docs/current/sheet/write/image.md	Reworks image docs (sources, multi-image cells, URL policy) and replaces screenshots with grids (zh-cn).
website/i18n/zh-cn/docusaurus-plugin-content-docs/current/sheet/write/head.md	Corrects merge strategy explanations and adds one grid per strategy (zh-cn).
website/i18n/zh-cn/docusaurus-plugin-content-docs/current/sheet/write/format.md	Replaces screenshot output with an HTML grid (zh-cn).
website/i18n/zh-cn/docusaurus-plugin-content-docs/current/sheet/write/extra.md	Replaces screenshots with grids for comments/hyperlinks/formulas/dropdowns; removes merged-cells section (zh-cn).
website/i18n/zh-cn/docusaurus-plugin-content-docs/current/sheet/fill/fill.md	Adds placeholder syntax section and replaces template/result screenshots with grids (zh-cn).
website/docusaurus.config.js	Adds `xl-sheet.css` to the site’s custom CSS pipeline.
website/docs/sheet/write/style.md	Replaces screenshots with grids; updates titles/log text to English.
website/docs/sheet/write/simple.md	Adds a missing rendered result grid and updates header titles to English.
website/docs/sheet/write/sheet.md	Replaces screenshots with grids; updates table-writing snippet and adds explanatory note.
website/docs/sheet/write/pojo.md	Expands include/exclude/index/ordering guidance and replaces screenshots with grids.
website/docs/sheet/write/merge.md	Replaces ASCII-art result with an HTML grid using rowspan.
website/docs/sheet/write/image.md	Reworks image docs (sources, multi-image cells, URL policy) and replaces screenshots with grids.
website/docs/sheet/write/head.md	Corrects merge strategy wording and adds one grid per strategy.
website/docs/sheet/write/format.md	Adjusts date format example and replaces screenshot output with an HTML grid.
website/docs/sheet/write/extra.md	Removes merged-cells section from this page; shows comments/hyperlinks/formulas/dropdowns via grids.
website/docs/sheet/fill/fill.md	Adds placeholder syntax section and replaces template/result screenshots with grids.
website/.markdownlint-cli2.jsonc	Re-formats config and expands MD033 allowlist to include `div` and `p` for the new grids.

nkuprins · 2026-08-03T22:22:54Z

+[data-theme='dark'] {
+    .xl-sheet-container {
+        border: none;
+        background: rgba(255, 255, 255, 0.05);
+    }
+
+    .xl-sheet .xl-chrome {
+        background: rgba(255, 255, 255, 0.05);
+        color: var(--xl-white);
+        border-color: rgba(255, 255, 255, 0.05);
+    }


@delei For context: Native CSS nesting has been available since April-August 2023

bengbengbalabalabeng added the PR: developing This feature will be added in future releases label Jul 28, 2026

nkuprins and others added 12 commits August 1, 2026 01:38

docs: shorten result tables in write/style

cd89259

Each grid keeps its first and last data rows with an ellipsis row between, and uses the value-named style classes.

docs: document placeholder syntax in fill

b5a532a

Adds a table of the {name}, {.name}, {list.name} and escaped forms with what fills each, plus notes on mixing placeholders with text and on unfilled placeholders being cleared. Result grids are shortened.

docs: shorten result table in write/format

b75d11c

Drops the trailing empty column and the repeated data rows.

docs: show the result of every header merge strategy

27f5c2d

The strategy example now uses a three-level header where names repeat in both directions, with one grid per strategy, and explains why AUTO leaves a vertical merge below the first header row unmerged.

docs: rewrite write/image around image sources

018e489

Adds a table mapping each field type to its converter, notes that a picture is stretched to its cell, and documents the multi-image WriteCellData form. The result screenshots become grids drawing a sample SVG.

docs: add sheet tabs to write/sheet results

bdb7574

The grids now carry the sheet tabs they produce, so the single-sheet, multi- sheet and table results are told apart, with a line on what each writes.

docs: add the result grid to write/simple

0ec9035

Shows what the three approaches write. The Chinese page also switches its sample data to 字符串, matching write/merge.

docs: replace the last write/extra screenshots with grids

2ab289d

The comment and dropdown results are drawn open in the grid, and the dropdown handler gains the usage snippet that registers it.

docs: drop the write screenshots replaced by inline grids

cd481c6

The 19 PNGs under static/img/docs/write are no longer referenced by any page.

Merge branch 'main' into docs/inline-spreadsheet-tables

5dc0b4d

nkuprins changed the title ~~docs: replace screenshots with inline HTML tables in write/fill docs~~ docs: expand the write/fill pages and replace their screenshots with grids Jul 31, 2026

docs: drop the fill screenshots replaced by inline grids

5fd567e

Includes listFill_file.png, which only appears as a path inside a code sample in the contribute-doc guide and is not loaded by any page.

nkuprins marked this pull request as ready for review July 31, 2026 23:43

bengbengbalabalabeng removed the PR: developing This feature will be added in future releases label Aug 1, 2026

Merge branch 'main' into docs/inline-spreadsheet-tables

aecc7f4

delei added 6 commits August 2, 2026 17:35

style: update xl-sheet styles and enhance dark theme support

60ff3d0

docs: update comment text and wrap tables with container div

c664205

docs: update comment text and wrap tables with container div

3dfd9c3

chore: update markdownlint configuration formatting and allowed elements

1d4c081

style: update colors and refine layout styles

bd4d3f5

docs: enhance image writing documentation and fix formatting issues

3864f96

Merge branch 'docs/inline-spreadsheet-tables' of https://github.com/n…

35fbac1

…kuprins/fesod into pr/979

delei added 3 commits August 2, 2026 23:23

style: update background color styling in table cells

7c9ff56

style: fix table row class attribute in image markdown files

425abf0

style: set default text color for table cells

31d66ce

delei and others added 5 commits August 3, 2026 20:35

Merge branch 'main' into docs/inline-spreadsheet-tables

9fc8e9e

docs: remove merged cells from extra information description

674d864

docs: add data list example and update table layout

70ae2ba

fix: correct typo in image.md

f7cc3d3

Merge branch 'docs/inline-spreadsheet-tables' of https://github.com/n…

6e0fbf3

…kuprins/fesod into pr/979

alaahong requested a review from Copilot August 3, 2026 15:30

Copilot AI reviewed Aug 3, 2026

View reviewed changes

Copilot started reviewing on behalf of alaahong August 3, 2026 17:37 View session

nkuprins added 4 commits August 4, 2026 00:57

chore: remove duplicate img entry from MD033 allowed_elements

77e28bc

fix: replace Chinese commas with ASCII commas in English fill.md

f6c5956

fix: correct fetch policies wording

90ebbcc

fix: wrap zh-cn image grids in the sheet container

4323557

bengbengbalabalabeng reviewed Aug 4, 2026

View reviewed changes

Comment thread website/src/css/xl-sheet.css

bengbengbalabalabeng reviewed Aug 4, 2026

View reviewed changes

Comment thread website/src/css/xl-sheet.css

style: add border-radius and margin-left styles

81d1364

Uh oh!

Conversation

nkuprins commented Jul 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Purpose of the pull request

What's changed?

Collaboration

Browsers

Chinese

Checklist

Uh oh!

nkuprins commented Jul 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

delei commented Aug 2, 2026

Uh oh!

nkuprins commented Aug 2, 2026

Uh oh!

delei commented Aug 2, 2026

Uh oh!

nkuprins commented Aug 2, 2026

Uh oh!

delei commented Aug 2, 2026

Uh oh!

nkuprins commented Aug 2, 2026

Before:

Now:

Uh oh!

nkuprins commented Aug 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

nkuprins commented Aug 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Data List

Uh oh!

nkuprins commented Aug 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

delei commented Aug 3, 2026

Data List

Uh oh!

nkuprins commented Aug 3, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

nkuprins Aug 3, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

nkuprins commented Jul 28, 2026 •

edited

Loading

nkuprins commented Jul 28, 2026 •

edited

Loading

nkuprins commented Aug 2, 2026 •

edited

Loading

nkuprins commented Aug 2, 2026 •

edited

Loading

nkuprins commented Aug 2, 2026 •

edited

Loading