# SheetJS CE Docs

Hosted URL: <https://docs.sheetjs.com>

## Development

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.

`docz/version.js` exports a version number for use in docs pages.

### Build Commands

```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/).

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>
```

</details>


### 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.

### Formats Graph

The formats graph and legend are written in the DOT language. Rebuilding the
graphs will require Graphviz (`brew install graphviz` on macOS)

## Live Demos

<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.

### Page-Specific Scripts

**Imports do not work from live codeblocks!**

Docusaurus does not have an official recommendation for this workflow.

Specific pages can load scripts using the `head` component:

```html
<head>
  <script src="https://cdn.sheetjs.com/xspreadsheet/xlsxspread.min.js"></script>
</head>
```

**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> );
}
```

## Other Notes

`src/theme/Admonition` was swizzled from 3.2.1 to enable `pass` for hiding
header text. See Docusaurus issue 8568 for more details.

`src/theme/prism-include-languages.js` was swizzled from 3.2.1 to support the
Liquid language. See Docusaurus issue 6872 for more details.