docs.sheetjs.com/README.md

146 lines
3.4 KiB
Markdown
Raw Normal View History

2022-05-16 03:26:04 +00:00
# SheetJS CE Docs
2022-05-11 21:03:03 +00:00
2022-05-16 03:26:04 +00:00
Hosted URL: <https://docs.sheetjs.com>
2022-08-26 19:21:53 +00:00
## Development
2023-09-11 06:53:53 +00:00
The site source code is in the `docz` folder. `make` builds the static site and
moves the generated pages and scripts to the `docs` folder.
2022-08-26 19:21:53 +00:00
`docz/version.js` exports a version number for use in docs pages.
2023-09-11 06:53:53 +00:00
### Build Commands
2022-08-26 19:21:53 +00:00
```bash
$ make init # install dependencies
$ make # build static site
$ make serve # serve static site
$ make dev # run dev server
$ make spell # spell check (.spelling custom dictionary)
$ make graph # build format graph and legend
```
### Documentation Markup
The original documentation used [GFM](https://github.github.com/gfm/).
2024-04-14 07:05:36 +00:00
Pages currently use MDX v2.
<details>
<summary><b>MDX Notes</b> (click to show)</summary>
**Multi-line tags**
Markdown and MDX v1 accept the following:
```
<details><summary><b>MDX Notes</b> (click to show)</summary>
Note
</details>
```
This is no longer valid in MDX v2. The `<summary>` part must be separated:
```
<details>
<summary><b>MDX Notes</b> (click to show)</summary>
Note
</details>
```
**Shortlinks**
Markdown and MDX v1 support shortlinks:
```
Scripts are available at <https://cdn.sheetjs.com>
```
This is no longer valid in MDX v2. Autolinks should be used:
```
Scripts are available at https://cdn.sheetjs.com
```
**Variables**
Patterns such as
```
<a href={`Foo${current}`}>Foo{current}</a>
```
do not work in MDX v2. Instead, string literals and concatenation must be used:
```
<a href={"Foo" + current + ""}>{"Foo" + current + ""}</a>
```
2024-06-09 03:40:45 +00:00
**Tables**
MDX inconsistently requires different indentation levels for `TD` / `TH`, `TR`,
`THEAD` / `TBODY` / `TFOOT`, and `TABLE` tags. Unconventional indentation is
intentional.
</details>
2024-03-12 06:47:52 +00:00
### Engine Compatibility Tables
`docz/src/data/engines.xls` is an XLML workbook that controls the compatibility
tables in <https://docs.sheetjs.com/docs/demos/engines/>. The component script
`docz/src/data/engines.js` parses the file and generates content.
2023-09-11 06:53:53 +00:00
### Formats Graph
2022-08-26 19:21:53 +00:00
2023-09-11 06:53:53 +00:00
The formats graph and legend are written in the DOT language. Rebuilding the
graphs will require Graphviz (`brew install graphviz` on macOS)
## Live Demos
2022-08-26 19:21:53 +00:00
<https://cdn.sheetjs.com/xlsx-latest/package/dist/xlsx.full.min.js> is loaded
on each page, making the `XLSX` variable available to live blocks.
2023-09-11 06:53:53 +00:00
### Page-Specific Scripts
**Imports do not work from live codeblocks!**
Docusaurus does not have an official recommendation for this workflow.
2022-08-26 19:21:53 +00:00
Specific pages can load scripts using the `head` component:
```html
<head>
<script src="https://cdn.sheetjs.com/xspreadsheet/xlsxspread.min.js"></script>
</head>
```
2023-09-11 06:53:53 +00:00
**Adding scripts through `head` is known to be brittle!**
Live codeblocks that use external libraries in `useEffect` hooks should check
before using variables. For example, the Dropbox live demo tests if `Dropbox` is
defined before proceeding. If it is not defined, a message is displayed.
```jsx
function SheetJSTestDropbox() {
const [msg, setMsg] = React.useState("Dropbox is defined");
React.useEffect(() => {
if(typeof Dropbox == "undefined") return setMsg("Dropbox is not defined");
}, []);
return ( <b>{msg}</b> );
}
```
2023-06-20 01:21:34 +00:00
## Other Notes
2024-04-12 01:04:37 +00:00
`src/theme/Admonition` was swizzled from 3.2.1 to enable `pass` for hiding
2023-09-11 06:53:53 +00:00
header text. See Docusaurus issue 8568 for more details.
2024-04-12 01:04:37 +00:00
`src/theme/prism-include-languages.js` was swizzled from 3.2.1 to support the
2023-09-11 06:53:53 +00:00
Liquid language. See Docusaurus issue 6872 for more details.