-
- );
+ );
}
```
diff --git a/docz/docs/07-csf/07-features/12-props.md b/docz/docs/07-csf/07-features/12-props.md
new file mode 100644
index 0000000..8a12507
--- /dev/null
+++ b/docz/docs/07-csf/07-features/12-props.md
@@ -0,0 +1,164 @@
+---
+title: File Properties
+sidebar_position: 12
+---
+
+
+ File Format Support (click to show)
+
+Excel supports a number of standard properties. Most modern versions of Excel
+also support custom properties.
+
+| Formats | Standard | Custom | Separate |
+|:----------|:--------:|:-------|----------|
+| XLSX/XLSM | ✔ | ✔ | ✔ |
+| XLSB | ✔ | ✔ | ✔ |
+| XLML | ✔ | ✔ | ✔ |
+| BIFF8 XLS | ✔ | ✔ | |
+| BIFF5 XLS | R | R | |
+
+The letter R (R) marks features parsed but not written in the format.
+
+The "Separate" column marks formats that store standard and custom properties
+in different locations. Legacy XLS files commingle properties.
+
+
+
+Modern spreadsheet software support special file properties including titles and
+keywords. Third-party tools can understand the file properties without having to
+process or understand the spreadsheet structure.
+
+In the SheetJS Data Model, the workbook object `Props` property holds standard
+properties and the `Custprops` property holds custom properties.
+
+## Live Demo
+
+The following demo generates `SheetJSProperties.xlsx` with two file properties:
+
+- The standard `Title` property will be set to `SheetJS Properties Test`. This
+ will be displayed in the "Summary" tab of the Excel file properties dialog:
+
+
+
+- The custom `Custom Quip` property will be set to `Get Sheet Done`. This will
+ be displayed in the "Properties" table in the "Custom" tab of the dialog:
+
+
+
+
+```jsx live
+function SheetJSPropertiesExport() { return (); }
+```
+
+## Spreadsheet Applications
+
+Spreadsheet applications commonly display file properties in separate windows:
+
+- Excel for Windows: select "File" above the ribbon bar, select "Info" in the
+ left sidebar, and click Properties > Advanced Properties
+
+- Excel for Mac: select "File" in the menu bar and select "Properties"
+
+- WPS Office: select "Menu" > "Document Encryption" > "Properties"
+
+:::note pass
+
+When this demo was last tested, Apple Numbers (14.2, build 7041.0.109) did not
+support file properties in the XLSX import and export codecs.
+
+:::
+
+## Standard Properties
+
+Some properties cannot be changed in spreadsheet applications. The underlying
+SheetJS output codecs can write arbitrary values.
+
+The `Props` object understands the "standard" properties listed in the following
+table. "SheetJS Name" refers to the name of the property in the `Props` object.
+"Excel Property Setting" refers to the name in the Excel file properties dialog.
+
+| SheetJS Name | Excel Property Setting |
+|:--------------|:-------------------------------|
+| `Title` | Summary tab "Title" |
+| `Subject` | Summary tab "Subject" |
+| `Author` | Summary tab "Author" |
+| `Manager` | Summary tab "Manager" |
+| `Company` | Summary tab "Company" |
+| `Category` | Summary tab "Category" |
+| `Keywords` | Summary tab "Keywords" |
+| `Comments` | Summary tab "Comments" |
+| `LastAuthor` | Statistics tab "Last saved by" |
+| `CreatedDate` | Statistics tab "Created" |
+
+It is strongly recommended to test if the `Props` property exists:
+
+```js title="Set the 'Title' file property"
+/* ensure `Props` exists */
+if(!wb.Props) wb.Props = {};
+
+/* set `Title` property */
+wb.Props.Title = "SheetJS Properties Test";
+```
+
+## Custom Properties
+
+Custom properties are added in the workbook `Custprops` object. As with `Props`,
+scripts should test for the existence of the `Custprops` property:
+
+```js title="Set the 'Custom Quip' custom file property"
+/* ensure `Custprops` exists */
+if(!wb.Custprops) wb.Custprops = {};
+
+/* set `Custom Quip` property */
+wb.Custprops["Custom Quip"] = "Get Sheet Done";
+```
+
+## Export Override
+
+The SheetJS `write` and `writeFile` methods[^2] accept options. The `Props`
+option instructs the writer to override properties from the workbook object.
+
+In the following example, the workbook object sets the "Title" and "Keywords"
+standard properties. `writeFile` will override the "Keywords" property and add
+the "Category" property. The generated file will have the following properties:
+
+- "Title" will be set to "SheetJS Properties Test" (from the workbook object)
+- "Keywords" will be blank (overridden by `writeFile` option)
+- "Category" will be "Sheetpost" (assigned through `writeFile` option)
+
+
+```jsx live
+function SheetJSPropertiesOverride() { return (); }
+```
+
+[^1]: See [`write` and `writeFile` in "Writing Files"](/docs/api/write-options)
\ No newline at end of file
diff --git a/docz/docs/09-miscellany/05-contributing.md b/docz/docs/09-miscellany/05-contributing.md
index 1e69657..f75203e 100644
--- a/docz/docs/09-miscellany/05-contributing.md
+++ b/docz/docs/09-miscellany/05-contributing.md
@@ -41,7 +41,7 @@ These instructions were tested on the following platforms:
| Platform | Architecture | Test Date |
|:------------------------------|:-------------|:-----------|
-| Linux (Steam Deck Holo x64) | `linux-x64` | 2024-07-12 |
+| Linux (Steam Deck Holo x64) | `linux-x64` | 2024-09-20 |
| Linux (Arch Linux AArch64) | `linux-arm` | 2024-05-10 |
| MacOS 14.4 (x64) | `darwin-x64` | 2024-07-12 |
| MacOS 14.5 (ARM64) | `darwin-arm` | 2024-05-23 |
@@ -302,6 +302,17 @@ sudo pacman-key --populate
sudo pacman-key --refresh-keys
```
+:::caution pass
+
+When this demo was last tested, keys were refreshed after 25 minutes.
+
+**Do not switch to gaming mode or let the device sleep during the process!**
+
+To ensure the device does not sleep, click the battery icon in the lower right
+corner of the screen and enable "Manually block sleep and screen locking".
+
+:::
+
4) Install dependencies:
```bash
@@ -325,8 +336,6 @@ These packages are *not required* for building or testing the library.
B) Install NodeJS.
-:::note pass
-
[The official NodeJS site](https://nodejs.org/en/download/) provides Linux
binaries, but it is strongly recommended to use `nvm` to install NodeJS:
@@ -334,15 +343,25 @@ binaries, but it is strongly recommended to use `nvm` to install NodeJS:
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.5/install.sh | bash
```
-After installing, start a new terminal session and install NodeJS "LTS":
+After installing `nvm`, start a new terminal session and install NodeJS "LTS":
```bash
nvm install --lts
+node --version
```
-After installing, if running `node` in the terminal fails with a `glibc` error,
-an older version of NodeJS should be installed. For example, Ubuntu 18.04 does
-not support Node 18 but supports Node 16.20.0:
+:::note pass
+
+If the `nvm` command cannot be found, close the current terminal session and
+start a new session.
+
+:::
+
+:::caution pass
+
+If the `node` command fails with a `glibc` error, an older version of NodeJS
+must be installed. For example, Ubuntu 18.04 does not support Node 18 but does
+support Node 16.20.0:
```bash
nvm install 16
diff --git a/docz/static/props/custom-quip.png b/docz/static/props/custom-quip.png
new file mode 100644
index 0000000..b3d1a82
Binary files /dev/null and b/docz/static/props/custom-quip.png differ
diff --git a/docz/static/props/standard-title.png b/docz/static/props/standard-title.png
new file mode 100644
index 0000000..1605563
Binary files /dev/null and b/docz/static/props/standard-title.png differ