diff --git a/docs/.vuepress/collections/en/theme-guide.ts b/docs/.vuepress/collections/en/theme-guide.ts index d5baea4e..1b5ebf42 100644 --- a/docs/.vuepress/collections/en/theme-guide.ts +++ b/docs/.vuepress/collections/en/theme-guide.ts @@ -41,6 +41,7 @@ export const themeGuide: ThemeCollectionItem = defineCollection({ items: [ 'basic', 'extensions', + 'table', 'icons', 'mark', 'plot', diff --git a/docs/en/guide/markdown/table.md b/docs/en/guide/markdown/table.md new file mode 100644 index 00000000..4d37498d --- /dev/null +++ b/docs/en/guide/markdown/table.md @@ -0,0 +1,337 @@ +--- +title: Table Enhancement +icon: mdi:table-plus +createTime: 2025/10/13 16:57:42 +permalink: /en/guide/markdown/table/ +badge: New +--- + +## Overview + +The default table functionality in Markdown is relatively basic. +However, in practical usage scenarios, it is often necessary to add additional information to tables, +such as a table title, or extra features like the ability to copy table content. + +Without breaking the table syntax, the theme provides a `::: table` container to conveniently extend table capabilities. + +::: tip The table enhancement container is under continuous development. +If you have suggestions for other features, please provide feedback via an [Issue](https://github.com/pengzhanbo/vuepress-theme-plume/issues). +::: + +## Configuration + +This feature is disabled by default. You need to enable it in your `theme` configuration. + +```ts title=".vuepress/config.ts" +export default defineUserConfig({ + theme: plumeTheme({ + markdown: { + // table: true, // Enable default features + table: { + // Default table alignment: 'left' | 'center' | 'right' + align: 'left', + // Whether the table width is the max-content width + // Inline elements will not wrap automatically; a scrollbar is displayed when the content exceeds the container width. + maxContent: false, + /** + * Copy as HTML/Markdown + * `true` is equivalent to `'all'`, enabling both HTML and Markdown copying. + */ + copy: true, // true | 'all' | 'html' | 'md' + } + }, + }) +}) +``` + +## Syntax + +Simply wrap the table within a `:::table` block. + +```md +:::table title="Title" align="center" max-content copy="all" +| xx | xx | xx | +| -- | -- | -- | +| xx | xx | xx | +::: +``` + +### Props + +:::: field-group + +::: field name="title" type="string" optional +Table title, displayed below the table. +::: + +::: field name="align" type="'left' | 'center' | 'right'" optional default="'left'" +Table alignment. +::: + +::: field name="copy" type="boolean | 'all' | 'html' | 'md'" optional default="true" +Displays a copy button in the top-right corner of the table for copying as HTML or Markdown. + +- `true` is equivalent to `'all'`. +- `false` hides the copy button. +- `'all'` enables both `'html'` and `'md'` copying. +- `'html'` enables copying as HTML. +- `'md'` enables copying as Markdown. +::: + +::: field name="maxContent" type="boolean" optional default="false" +Inline elements will not wrap automatically; a scrollbar is displayed when the content exceeds the container width. +::: + +::: field name="hl-rows" type="string" optional +Configures row highlighting within the table. + +The value uses the format `type:row1,row2`. Multiple type-row pairs can be combined using `;`. + +Examples: + +- `hl-rows="warning:1"`: Sets the first row to the warning color. +- `hl-rows="danger:1,2"`: Sets the first and second rows to the danger color. +- `hl-rows="warning:1,2;danger:3,4"`: Sets the first and second rows to the warning color, and the third and fourth rows to the danger color. + +Built-in `type` support: `tip`, `note`, `info`, `success`, `warning`, `danger`, `caution`, `important`. + +`row` counting starts from 1. +::: + +::: field name="hl-cols" type="string" optional +Configures column highlighting within the table. + +The value uses the format `type:col1,col2`. Multiple type-column pairs can be combined using `;`. + +Examples: + +- `hl-cols="warning:1"`: Sets the first column to the warning color. +- `hl-cols="danger:1,2"`: Sets the first and second columns to the danger color. +- `hl-cols="warning:1,2;danger:3,4"`: Sets the first and second columns to the warning color, + and the third and fourth columns to the danger color. + +Built-in `type` support: `tip`, `note`, `info`, `success`, `warning`, `danger`, `caution`, `important`. + +`col` counting starts from 1. +::: + +::: field name="hl-cells" type="string" optional +Configures cell highlighting within the table. + +The value uses the format `type:(row,col)`. Multiple type-cell pairs can be combined using `;`. + +Examples: + +- `hl-cells="warning:(1,1)"`: Sets the cell at row 1, column 1 to the warning color. +- `hl-cells="danger:(1,1)(2,2)"`: Sets the cells at (1,1) and (2,2) to the danger color. +- `hl-cells="warning:(1,1)(2,2);danger:(3,3)(4,4)"`: Sets the cells at (1,1) and (2,2) to the warning color, + and the cells at (3,3) and (4,4) to the danger color. + +Built-in `type` support: `tip`, `note`, `info`, `success`, `warning`, `danger`, `caution`, `important`. + +`row` counting starts from 1, `col` counting starts from 1. +::: +:::: + +## Examples + +### Table Title + +**Input:** + +```md +::: table title="This is the Table Title" +| Header 1 | Header 2 | Header 3 | +|----------|----------|----------| +| Cell 1 | Cell 2 | Cell 3 | +| Row 2 | Data | Info | +::: +``` + +**Output:** + +::: table title="This is the Table Title" + +| Header 1 | Header 2 | Header 3 | +|----------|----------|----------| +| Cell 1 | Cell 2 | Cell 3 | +| Row 2 | Data | Info | + +::: + +### Table Alignment + +**Input:** + +```md +::: table title="This is the Table Title" align="center" +| Header 1 | Header 2 | Header 3 | +|----------|----------|----------| +| Cell 1 | Cell 2 | Cell 3 | +| Row 2 | Data | Info | +::: +``` + +**Output:** + +::: table title="This is the Table Title" align="center" + +| Header 1 | Header 2 | Header 3 | +|----------|----------|----------| +| Cell 1 | Cell 2 | Cell 3 | +| Row 2 | Data | Info | + +::: + +### Table Max Content Width + +**Input:** + +```md +:::table title="This is the Table Title" max-content + +| ID | Description | Status | +|----|-----------------------------------------------------------------------------|--------------| +| 1 | This is an extremely long description that should trigger text wrapping in most table implementations. | In Progress | +| 2 | Short text | ✅ Completed | +::: +``` + +**Output:** + +:::table title="This is the Table Title" max-content + +| ID | Description | Status | +|----|-----------------------------------------------------------------------------|--------------| +| 1 | This is an extremely long description that should trigger text wrapping in most table implementations. | In Progress | +| 2 | Short text | ✅ Completed | + +::: + +### Table Row Highlighting + +**Input:** + +```md +::: table title="This is the Table Title" hl-rows="tip:1;warning:2;important:3,4" +| row1 | row1 | row1 | +| ---- | ---- | ---- | +| row2 | row2 | row2 | +| row3 | row3 | row3 | +| row4 | row4 | row4 | +::: +``` + +**Output:** + +::: table title="This is the Table Title" hl-rows="tip:1;warning:2;important:3,4" + +| row1 | row1 | row1 | +| ---- | ---- | ---- | +| row2 | row2 | row2 | +| row3 | row3 | row3 | +| row4 | row4 | row4 | + +::: + +### Table Column Highlighting + +**Input:** + +```md +::: table title="This is the Table Title" hl-cols="success:1;warning:2;danger:3,4" +| col1 | col2 | col3 | col4 | +| ---- | ---- | ---- | ---- | +| col1 | col2 | col3 | col4 | +| col1 | col2 | col3 | col4 | +| col1 | col2 | col3 | col4 | +::: +``` + +**Output:** + +::: table title="This is the Table Title" hl-cols="success:1;warning:2;danger:3,4" + +| col1 | col2 | col3 | col4 | +| ---- | ---- | ---- | ---- | +| col1 | col2 | col3 | col4 | +| col1 | col2 | col3 | col4 | +| col1 | col2 | col3 | col4 | + +::: + +### Table Cell Highlighting + +**Input:** + +```md +::: table title="This is the Table Title" hl-cells="danger:(1,1)(2,2);success:(3,3)(4,4);warning:(1,4)(2,3);important:(3,2)(4,1)" +| (1,1) | (1,2) | (1,3) | (1,4) | +| ----- | ----- | ----- | ----- | +| (2,1) | (2,2) | (2,3) | (2,4) | +| (3,1) | (3,2) | (3,3) | (3,4) | +| (4,1) | (4,2) | (4,3) | (4,4) | +::: +``` + +**Output:** + +::: table title="This is the Table Title" hl-cells="danger:(1,1)(2,2);success:(3,3)(4,4);warning:(1,4)(2,3);important:(3,2)(4,1)" + +| (1,1) | (1,2) | (1,3) | (1,4) | +| ----- | ----- | ----- | ----- | +| (2,1) | (2,2) | (2,3) | (2,4) | +| (3,1) | (3,2) | (3,3) | (3,4) | +| (4,1) | (4,2) | (4,3) | (4,4) | + +::: + +## Custom Highlight Types + +In [Custom CSS Styles](../custom/style.md), custom highlight types can be defined using the following format: + +```css +.vp-table table th.type, +.vp-table table td.type { + color: #000; + background-color: #fff; +} +``` + +For example, to add a `blue` highlight type: + +```css +.vp-table table th.blue, +.vp-table table td.blue { + color: #4a7cb9; + background-color: #a3c6e5; +} +``` + + + +This custom type can then be used in tables: + +```md +::: table hl-rows="blue:1" hl-cols="blue:1" hl-cells="blue:(3,3)" +| Header 1 | Header 2 | Header 3 | +| -------- | -------- | -------- | +| Cell 1 | Cell 2 | Cell 3 | +| Cell 4 | Cell 5 | Cell 6 | +::: +``` + +::: table hl-rows="blue:1" hl-cols="blue:1" hl-cells="blue:(3,3)" + +| Header 1 | Header 2 | Header 3 | +| -------- | -------- | -------- | +| Cell 1 | Cell 2 | Cell 3 | +| Cell 4 | Cell 5 | Cell 6 | + +:::