docz | ||
misc | ||
tests | ||
_headers | ||
.gitattributes | ||
.gitignore | ||
.spelling | ||
formats.png | ||
index.html | ||
legend.png | ||
Makefile | ||
package.json | ||
README.md |
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
$ 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.
Pages currently use MDX v2.
MDX Notes (click to show)
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>
Tables
MDX inconsistently requires different indentation levels for TD
/ TH
, TR
,
THEAD
/ TBODY
/ TFOOT
, and TABLE
tags. Unconventional indentation is
intentional.
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:
<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.
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.