Skip to content

Commit ef054ab

Browse files
bennettgoblebennettgoble
committed
Initial commit
0 parents  commit ef054ab

3,194 files changed

Lines changed: 119710 additions & 0 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/ci.yml‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
name: CI
2+
3+
on:
4+
pull_request:
5+
branches: [main]
6+
push:
7+
branches: [main]
8+
9+
jobs:
10+
build-and-lint:
11+
name: Build and Lint
12+
runs-on: ubuntu-latest
13+
14+
steps:
15+
- name: Checkout code
16+
uses: actions/checkout@v5
17+
18+
- name: Setup Node.js
19+
uses: actions/setup-node@v6
20+
with:
21+
node-version: '24'
22+
23+
- name: Setup pnpm
24+
uses: pnpm/action-setup@v4
25+
with:
26+
version: 10
27+
28+
- name: Get pnpm store directory
29+
id: pnpm-cache
30+
shell: bash
31+
run: |
32+
echo "STORE_PATH=$(pnpm store path)" >> $GITHUB_OUTPUT
33+
34+
- name: Setup pnpm cache
35+
uses: actions/cache@v4
36+
with:
37+
path: ${{ steps.pnpm-cache.outputs.STORE_PATH }}
38+
key: ${{ runner.os }}-pnpm-store-${{ hashFiles('**/pnpm-lock.yaml') }}
39+
restore-keys: |
40+
${{ runner.os }}-pnpm-store-
41+
42+
- name: Install dependencies
43+
run: pnpm install --frozen-lockfile
44+
45+
- name: Run TypeScript type checking
46+
run: pnpm astro check
47+
48+
- name: Build site
49+
run: pnpm build
50+
51+
- name: Upload build artifacts
52+
uses: actions/upload-artifact@v4
53+
if: success()
54+
with:
55+
name: build-output
56+
path: dist/
57+
retention-days: 7

‎.github/workflows/deploy.yml‎

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
name: Deploy to GitHub Pages
2+
3+
on:
4+
push:
5+
branches: [main]
6+
workflow_dispatch:
7+
8+
permissions:
9+
contents: read
10+
pages: write
11+
id-token: write
12+
13+
concurrency:
14+
group: "pages"
15+
cancel-in-progress: false
16+
17+
jobs:
18+
build:
19+
name: Build
20+
runs-on: ubuntu-latest
21+
steps:
22+
- name: Checkout code
23+
uses: actions/checkout@v5
24+
25+
- name: Setup Node.js
26+
uses: actions/setup-node@v6
27+
with:
28+
node-version: '24'
29+
30+
- name: Setup pnpm
31+
uses: pnpm/action-setup@v4
32+
with:
33+
version: 10
34+
35+
- name: Get pnpm store directory
36+
id: pnpm-cache
37+
shell: bash
38+
run: |
39+
echo "STORE_PATH=$(pnpm store path)" >> $GITHUB_OUTPUT
40+
41+
- name: Setup pnpm cache
42+
uses: actions/cache@v4
43+
with:
44+
path: ${{ steps.pnpm-cache.outputs.STORE_PATH }}
45+
key: ${{ runner.os }}-pnpm-store-${{ hashFiles('**/pnpm-lock.yaml') }}
46+
restore-keys: |
47+
${{ runner.os }}-pnpm-store-
48+
49+
- name: Install dependencies
50+
run: pnpm install --frozen-lockfile
51+
52+
- name: Build site
53+
run: pnpm build
54+
55+
- name: Setup Pages
56+
uses: actions/configure-pages@v5
57+
58+
- name: Upload artifact
59+
uses: actions/upload-pages-artifact@v4
60+
with:
61+
path: ./dist
62+
63+
deploy:
64+
name: Deploy
65+
needs: build
66+
runs-on: ubuntu-latest
67+
environment:
68+
name: github-pages
69+
url: ${{ steps.deployment.outputs.page_url }}
70+
steps:
71+
- name: Deploy to GitHub Pages
72+
id: deployment
73+
uses: actions/deploy-pages@v4

‎.gitignore‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
# build output
2+
dist/
3+
# generated types
4+
.astro/
5+
6+
# dependencies
7+
node_modules/
8+
9+
*.log
10+
*.zip
11+
.DS_Store

‎.vscode/extensions.json‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
{
2+
"recommendations": ["astro-build.astro-vscode"],
3+
"unwantedRecommendations": []
4+
}

‎.vscode/launch.json‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
{
2+
"version": "0.2.0",
3+
"configurations": [
4+
{
5+
"command": "./node_modules/.bin/astro dev",
6+
"name": "Development server",
7+
"request": "launch",
8+
"type": "node-terminal"
9+
}
10+
]
11+
}

‎CLAUDE.md‎

Lines changed: 226 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,226 @@
1+
# CLAUDE.md
2+
3+
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4+
5+
## Project Overview
6+
7+
This is Second Life's creation-focused documentation site, built with Astro + Starlight. The site is currently a basic template that will be built out starting with the LSL (Linden Scripting Language) portal. It covers both building and scripting aspects of Second Life content creation.
8+
9+
## Development Commands
10+
11+
All commands use pnpm:
12+
13+
- `pnpm install` - Install dependencies
14+
- `pnpm dev` - Start dev server at http://localhost:4321
15+
- `pnpm build` - Build production site to ./dist/
16+
- `pnpm preview` - Preview production build locally
17+
- `pnpm astro check` - Run TypeScript type checking
18+
- `pnpm generate:docs` - Generate all reference pages (functions, events, and constants) for both LSL and SLua from src/definitions/lsl_definitions.yaml
19+
20+
## Architecture
21+
22+
### Content Organization
23+
24+
Documentation lives in `src/content/docs/` with two main areas:
25+
26+
**build/** - Building and construction documentation
27+
- `build/guides/` - Build tutorials and guides
28+
- `build/reference/` - Build reference materials
29+
30+
**script/** - Scripting documentation (primary focus: LSL portal)
31+
- `script/guides/` - Scripting guides
32+
- `script/lsl-reference/` - LSL language reference
33+
- `script/slua-reference/` - SLua reference
34+
- `script/learn-slua/` - SLua learning materials
35+
36+
Files are `.md` or `.mdx` format. Routes auto-generate from file paths (e.g., `docs/script/lsl-reference/example.md` → `/script/lsl-reference/example/`).
37+
38+
### Internationalization
39+
40+
Configured in `astro.config.mjs` with additional locales:
41+
- `root` (English, default)
42+
- `de` (German), `es` (Spanish), `fr` (French), `it` (Italian)
43+
- `ja` (Japanese), `ko` (Korean), `nl` (Dutch), `pt` (Portuguese), `ru` (Russian)
44+
45+
To add translated content, create localized directories like `docs/de/`, `docs/ja/`, etc.
46+
47+
### Navigation
48+
49+
Sidebar configuration in `astro.config.mjs`:
50+
- Manual entries: Define with `label` and `slug`
51+
- Auto-generated: Use `autogenerate: { directory: 'reference' }` to include all files in a directory
52+
53+
### Configuration Files
54+
55+
- `astro.config.mjs` - Starlight integration, sidebar, locales
56+
- `src/content.config.ts` - Content collections using Starlight's schema
57+
- `tsconfig.json` - Extends Astro's strict TypeScript preset
58+
59+
## Documentation Tone and Style
60+
61+
**Approved Tone: Balanced & Pragmatic**
62+
63+
All documentation should use a balanced and pragmatic tone that:
64+
- Is professional but approachable
65+
- Maintains technical accuracy with clear explanations
66+
- Acknowledges both benefits and challenges
67+
- Respects the reader's existing knowledge (especially for LSL scripters and SL builders)
68+
- Works well for both learning new concepts and later reference use
69+
70+
**Writing Guidelines:**
71+
- Use "you" to address the reader directly
72+
- Be clear and precise without being overly formal
73+
- Explain the "why" behind concepts, not just the "what"
74+
- Anticipate common confusion points (especially for LSL-to-SLua migration)
75+
- Use code examples to illustrate concepts
76+
- Avoid excessive enthusiasm or marketing language
77+
- Don't oversimplify or condescend to the reader
78+
79+
**Example of preferred tone:**
80+
> "Tables are SLua's most powerful data structure. Unlike LSL's separate `list` type, tables serve two purposes: they work as both arrays (like LSL lists) and dictionaries/maps (which LSL doesn't have)."
81+
82+
## Adding Documentation
83+
84+
1. Create `.md` or `.mdx` file in appropriate `src/content/docs/` subdirectory
85+
2. Add frontmatter:
86+
```yaml
87+
---
88+
title: Page Title
89+
description: Brief description for SEO
90+
---
91+
```
92+
3. For `.mdx`, import Starlight components as needed:
93+
```mdx
94+
import { Card, CardGrid, Tabs, TabItem } from '@astrojs/starlight/components';
95+
```
96+
4. Update sidebar in `astro.config.mjs` if needed (or rely on autogenerate)
97+
98+
## Assets
99+
100+
- `src/assets/` - Images embedded in Markdown with relative links
101+
- `public/` - Static assets (favicons, etc.) served directly
102+
103+
## Source Material
104+
105+
The repository includes reference materials in the `context/` directory (gitignored):
106+
107+
**context/lsl_definitions.yaml** - Comprehensive language definitions for both LSL and SLua, including:
108+
- Constants with types, values, and tooltips
109+
- Functions with signatures, parameters, return types, and descriptions
110+
- Events and their parameters
111+
- Function IDs for LSO compilation
112+
- Structured in YAML format for programmatic processing
113+
114+
**context/wiki.secondlife.com/** - Exported MediaWiki markup from Second Life's current wiki:
115+
- `constants/` - Constant documentation pages
116+
- `functions/` - Function documentation pages
117+
- `flow-control/` - Control flow documentation
118+
- `lsl-portal/` - General LSL portal pages, tutorials, protocols, examples
119+
120+
**context/slua-guide/** - Suzanna's SLua Guide (https://suzanna-linn.github.io/slua/):
121+
- Comprehensive educational resource for the SLua language
122+
- Jekyll-based documentation with markdown files in `docs/` directory
123+
- Content includes:
124+
- Language fundamentals: `language1.md`, `language2.md`
125+
- Migration guides for LSL scripters: `moving-*.md` files covering datatypes, events, functions, operators, lists, strings, control flow, and libraries
126+
- Practical examples: `scripts-*.md` files with working examples (coroutines, enums, floating texts, sets, web integration)
127+
- Reference materials: `classes.md`, `transpiler.md`, `beta.md`, `future.md`, `history.md`
128+
- Licensed under Creative Commons Attribution 4.0 (text) and MIT License (code examples)
129+
- Use as reference for SLua language documentation and migration patterns
130+
131+
**IMPORTANT: For SLua documentation guidelines, see [SLUA_REFERENCE.md](SLUA_REFERENCE.md)**
132+
This file contains:
133+
- Language basics and syntax differences from LSL
134+
- Code style conventions and best practices
135+
- Documentation patterns (tabs, code blocks, callouts)
136+
- Type annotation guidelines (ALWAYS use types in examples)
137+
- Common patterns and idioms (events, timers, error handling)
138+
- Migration quick reference tables
139+
140+
**context/taxonomy.md** - Proposed site architecture and content taxonomy:
141+
- Scripting portal structure with sections for Getting Started, Features, Guides, and Recipes
142+
- Planned organization for SLua/LSL language documentation
143+
- Standard library/reference organization patterns
144+
- Site-wide SLua/LSL toggle considerations
145+
146+
These files are reference materials for building the new documentation. They should be transformed into clean, modern Markdown/MDX format in `src/content/docs/`.
147+
148+
## LSL Portal Development
149+
150+
The LSL portal is the initial focus area. Documentation should go in:
151+
- `src/content/docs/script/lsl-reference/` - Language reference, functions, events, constants
152+
- `src/content/docs/script/guides/` - Tutorials, examples, best practices
153+
154+
Consider organizing LSL content by:
155+
- Language syntax and structure
156+
- Built-in functions (organized by category)
157+
- Events
158+
- Constants and types
159+
- Examples and common patterns
160+
161+
When building documentation, use `context/lsl_definitions.yaml` as the authoritative source for technical accuracy, and reference `context/wiki.secondlife.com/` for existing documentation patterns and examples.
162+
163+
## SLua Documentation Guidelines
164+
165+
**When creating or editing SLua documentation, always refer to [SLUA_REFERENCE.md](SLUA_REFERENCE.md) for:**
166+
- Syntax conventions (use `luau` not `lua` for code blocks)
167+
- Type annotation requirements (ALWAYS include types in examples)
168+
- Documentation patterns (tabs, asides, code formatting)
169+
- Common patterns and idioms
170+
- LSL-to-SLua migration examples
171+
172+
## Reference Page Generation
173+
174+
The project includes an automated generator for creating LSL and SLua reference pages for functions, events, and constants:
175+
176+
**Generator Script:** `scripts/generate-docs.js`
177+
- Parses `src/definitions/lsl_definitions.yaml` to extract definitions
178+
- Supports both LSL and SLua/Luau generation
179+
- Creates MDX pages with appropriate components (LSLFunction/SLuaFunction, LSLEvent/SLuaEvent, LSLConstant/SLuaConstant)
180+
- Run with: `pnpm generate:docs`
181+
- Generates pages in:
182+
- LSL functions: `src/content/docs/script/lsl-reference/functions/`
183+
- SLua functions: `src/content/docs/script/slua-reference/functions/`
184+
- LSL events: `src/content/docs/script/lsl-reference/events/`
185+
- SLua events: `src/content/docs/script/slua-reference/events/`
186+
- LSL constants: `src/content/docs/script/lsl-reference/constants/`
187+
- SLua constants: `src/content/docs/script/slua-reference/constants/`
188+
189+
**Custom Content Preservation:**
190+
Generated pages support custom content that persists across regenerations. Any content after the component tag (e.g., `<LSLFunction />`, `<LSLEvent />`, `<LSLConstant />`) and before the optional attribution footer will be preserved when re-running the generator. This allows you to:
191+
- Add usage examples
192+
- Include additional notes and caveats
193+
- Link to related functions, events, or constants
194+
- Provide tutorials or best practices
195+
196+
**Generated Page Structure:**
197+
1. Frontmatter with title and description
198+
2. Component import statements
199+
3. Reference component tag (LSLFunction/SLuaFunction, LSLEvent/SLuaEvent, or LSLConstant/SLuaConstant)
200+
4. Custom content marker comment: `{/* DO NOT EDIT ABOVE THIS LINE */}`
201+
5. Custom content section for examples, notes, and related links
202+
6. Optional WikiAttribution footer (for LSL pages)
203+
204+
**Component Locations:**
205+
206+
Functions:
207+
- `src/components/FunctionReference.astro` - Base function reference component
208+
- `src/components/LSLFunction.astro` - LSL function wrapper
209+
- `src/components/SLuaFunction.astro` - SLua function wrapper
210+
211+
Events:
212+
- `src/components/EventReference.astro` - Base event reference component
213+
- `src/components/LSLEvent.astro` - LSL event wrapper
214+
- `src/components/SLuaEvent.astro` - SLua event wrapper
215+
216+
Constants:
217+
- `src/components/ConstantReference.astro` - Base constant reference component
218+
- `src/components/LSLConstant.astro` - LSL constant wrapper
219+
- `src/components/SLuaConstant.astro` - SLua constant wrapper
220+
221+
These components dynamically load data from `src/definitions/lsl_definitions.yaml` at build time, requiring only the name as a prop. All metadata (signatures, parameters, types, values, energy costs, sleep times, badges) is loaded from the YAML file.
222+
223+
When importing custom components in MDX use the `@component` alias, ex.:
224+
```mdx
225+
import SLuaConstant from '@components/SluaConstant.astro';
226+
```

0 commit comments

Comments
 (0)