Skip to content

Commit cdb9297

Browse files
arnogarnog
committed
perf
1 parent a295d5d commit cdb9297

35 files changed

+445
-53
lines changed

‎CLAUDE.md‎

Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
# CLAUDE.md
2+
3+
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4+
5+
## Common Development Commands
6+
7+
### Development
8+
- `npm start` - Start local development server (runs Docusaurus in dev mode)
9+
- `npm run build` - Build the site (runs `bash scripts/build.sh`)
10+
- `npm run serve` - Serve the built site locally
11+
12+
### Content Updates
13+
- `npm run update` - Update dependent modules and regenerate API docs
14+
- `npm run stage` - Create production build in `submodules/cortex-js.github.io/`
15+
- `npm run deploy` - Deploy staged changes to GitHub Pages
16+
17+
### Utility Commands
18+
- `npm run clear` - Clear Docusaurus cache
19+
- `npm run swizzle` - Eject Docusaurus components for customization
20+
21+
## High-Level Architecture
22+
23+
This is a Docusaurus-based documentation website for the CortexJS ecosystem (MathLive and Compute Engine).
24+
25+
### Key Architecture Components
26+
27+
**Documentation Pipeline:**
28+
- Source content in `docs/` (Markdown files)
29+
- API documentation auto-generated from TypeScript `.d.ts` files using typedoc
30+
- Build scripts in `scripts/` orchestrate changelog and API file generation
31+
- Docusaurus processes everything into static HTML/CSS
32+
33+
**Deployment Strategy:**
34+
- Built site outputs to `submodules/cortex-js.github.io/` (a Git submodule)
35+
- This submodule is linked to the `cortex-js.github.io` repository
36+
- GitHub Pages serves the site from that repository at `cortexjs.io`
37+
38+
**External Dependencies:**
39+
- References `../mathlive/` and `../compute-engine/` for source API files
40+
- Changelog and API content is copied from these sibling repositories during build
41+
42+
### Directory Structure
43+
44+
- `docs/` - Markdown documentation source files
45+
- `compute-engine/` - Compute Engine documentation
46+
- `mathfield/` - MathLive/Mathfield documentation
47+
- `src/` - React components, pages, and styling
48+
- `components/` - Custom React components (FunctionDefinition, Signature, etc.)
49+
- `pages/` - Docusaurus pages (index.js for homepage)
50+
- `css/` - Global CSS modules
51+
- `build/` - Generated API documentation and knowledge base files
52+
- `scripts/` - Build automation scripts
53+
- `submodules/cortex-js.github.io/` - Deployment target (Git submodule)
54+
55+
### Build Process Flow
56+
57+
1. `scripts/build.sh` copies changelogs from `../mathlive/` and `../compute-engine/`
58+
2. API files are copied and processed from sibling repositories
59+
3. Docusaurus builds the site into `build/` directory
60+
4. In production mode, content is copied to the submodule for deployment
61+
62+
## Development Workflow
63+
64+
### Initial Setup
65+
After cloning, run:
66+
```bash
67+
git submodule init
68+
git submodule update
69+
npm start
70+
```
71+
72+
### Content Updates
73+
When external dependencies have new releases:
74+
```bash
75+
npm run update # Syncs dependent modules
76+
npm start # Regenerates and serves locally
77+
```
78+
79+
### Documentation Authoring
80+
81+
**Tutorial Pages (Guides):**
82+
- Follow introduction → explanation → code examples pattern
83+
- Use `**To <do something>**, <description>` format for mini-recipes
84+
- Explain unfamiliar terms before use
85+
86+
**Reference Pages:**
87+
- Start with hidden TOC div: `<nav className="hidden">### FunctionName</nav>`
88+
- Use `<FunctionDefinition>` and `<Signature>` components for API docs
89+
- Include MathJSON examples and LaTeX examples with `<Latex value="..." />`
90+
91+
### Component Patterns
92+
93+
The codebase uses custom React components:
94+
- `<FunctionDefinition>` - API documentation wrapper
95+
- `<Signature>` - Function signature display
96+
- `<Latex>` - LaTeX rendering
97+
- `<CodePlayground>` - Interactive code examples
98+
99+
CSS follows CSS Modules pattern (`index.module.css` files).
100+
101+
## Testing
102+
103+
No automated test suite exists. Validation consists of:
104+
- Manual verification of build output
105+
- Link checking in generated site
106+
- Visual validation in browser before deployment

‎docs/compute-engine/01-introduction.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -167,7 +167,7 @@ available by default to a `ComputeEngine` instance.
167167
| [Sets](/compute-engine/reference/sets/) | `Union` `Intersection` `EmptySet` `RealNumbers` `Integers` ... |
168168
| [Special Functions](/compute-engine/reference/special-functions/) | `Gamma` `Factorial`... |
169169
| [Statistics](/compute-engine/reference/statistics/) | `StandardDeviation` `Mean` `Erf`... |
170-
| [Styling](/compute-engine/reference/styling/) | `Delimiter` `Style`... |
170+
| [Styling](/compute-engine/reference/styling/) | `Delimiter` `Annotated`... |
171171
| [Trigonometry](/compute-engine/reference/trigonometry/) | `Pi` `Cos` `Sin` `Tan`... |
172172

173173
</div>

‎docs/compute-engine/50-math-json.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -865,7 +865,7 @@ The MathJSON Standard Library includes definitions for:
865865
| [Sets](/compute-engine/reference/sets/) | `Union` `Intersection` `EmptySet` `RealNumbers` `Integers` ... |
866866
| [Special Functions](/compute-engine/reference/special-functions/) | `Gamma` `Factorial`... |
867867
| [Statistics](/compute-engine/reference/statistics/) | `StandardDeviation` `Mean` `Erf`... |
868-
| [Styling](/compute-engine/reference/styling/) | `Delimiter` `Style`... |
868+
| [Styling](/compute-engine/reference/styling/) | `Delimiter` `Annotated`... |
869869
| [Trigonometry](/compute-engine/reference/trigonometry/) | `Pi` `Cos` `Sin` `Tan`... |
870870

871871
</div>

‎docs/compute-engine/79-standard-library.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -39,7 +39,7 @@ the documentation.
3939
| [Special Functions](/compute-engine/reference/special-functions/) | `Gamma` `Factorial`... |
4040
| [Statistics](/compute-engine/reference/statistics/) | `StandardDeviation` `Mean` `Erf`... |
4141
| [Strings](/compute-engine/reference/strings/) | ... |
42-
| [Styling](/compute-engine/reference/styling/) | `Delimiter` `Style`... |
42+
| [Styling](/compute-engine/reference/styling/) | `Delimiter` `Annotated`... |
4343
| [Trigonometry](/compute-engine/reference/trigonometry/) | `Pi` `Cos` `Sin` `Tan`... |
4444

4545
</div>

‎docs/compute-engine/93-reference-styling.md‎

Lines changed: 107 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -69,24 +69,113 @@ The `Spacing` function is **inert** and the value of a `["Spacing", _expr_]` exp
6969

7070

7171

72-
<FunctionDefinition name="Style">
73-
74-
<Signature name="Style">_expr_, _dictionary_</Signature>
75-
76-
77-
78-
- `expr`an expression
79-
- `dictionary`a dictionary with one or more of the following keys:
80-
- `_"display"_`:
81-
- `"inline"` for `\textstyle`
82-
- `"block"` for `\displaystyle`
83-
- `"script"` for `\scriptstyle`
84-
- `"scriptscript"` for `\scriptscriptstyle`
85-
- `_"size"_`: `1`...`10`. Size `5` is normal, size `1` is smallest
86-
- `_"color"_`
87-
88-
89-
The `Style` function is **inert** and the value of a `["Style", _expr_]` expression is `expr`.
72+
<FunctionDefinition name="Annotated">
73+
74+
<Signature name="Annotated" returns="expression">_expr_:expression, dictionary</Signature>
75+
76+
`Annotated(expr, attributes)` is an expression that behaves exactly like `expr`,
77+
but carries **visual or semantic metadata** as an attribute dictionary.
78+
79+
The attributes have no effect on evaluation. This function is inert — it
80+
evaluates to its first argument.
81+
82+
The `attributes` dictionary may include:
83+
84+
* Visual style hints (e.g. `weight: "bold"`, `color: "blue"`)
85+
* Semantic metadata (e.g. `tooltip`, `language`, `link`)
86+
87+
Use `Annotated` when you want to attach presentational or semantic
88+
information to an expression **without affecting its evaluation or identity**.
89+
This is useful for rendering, tooltips, highlighting, etc.
90+
91+
92+
The following keys are applicable to math expressions:
93+
- `mathStyle` = `"compact"` or `"normal"`. The `"compact"` style is used for inline math expressions, while the `"normal"` style is used for display math expressions.
94+
- `scriptLevel` = `0`, `1`, or `-1`, `+1`. The script level is used to
95+
determine the size of the expression in relation to the surrounding text.
96+
A script level of `0` is normal size, `1` is smaller, and `2` is even smaller.
97+
98+
99+
100+
The following keys are applicable to text content:
101+
- `weight` a string, one of `"normal"`, `"bold"`, `"bolder"`, `"light"`
102+
- `style` a string, one of `"normal"`, `"italic"`, `"oblique"`
103+
- `language` a string indicating the language of the expression, e.g. `"en"`, `"fr"`, `"es"` etc.
104+
105+
106+
107+
The following keys are applicable to both math expressions and text content:
108+
- `color` a color name or hex code
109+
- `backgroundColor` a color name or hex code for the background color
110+
- `tooltip` a string to be displayed as a tooltip when the expression is hovered over
111+
- `link` a URL to be followed when the expression is clicked
112+
- `cssClass` a string indicating the CSS class to be applied to the expression
113+
- `cssId` a string indicating the CSS id of the expression
114+
115+
116+
117+
118+
119+
The keys in the dictionary include:
120+
- `style` a string, one of `"normal"`, `"italic"`, `"oblique"`
121+
- `size` a number from `1` to `10` where `5` is normal size
122+
- `font` a string indicating the font family
123+
- `fontSize` a number indicating the font size in pixels
124+
- `fontWeight` a string indicating the font weight, e.g. `"normal"`, `"bold"`, `"bolder"`, `"lighter"`
125+
- `fontStyle` a string indicating the font style, e.g. `"normal"`, `"italic"`, `"oblique"`
126+
- `textDecoration` a string indicating the text decoration, e.g. `"none"`, `"underline"`, `"line-through"`
127+
- `textAlign` a string indicating the text alignment, e.g. `"left"`, `"center"`, `"right"`
128+
- `textTransform` a string indicating the text transformation, e.g. `"none"`, `"uppercase"`, `"lowercase"`
129+
- `textIndent` a number indicating the text indentation in pixels
130+
- `lineHeight` a number indicating the line height in pixels
131+
- `letterSpacing` a number indicating the letter spacing in pixels
132+
- `wordSpacing` a number indicating the word spacing in pixels
133+
- `backgroundColor` a color name or hex code for the background color
134+
- `border` a string indicating the border style, e.g. `"none"`, `"solid"`, `"dashed"`, `"dotted"`
135+
- `borderColor` a color name or hex code for the border color
136+
- `borderWidth` a number indicating the border width in pixels
137+
- `padding` a number indicating the padding in pixels
138+
- `margin` a number indicating the margin in pixels
139+
- `textShadow` a string indicating the text shadow, e.g. `"2px 2px 2px rgba(0,0,0,0.5)"`
140+
- `boxShadow` a string indicating the box shadow, e.g. `"2px 2px 5px rgba(0,0,0,0.5)"`
141+
- `opacity` a number from `0` to `1` indicating the opacity of the expression
142+
- `transform` a string indicating the CSS transform, e.g. `"rotate(45deg)"`, `"scale(1.5)"`, `"translateX(10px)"`
143+
- `transition` a string indicating the CSS transition, e.g. `"all 0.3s ease-in-out"`
144+
- `cursor` a string indicating the cursor style, e.g. `"pointer"`, `"default"`, `"text"`
145+
- `display` a string indicating the CSS display property, e.g. `"inline"`, `"block"`, `"flex"`, `"grid"`
146+
- `visibility` a string indicating the CSS visibility property, e.g. `"visible"`, `"hidden"`, `"collapse"`
147+
- `zIndex` a number indicating the z-index of the expression
148+
- `position` a string indicating the CSS position property, e.g. `"static"`, `"relative"`, `"absolute"`, `"fixed"`
149+
- `float` a string indicating the CSS float property, e.g. `"left"`, `"right"`, `"none"`
150+
- `clear` a string indicating the CSS clear property, e.g. `"left"`, `"right"`, `"both"`, `"none"`
151+
- `overflow` a string indicating the CSS overflow property, e.g. `"visible"`, `"hidden"`, `"scroll"`, `"auto"`
152+
- `overflowX` a string indicating the CSS overflow-x property, e.g. `"visible"`, `"hidden"`, `"scroll"`, `"auto"`
153+
- `overflowY` a string indicating the CSS overflow-y property, e.g. `"visible"`, `"hidden"`, `"scroll"`, `"auto"`
154+
- `whiteSpace` a string indicating the CSS white-space property, e.g. `"normal"`, `"nowrap"`, `"pre"`,
155+
- `textOverflow` a string indicating the CSS text-overflow property, e.g. `"ellipsis"`, `"clip"`
156+
- `direction` a string indicating the text direction, e.g. `"ltr"` (left-to-right) or `"rtl"` (right-to-left)
157+
- `lang` a string indicating the language of the expression, e.g. `"en"` (English), `"fr"` (French), `"es"` (Spanish)
158+
- `role` a string indicating the ARIA role of the expression, e.g. `"button"`, `"link"`, `"textbox"`
159+
- `aria-label` a string providing an accessible label for the expression
160+
- `aria-labelledby` a string providing an accessible label by referencing another element's ID
161+
- `aria-describedby` a string providing an accessible description by referencing another element's ID
162+
- `aria-hidden` a boolean indicating whether the expression is hidden from assistive technologies
163+
- `aria-live` a string indicating the ARIA live region, e.g. `"off"`, `"polite"`, `"assertive"`
164+
- `aria-atomic` a boolean indicating whether assistive technologies should treat the expression as a whole
165+
- `aria-relevant` a string indicating what changes in the expression are relevant to assistive technologies, e.g. `"additions"
166+
- `aria-controls` a string providing the ID of another element that the expression controls
167+
- `aria-expanded` a boolean indicating whether the expression is expanded or collapsed
168+
- `aria-pressed` a boolean indicating whether the expression is pressed (for toggle buttons)
169+
- `aria-selected` a boolean indicating whether the expression is selected
170+
- `aria-checked` a boolean indicating whether the expression is checked (for checkboxes or radio buttons)
171+
- `aria-valuenow` a number indicating the current value of the expression (for sliders or progress bars)
172+
- `aria-valuetext` a string providing a text representation of the current value of the expression
173+
- `aria-valuemin` a number indicating the minimum value of the expression (for sliders or progress bars)
174+
- `aria-valuemax` a number indicating the maximum value of the expression (for sliders or progress bars)
175+
- `aria-keyshortcuts` a
176+
177+
178+
The `Annotated` function is **inert** and the value of a `["Annotated", expr]` expression is `expr`.
90179

91180
</FunctionDefinition>
92181

‎docs/mathfield/05-latex-commands.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1618,12 +1618,12 @@ display on hover.
16181618

16191619
<Latex value="\texttip{e^{i\pi}-1=0}{The most beautiful equation}"/>
16201620

1621-
#### `\mathtip{expression}{hover text}`
1621+
#### `\mathtip{expression}{hover math expression}`
16221622

16231623
The first argument is a math expression to display, the second argument is the
1624-
a math expression to display on hover.
1624+
math expression to display on hover.
16251625

1626-
<Latex value="\mathtip{e^{i\pi}}{-1}"/>
1626+
<Latex value="\mathtip{e^{i\pi}}{e^{i\pi}=1}"/>
16271627

16281628

16291629
### Others

‎docusaurus.config.ts‎

Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -108,6 +108,96 @@ const config: Config = {
108108
onload: "this.media='all'",
109109
},
110110
},
111+
// Preload critical fonts for better performance
112+
{
113+
tagName: 'link',
114+
attributes: {
115+
rel: 'preload',
116+
as: 'font',
117+
type: 'font/woff2',
118+
href: '/fonts/berkeley-mono/BerkeleyMono-Regular.woff2',
119+
crossorigin: 'anonymous',
120+
},
121+
},
122+
{
123+
tagName: 'link',
124+
attributes: {
125+
rel: 'preload',
126+
as: 'font',
127+
type: 'font/woff2',
128+
href: '/fonts/berkeley-mono/BerkeleyMono-Bold.woff2',
129+
crossorigin: 'anonymous',
130+
},
131+
},
132+
// Preload most critical KaTeX fonts from MathLive CDN
133+
{
134+
tagName: 'link',
135+
attributes: {
136+
rel: 'preload',
137+
as: 'font',
138+
type: 'font/woff2',
139+
href: 'https://cdn.jsdelivr.net/npm/mathlive/fonts/KaTeX_Main-Regular.woff2',
140+
crossorigin: 'anonymous',
141+
},
142+
},
143+
{
144+
tagName: 'link',
145+
attributes: {
146+
rel: 'preload',
147+
as: 'font',
148+
type: 'font/woff2',
149+
href: 'https://cdn.jsdelivr.net/npm/mathlive/fonts/KaTeX_Math-Italic.woff2',
150+
crossorigin: 'anonymous',
151+
},
152+
},
153+
{
154+
tagName: 'link',
155+
attributes: {
156+
rel: 'preload',
157+
as: 'font',
158+
type: 'font/woff2',
159+
href: 'https://cdn.jsdelivr.net/npm/mathlive/fonts/KaTeX_AMS-Regular.woff2',
160+
crossorigin: 'anonymous',
161+
},
162+
},
163+
{
164+
tagName: 'link',
165+
attributes: {
166+
rel: 'preload',
167+
as: 'font',
168+
type: 'font/woff2',
169+
href: 'https://cdn.jsdelivr.net/npm/mathlive/fonts/KaTeX_Size1-Regular.woff2',
170+
crossorigin: 'anonymous',
171+
},
172+
},
173+
// Preload hero images for better performance
174+
{
175+
tagName: 'link',
176+
attributes: {
177+
rel: 'preload',
178+
as: 'image',
179+
href: '/img/hand-slugs.jpg',
180+
fetchpriority: 'high',
181+
},
182+
},
183+
{
184+
tagName: 'link',
185+
attributes: {
186+
rel: 'preload',
187+
as: 'image',
188+
href: '/img/hand-gears.jpg',
189+
fetchpriority: 'high',
190+
},
191+
},
192+
{
193+
tagName: 'link',
194+
attributes: {
195+
rel: 'preload',
196+
as: 'image',
197+
href: '/img/hand-cube2.jpg',
198+
fetchpriority: 'high',
199+
},
200+
},
111201
],
112202

113203
clientModules: ['./modules/route-update.js'],

0 commit comments

Comments
 (0)