uniweb 0.5.14 → 0.6.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +33 -391
- package/package.json +4 -4
- package/partials/agents-md.hbs +16 -15
- package/templates/multi/foundations/default/src/foundation.js.hbs +1 -1
- package/templates/multi/foundations/default/src/styles.css +1 -1
- package/templates/single/foundation/src/foundation.js.hbs +1 -1
- package/templates/single/foundation/src/styles.css +1 -1
- package/templates/multi/foundations/default/src/_entry.generated.js +0 -14
- package/templates/single/foundation/src/_entry.generated.js +0 -14
- /package/templates/multi/foundations/default/src/{components → sections}/Section/index.jsx +0 -0
- /package/templates/multi/foundations/default/src/{components → sections}/Section/meta.js +0 -0
- /package/templates/single/foundation/src/{components → sections}/Section/index.jsx +0 -0
- /package/templates/single/foundation/src/{components → sections}/Section/meta.js +0 -0
package/README.md
CHANGED
|
@@ -13,7 +13,7 @@ pnpm install
|
|
|
13
13
|
pnpm dev
|
|
14
14
|
```
|
|
15
15
|
|
|
16
|
-
Open http://localhost:5173 to see your site. Edit files in `site/pages/` and `foundation/src/
|
|
16
|
+
Open http://localhost:5173 to see your site. Edit files in `site/pages/` and `foundation/src/sections/` to see changes instantly.
|
|
17
17
|
|
|
18
18
|
> **Need pnpm?** Run `npm install -g pnpm` or see [pnpm installation](https://pnpm.io/installation).
|
|
19
19
|
|
|
@@ -27,7 +27,7 @@ pnpm build # Build foundation + site for production
|
|
|
27
27
|
pnpm preview # Preview the production build
|
|
28
28
|
```
|
|
29
29
|
|
|
30
|
-
The `build` command
|
|
30
|
+
The `build` command outputs to `site/dist/`. With pre-rendering enabled (the default for official templates), you get static HTML files ready to deploy anywhere.
|
|
31
31
|
|
|
32
32
|
The `marketing` template includes real components (Hero, Features, Pricing, Testimonials, FAQ, and more) with sample content—a working site you can explore and modify.
|
|
33
33
|
|
|
@@ -72,10 +72,13 @@ my-project/
|
|
|
72
72
|
│
|
|
73
73
|
└── foundation/ # Your components
|
|
74
74
|
├── src/
|
|
75
|
-
│
|
|
76
|
-
│
|
|
77
|
-
│
|
|
78
|
-
│
|
|
75
|
+
│ ├── sections/ # Section types (addressable from markdown)
|
|
76
|
+
│ │ ├── Hero.jsx # Bare file → section type (no meta.js needed)
|
|
77
|
+
│ │ └── Features/
|
|
78
|
+
│ │ ├── meta.js # Content interface (params, presets)
|
|
79
|
+
│ │ └── Features.jsx
|
|
80
|
+
│ └── components/ # Regular React components
|
|
81
|
+
│ └── Button.jsx
|
|
79
82
|
├── vite.config.js # 3-line config
|
|
80
83
|
└── dist/ # Built output
|
|
81
84
|
```
|
|
@@ -128,22 +131,19 @@ Natural content stays in markdown; structured data goes in tagged blocks (YAML o
|
|
|
128
131
|
### Components as React
|
|
129
132
|
|
|
130
133
|
```jsx
|
|
131
|
-
export function Hero({ content, params }) {
|
|
134
|
+
export default function Hero({ content, params }) {
|
|
132
135
|
const { title, paragraphs, links } = content
|
|
133
|
-
const { theme = 'light' } = params
|
|
134
136
|
|
|
135
137
|
return (
|
|
136
|
-
<section
|
|
137
|
-
className={`py-20 text-center ${theme === 'dark' ? 'bg-gray-900 text-white' : ''}`}
|
|
138
|
-
>
|
|
138
|
+
<section className="py-20 text-center">
|
|
139
139
|
<h1 className="text-4xl font-bold">{title}</h1>
|
|
140
140
|
<p className="text-xl text-gray-600">{paragraphs[0]}</p>
|
|
141
141
|
{links[0] && (
|
|
142
142
|
<a
|
|
143
|
-
href={links[0].
|
|
143
|
+
href={links[0].href}
|
|
144
144
|
className="mt-8 px-6 py-3 bg-blue-600 text-white rounded inline-block"
|
|
145
145
|
>
|
|
146
|
-
{links[0].
|
|
146
|
+
{links[0].label}
|
|
147
147
|
</a>
|
|
148
148
|
)}
|
|
149
149
|
</section>
|
|
@@ -151,7 +151,7 @@ export function Hero({ content, params }) {
|
|
|
151
151
|
}
|
|
152
152
|
```
|
|
153
153
|
|
|
154
|
-
Standard React. Standard Tailwind. The `{ content, params }` interface is only for
|
|
154
|
+
Standard React. Standard Tailwind. The `{ content, params }` interface is only for _section types_ — components that content creators select in markdown frontmatter. Everything else uses regular React props.
|
|
155
155
|
|
|
156
156
|
## Next Steps
|
|
157
157
|
|
|
@@ -163,7 +163,7 @@ After creating your project:
|
|
|
163
163
|
|
|
164
164
|
3. **Learn the configuration** — Run `uniweb docs site` or `uniweb docs page` for quick reference on configuration options.
|
|
165
165
|
|
|
166
|
-
4. **Create a
|
|
166
|
+
4. **Create a section type** — Add a file to `foundation/src/sections/` (e.g., `Banner.jsx`) and rebuild. Bare files at the root are discovered automatically — no `meta.js` needed. Add `meta.js` when you want to declare params or presets. See the [Component Metadata Guide](./docs/component-metadata.md) for the full schema.
|
|
167
167
|
|
|
168
168
|
The `meta.js` file defines what content and parameters a component accepts. The runtime uses this metadata to apply defaults and guarantee content structure—no defensive null checks needed in your component code.
|
|
169
169
|
|
|
@@ -187,10 +187,10 @@ Save and see the change instantly in your browser.
|
|
|
187
187
|
|
|
188
188
|
### Your First Component Change
|
|
189
189
|
|
|
190
|
-
Open `foundation/src/
|
|
190
|
+
Open `foundation/src/sections/Hero.jsx`. The component receives parsed content:
|
|
191
191
|
|
|
192
192
|
```jsx
|
|
193
|
-
export function Hero({ content
|
|
193
|
+
export default function Hero({ content }) {
|
|
194
194
|
const { title, paragraphs, links, imgs, items } = content
|
|
195
195
|
// Edit the JSX below...
|
|
196
196
|
}
|
|
@@ -198,25 +198,6 @@ export function Hero({ content, params }) {
|
|
|
198
198
|
|
|
199
199
|
The parser extracts semantic elements from markdown—`title` from the first heading, `paragraphs` from body text, `links` from `[text](url)`, and so on. The `items` array contains child groups created when headings appear after content (useful for features, pricing tiers, team members, etc.).
|
|
200
200
|
|
|
201
|
-
**Learn more:**
|
|
202
|
-
|
|
203
|
-
- [Site Configuration](./docs/site-configuration.md) — Complete site.yml reference
|
|
204
|
-
- [Page Configuration](./docs/page-configuration.md) — Complete page.yml reference
|
|
205
|
-
- [Content Structure](./docs/content-structure.md) — How content is parsed and structured
|
|
206
|
-
- [Navigation Patterns](./docs/navigation-patterns.md) — Building navbars, menus, and sidebars
|
|
207
|
-
- [Special Sections](./docs/special-sections.md) — @header, @footer, and sidebars
|
|
208
|
-
- [Linking](./docs/linking.md) — Stable page references that survive reorganization
|
|
209
|
-
- [Component Metadata](./docs/component-metadata.md) — Full meta.js schema reference
|
|
210
|
-
- [Foundation Configuration](./docs/foundation-configuration.md) — CSS variables and custom Layout
|
|
211
|
-
- [Site Theming](./docs/site-theming.md) — Colors, typography, and dark mode
|
|
212
|
-
- [Internationalization](./docs/internationalization.md) — Multi-language sites
|
|
213
|
-
- [Data Fetching](./docs/data-fetching.md) — Load external data from files or APIs
|
|
214
|
-
- [Dynamic Routes](./docs/dynamic-routes.md) — Generate pages from data (blogs, catalogs)
|
|
215
|
-
- [Content Collections](./docs/content-collections.md) — Manage articles, team members, and more
|
|
216
|
-
- [Versioning](./docs/versioning.md) — Multi-version documentation
|
|
217
|
-
- [Site Search](./docs/search.md) — Built-in full-text search
|
|
218
|
-
- [Runtime API](./docs/runtime-api.md) — Hooks and core objects
|
|
219
|
-
|
|
220
201
|
## Foundations Are Portable
|
|
221
202
|
|
|
222
203
|
The `foundation/` folder ships with your project as a convenience, but a foundation is a self-contained artifact with no dependency on any specific site. Sites reference foundations by configuration, not by folder proximity.
|
|
@@ -253,249 +234,26 @@ Start with local files deployed anywhere. The same foundation works across all t
|
|
|
253
234
|
|
|
254
235
|
---
|
|
255
236
|
|
|
256
|
-
##
|
|
257
|
-
|
|
258
|
-
```bash
|
|
259
|
-
# pnpm (recommended)
|
|
260
|
-
pnpm create uniweb my-site --template marketing
|
|
261
|
-
|
|
262
|
-
# npm (use -- before options)
|
|
263
|
-
npm create uniweb@latest my-site -- --template marketing
|
|
264
|
-
|
|
265
|
-
# npx
|
|
266
|
-
npx uniweb@latest create my-site --template marketing
|
|
267
|
-
```
|
|
268
|
-
|
|
269
|
-
Alternatively, install the CLI globally:
|
|
270
|
-
|
|
271
|
-
```bash
|
|
272
|
-
npm install -g uniweb
|
|
273
|
-
uniweb create my-site --template marketing
|
|
274
|
-
```
|
|
275
|
-
|
|
276
|
-
**Requirements:**
|
|
277
|
-
|
|
278
|
-
- Node.js 20.19 or later
|
|
279
|
-
- pnpm 10+ (recommended) or npm 10+
|
|
280
|
-
|
|
281
|
-
Projects use Vite 7 and Tailwind CSS v4 by default.
|
|
282
|
-
|
|
283
|
-
### Setting up pnpm
|
|
284
|
-
|
|
285
|
-
We recommend pnpm for dependency management (npm also works). Install pnpm via npm:
|
|
286
|
-
|
|
287
|
-
```bash
|
|
288
|
-
npm install -g pnpm
|
|
289
|
-
```
|
|
290
|
-
|
|
291
|
-
Or see the [official pnpm installation guide](https://pnpm.io/installation) for other options including Corepack, Homebrew, and more.
|
|
292
|
-
|
|
293
|
-
## Commands
|
|
294
|
-
|
|
295
|
-
### `create`
|
|
296
|
-
|
|
297
|
-
Create a new Uniweb project. See [Create a Project](#create-a-project) for usage examples.
|
|
298
|
-
|
|
299
|
-
```bash
|
|
300
|
-
uniweb create [project-name] [options]
|
|
301
|
-
```
|
|
302
|
-
|
|
303
|
-
**Options:**
|
|
304
|
-
|
|
305
|
-
| Option | Description |
|
|
306
|
-
| ------------------- | ---------------------------- |
|
|
307
|
-
| `--template <type>` | Project template (see below) |
|
|
308
|
-
|
|
309
|
-
**Template Sources:**
|
|
310
|
-
|
|
311
|
-
| Source | Example | Description |
|
|
312
|
-
| ---------- | ------------------------------ | ------------------------------- |
|
|
313
|
-
| Built-in | `single`, `multi` | Minimal starter templates |
|
|
314
|
-
| Official | `marketing` | Feature-rich showcase templates |
|
|
315
|
-
| npm | `@org/my-template` | Published npm packages |
|
|
316
|
-
| GitHub | `github:user/repo` | GitHub repositories |
|
|
317
|
-
| GitHub URL | `https://github.com/user/repo` | Full GitHub URLs |
|
|
318
|
-
|
|
319
|
-
### `build`
|
|
320
|
-
|
|
321
|
-
Build the current project.
|
|
322
|
-
|
|
323
|
-
```bash
|
|
324
|
-
uniweb build [options]
|
|
325
|
-
```
|
|
326
|
-
|
|
327
|
-
**Options:**
|
|
328
|
-
|
|
329
|
-
| Option | Description |
|
|
330
|
-
| ------------------- | --------------------------------------------------------------------- |
|
|
331
|
-
| `--target <type>` | Build target: `foundation` or `site` (auto-detected if not specified) |
|
|
332
|
-
| `--prerender` | Force pre-rendering (overrides site.yml) |
|
|
333
|
-
| `--no-prerender` | Skip pre-rendering (overrides site.yml) |
|
|
334
|
-
| `--foundation-dir` | Path to foundation directory (for prerendering) |
|
|
335
|
-
| `--platform <name>` | Deployment platform (e.g., `vercel`) for platform-specific output |
|
|
336
|
-
|
|
337
|
-
**Examples:**
|
|
338
|
-
|
|
339
|
-
```bash
|
|
340
|
-
# Auto-detect and build
|
|
341
|
-
uniweb build
|
|
342
|
-
|
|
343
|
-
# Explicitly build as foundation
|
|
344
|
-
uniweb build --target foundation
|
|
345
|
-
|
|
346
|
-
# Explicitly build as site
|
|
347
|
-
uniweb build --target site
|
|
348
|
-
|
|
349
|
-
# Build site with pre-rendering (SSG) - force on
|
|
350
|
-
uniweb build --prerender
|
|
351
|
-
|
|
352
|
-
# Skip pre-rendering even if enabled in site.yml
|
|
353
|
-
uniweb build --no-prerender
|
|
354
|
-
|
|
355
|
-
# Build for Vercel deployment
|
|
356
|
-
uniweb build --platform vercel
|
|
357
|
-
```
|
|
358
|
-
|
|
359
|
-
### Pre-rendering (SSG)
|
|
360
|
-
|
|
361
|
-
Pre-rendering generates static HTML for each page at build time. Enable it in `site.yml`:
|
|
362
|
-
|
|
363
|
-
```yaml
|
|
364
|
-
build:
|
|
365
|
-
prerender: true
|
|
366
|
-
```
|
|
367
|
-
|
|
368
|
-
Or use the `--prerender` flag. This gives you:
|
|
369
|
-
|
|
370
|
-
- **SEO**: Search engines see fully rendered content immediately
|
|
371
|
-
- **Performance**: First contentful paint is instant
|
|
372
|
-
- **Hosting**: Deploy to any static host (GitHub Pages, Netlify, S3, etc.)
|
|
373
|
-
|
|
374
|
-
The pre-rendered HTML includes embedded site content. When the page loads, React hydrates the existing DOM—no flash of loading state, then full client-side interactivity.
|
|
375
|
-
|
|
376
|
-
## Built-in Templates
|
|
377
|
-
|
|
378
|
-
### Single (Default)
|
|
379
|
-
|
|
380
|
-
A minimal workspace with a site and foundation as sibling packages. The recommended starting point.
|
|
381
|
-
|
|
382
|
-
```
|
|
383
|
-
my-project/
|
|
384
|
-
├── package.json # Workspace root
|
|
385
|
-
├── pnpm-workspace.yaml
|
|
386
|
-
├── site/
|
|
387
|
-
│ ├── package.json
|
|
388
|
-
│ ├── vite.config.js
|
|
389
|
-
│ ├── site.yml
|
|
390
|
-
│ ├── main.js
|
|
391
|
-
│ └── pages/
|
|
392
|
-
└── foundation/
|
|
393
|
-
├── package.json
|
|
394
|
-
├── vite.config.js
|
|
395
|
-
└── src/components/
|
|
396
|
-
```
|
|
397
|
-
|
|
398
|
-
### Multi
|
|
399
|
-
|
|
400
|
-
A monorepo for foundation development or multi-site projects.
|
|
401
|
-
|
|
402
|
-
```
|
|
403
|
-
my-workspace/
|
|
404
|
-
├── sites/
|
|
405
|
-
│ ├── marketing/ # Main site or test site
|
|
406
|
-
│ └── docs/ # Additional site
|
|
407
|
-
└── foundations/
|
|
408
|
-
├── marketing/ # Primary foundation
|
|
409
|
-
└── documentation/ # Additional foundation
|
|
410
|
-
```
|
|
411
|
-
|
|
412
|
-
Use this when you need multiple sites sharing foundations, multiple foundations for different purposes, or test sites for foundation development.
|
|
413
|
-
|
|
414
|
-
## Official Templates
|
|
415
|
-
|
|
416
|
-
Feature-rich templates with real components and sample content. **[View all demos](https://uniweb.github.io/templates/)**
|
|
417
|
-
|
|
418
|
-
### Marketing
|
|
419
|
-
|
|
420
|
-
[**Live Demo**](https://uniweb.github.io/templates/marketing/) · `pnpm create uniweb my-site --template marketing`
|
|
421
|
-
|
|
422
|
-
**Includes:** Hero, Features, Pricing, Testimonials, CTA, FAQ, Stats, LogoCloud, Video, Gallery, Team
|
|
423
|
-
|
|
424
|
-
Perfect for product launches, SaaS websites, and business landing pages.
|
|
425
|
-
|
|
426
|
-
**Tailwind v3 variant:** `--variant tailwind3`
|
|
427
|
-
|
|
428
|
-
### Academic
|
|
429
|
-
|
|
430
|
-
[**Live Demo**](https://uniweb.github.io/templates/academic/) · `pnpm create uniweb my-site --template academic`
|
|
431
|
-
|
|
432
|
-
**Includes:** ProfileHero, PublicationList, ResearchAreas, TeamGrid, Timeline, ContactCard, Navbar, Footer
|
|
433
|
-
|
|
434
|
-
Perfect for researcher portfolios, lab websites, and academic department sites.
|
|
435
|
-
|
|
436
|
-
### Docs
|
|
437
|
-
|
|
438
|
-
[**Live Demo**](https://uniweb.github.io/templates/docs/) · `pnpm create uniweb my-site --template docs`
|
|
439
|
-
|
|
440
|
-
**Includes:** Header, LeftPanel, DocSection, CodeBlock, Footer
|
|
237
|
+
## Guides and Documentation
|
|
441
238
|
|
|
442
|
-
|
|
239
|
+
[Developer Guides](./guides/developers/) — Building foundations and components, converting designs, component patterns, theming contexts
|
|
443
240
|
|
|
444
|
-
|
|
241
|
+
[Content Author Guides](./guides/authors/) — Writing pages in markdown, writing dynamic content, site setup, theming, recipes
|
|
445
242
|
|
|
446
|
-
[
|
|
243
|
+
[Reference Docs](./docs/) — Full reference for all configuration, commands, and framework
|
|
447
244
|
|
|
448
|
-
|
|
245
|
+
### Quick Reference
|
|
449
246
|
|
|
450
|
-
|
|
247
|
+
| Topic | Guide |
|
|
248
|
+
| ------------------ | ------------------------------------------------------------------- |
|
|
249
|
+
| Content Structure | [How markdown becomes component props](./docs/content-structure.md) |
|
|
250
|
+
| Component Metadata | [The meta.js schema](./docs/component-metadata.md) |
|
|
251
|
+
| Site Configuration | [site.yml reference](./docs/site-configuration.md) |
|
|
252
|
+
| CLI Commands | [create, build, docs, i18n](./docs/cli-commands.md) |
|
|
253
|
+
| Templates | [Built-in, official, and external templates](./docs/templates.md) |
|
|
254
|
+
| Deployment | [Vercel, Netlify, Cloudflare, and more](./docs/deployment.md) |
|
|
451
255
|
|
|
452
|
-
|
|
453
|
-
|
|
454
|
-
```bash
|
|
455
|
-
uniweb i18n extract # Extract translatable strings
|
|
456
|
-
uniweb i18n status # Check translation coverage
|
|
457
|
-
uniweb build # Generates dist/es/, dist/fr/
|
|
458
|
-
```
|
|
459
|
-
|
|
460
|
-
Perfect for international businesses and learning the i18n workflow.
|
|
461
|
-
|
|
462
|
-
## External Templates
|
|
463
|
-
|
|
464
|
-
Use templates from npm or GitHub:
|
|
465
|
-
|
|
466
|
-
```bash
|
|
467
|
-
# npm package
|
|
468
|
-
pnpm create uniweb my-site --template @myorg/template-name
|
|
469
|
-
|
|
470
|
-
# GitHub repository
|
|
471
|
-
pnpm create uniweb my-site --template github:user/repo
|
|
472
|
-
|
|
473
|
-
# GitHub with specific branch/tag
|
|
474
|
-
pnpm create uniweb my-site --template github:user/repo#v1.0.0
|
|
475
|
-
```
|
|
476
|
-
|
|
477
|
-
## Dependency Management
|
|
478
|
-
|
|
479
|
-
Each package manages its own dependencies:
|
|
480
|
-
|
|
481
|
-
**`site/package.json`:**
|
|
482
|
-
|
|
483
|
-
- `@uniweb/runtime`
|
|
484
|
-
- `@my-project/foundation` (workspace link)
|
|
485
|
-
- Vite, Tailwind (dev)
|
|
486
|
-
|
|
487
|
-
**`foundation/package.json`:**
|
|
488
|
-
|
|
489
|
-
- Component libraries (carousel, icons, etc.)
|
|
490
|
-
- React as peer dependency
|
|
491
|
-
|
|
492
|
-
```bash
|
|
493
|
-
# Add component dependency
|
|
494
|
-
cd foundation && pnpm add embla-carousel
|
|
495
|
-
|
|
496
|
-
# Site references foundation via workspace
|
|
497
|
-
# No path gymnastics needed
|
|
498
|
-
```
|
|
256
|
+
---
|
|
499
257
|
|
|
500
258
|
## Configuration
|
|
501
259
|
|
|
@@ -542,30 +300,7 @@ export default defineFoundationConfig({
|
|
|
542
300
|
})
|
|
543
301
|
```
|
|
544
302
|
|
|
545
|
-
|
|
546
|
-
|
|
547
|
-
When you run `uniweb build` on a foundation:
|
|
548
|
-
|
|
549
|
-
1. **Discovers** components from `src/components/*/meta.js`
|
|
550
|
-
2. **Generates** entry point (`_entry.generated.js`)
|
|
551
|
-
3. **Runs** Vite build
|
|
552
|
-
4. **Processes** preview images (converts to WebP)
|
|
553
|
-
5. **Generates** `schema.json` with full metadata
|
|
554
|
-
|
|
555
|
-
**Output:**
|
|
556
|
-
|
|
557
|
-
```
|
|
558
|
-
dist/
|
|
559
|
-
├── foundation.js # Bundled components
|
|
560
|
-
├── foundation.js.map # Source map
|
|
561
|
-
├── schema.json # Component metadata
|
|
562
|
-
└── assets/
|
|
563
|
-
├── style.css # Compiled CSS
|
|
564
|
-
└── [Component]/ # Preview images
|
|
565
|
-
└── [preset].webp
|
|
566
|
-
```
|
|
567
|
-
|
|
568
|
-
## Workspace Configuration
|
|
303
|
+
### Workspace Configuration
|
|
569
304
|
|
|
570
305
|
Both templates use the same unified workspace configuration:
|
|
571
306
|
|
|
@@ -588,25 +323,6 @@ Also set in `package.json` for npm compatibility.
|
|
|
588
323
|
|
|
589
324
|
This means no config changes when evolving from single to multi-site.
|
|
590
325
|
|
|
591
|
-
## Releasing a Foundation
|
|
592
|
-
|
|
593
|
-
Publish your foundation to npm:
|
|
594
|
-
|
|
595
|
-
```bash
|
|
596
|
-
cd foundation
|
|
597
|
-
npm publish
|
|
598
|
-
```
|
|
599
|
-
|
|
600
|
-
Or to [uniweb.app](https://uniweb.app) for use with platform-managed sites:
|
|
601
|
-
|
|
602
|
-
```bash
|
|
603
|
-
uniweb login # First time only
|
|
604
|
-
uniweb build
|
|
605
|
-
uniweb publish
|
|
606
|
-
```
|
|
607
|
-
|
|
608
|
-
Sites control their own update strategy—automatic, minor-only, patch-only, or pinned to a specific version.
|
|
609
|
-
|
|
610
326
|
## FAQ
|
|
611
327
|
|
|
612
328
|
**How is this different from MDX?**
|
|
@@ -623,7 +339,7 @@ No. Local markdown files work great for developer-managed sites. The platform ad
|
|
|
623
339
|
|
|
624
340
|
**Can I use an existing component library?**
|
|
625
341
|
|
|
626
|
-
Yes. Foundations are standard React. Import any library into your foundation components. The `{ content, params }` interface only applies to
|
|
342
|
+
Yes. Foundations are standard React. Import any library into your foundation components. The `{ content, params }` interface only applies to section types (components with `meta.js`) — everything else uses regular React props.
|
|
627
343
|
|
|
628
344
|
**Is this SEO-friendly?**
|
|
629
345
|
|
|
@@ -633,80 +349,6 @@ Yes. Content is pre-embedded in the initial HTML—no fetch waterfalls, no layou
|
|
|
633
349
|
|
|
634
350
|
Pages can define data sources that auto-generate subroutes. A `/blog` page can have an index and a `[slug]` template that renders each post.
|
|
635
351
|
|
|
636
|
-
## Common Gotchas
|
|
637
|
-
|
|
638
|
-
### Homepage Configuration
|
|
639
|
-
|
|
640
|
-
Set your homepage with `index:` in `site.yml`:
|
|
641
|
-
|
|
642
|
-
```yaml
|
|
643
|
-
# site.yml
|
|
644
|
-
index: home # The page folder that becomes /
|
|
645
|
-
```
|
|
646
|
-
|
|
647
|
-
The `index:` option tells the build which page folder becomes the root route (`/`). The page still exists in `pages/home/`, but visitors access it at `/`.
|
|
648
|
-
|
|
649
|
-
Don't confuse this with `pages:` (which explicitly lists pages and hides any not listed).
|
|
650
|
-
|
|
651
|
-
### Content Shapes
|
|
652
|
-
|
|
653
|
-
Lists and items in markdown become **objects**, not strings. A bullet list:
|
|
654
|
-
|
|
655
|
-
```markdown
|
|
656
|
-
- First item
|
|
657
|
-
- Second item
|
|
658
|
-
```
|
|
659
|
-
|
|
660
|
-
Becomes:
|
|
661
|
-
|
|
662
|
-
```js
|
|
663
|
-
content.items = [
|
|
664
|
-
{ title: 'First item', paragraphs: [], links: [], imgs: [] },
|
|
665
|
-
{ title: 'Second item', paragraphs: [], links: [], imgs: [] },
|
|
666
|
-
]
|
|
667
|
-
```
|
|
668
|
-
|
|
669
|
-
Each item has the same structure as a content block. See [Content Structure](./docs/content-structure.md) for the full shape.
|
|
670
|
-
|
|
671
|
-
### Tagged Data Blocks
|
|
672
|
-
|
|
673
|
-
Tagged code blocks like:
|
|
674
|
-
|
|
675
|
-
````markdown
|
|
676
|
-
```yaml:team-member
|
|
677
|
-
name: Sarah Chen
|
|
678
|
-
role: Lead Architect
|
|
679
|
-
```
|
|
680
|
-
````
|
|
681
|
-
|
|
682
|
-
Are accessible via `content.data`:
|
|
683
|
-
|
|
684
|
-
```jsx
|
|
685
|
-
function TeamMember({ content }) {
|
|
686
|
-
const member = content.data['team-member']
|
|
687
|
-
return (
|
|
688
|
-
<div>
|
|
689
|
-
{member.name} - {member.role}
|
|
690
|
-
</div>
|
|
691
|
-
)
|
|
692
|
-
}
|
|
693
|
-
```
|
|
694
|
-
|
|
695
|
-
The tag name (after the colon) becomes the key in `content.data`.
|
|
696
|
-
|
|
697
|
-
### Root vs Package Commands
|
|
698
|
-
|
|
699
|
-
In a Uniweb workspace, commands run differently at different levels:
|
|
700
|
-
|
|
701
|
-
| Location | Command | What it does |
|
|
702
|
-
| ------------- | -------------- | --------------------------------------- |
|
|
703
|
-
| Project root | `pnpm build` | Builds all packages (foundation + site) |
|
|
704
|
-
| Project root | `pnpm dev` | Starts dev server for site |
|
|
705
|
-
| `foundation/` | `uniweb build` | Builds just the foundation |
|
|
706
|
-
| `site/` | `uniweb build` | Builds just the site |
|
|
707
|
-
|
|
708
|
-
For day-to-day development, run `pnpm dev` from the project root. The workspace scripts handle the rest.
|
|
709
|
-
|
|
710
352
|
## Related Packages
|
|
711
353
|
|
|
712
354
|
- [`@uniweb/build`](https://github.com/uniweb/build) — Foundation build tooling
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "uniweb",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.6.0",
|
|
4
4
|
"description": "Create structured Vite + React sites with content/code separation",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"bin": {
|
|
@@ -40,9 +40,9 @@
|
|
|
40
40
|
"js-yaml": "^4.1.0",
|
|
41
41
|
"prompts": "^2.4.2",
|
|
42
42
|
"tar": "^7.0.0",
|
|
43
|
-
"@uniweb/build": "0.
|
|
44
|
-
"@uniweb/runtime": "0.5.11",
|
|
43
|
+
"@uniweb/build": "0.5.0",
|
|
45
44
|
"@uniweb/core": "0.3.10",
|
|
46
|
-
"@uniweb/kit": "0.4.11"
|
|
45
|
+
"@uniweb/kit": "0.4.11",
|
|
46
|
+
"@uniweb/runtime": "0.5.11"
|
|
47
47
|
}
|
|
48
48
|
}
|
package/partials/agents-md.hbs
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# AGENTS.md
|
|
2
2
|
|
|
3
|
-
Guidance for AI agents working with this Uniweb project.
|
|
3
|
+
Guidance for AI agents working with this Uniweb project.
|
|
4
4
|
|
|
5
5
|
## Project Structure
|
|
6
6
|
|
|
@@ -13,8 +13,8 @@ project/
|
|
|
13
13
|
|
|
14
14
|
Multi-site variant uses `foundations/` and `sites/` (plural) folders.
|
|
15
15
|
|
|
16
|
-
- **Foundation**: React components. Those with `meta.js` are *
|
|
17
|
-
- **Site**: Markdown content + configuration. Each section file references
|
|
16
|
+
- **Foundation**: React components. Those with `meta.js` are *section types* — selectable by content authors via `type:` in frontmatter. Everything else is ordinary React.
|
|
17
|
+
- **Site**: Markdown content + configuration. Each section file references a section type.
|
|
18
18
|
|
|
19
19
|
## Commands
|
|
20
20
|
|
|
@@ -212,7 +212,7 @@ theme: dark ← sets context-dark, all tokens resolve to dark values
|
|
|
212
212
|
|
|
213
213
|
**Site controls the palette** in `theme.yml`. The same foundation looks different across sites because tokens resolve from the site's color configuration, not from component code.
|
|
214
214
|
|
|
215
|
-
**When to break the rules:** Header/footer components that float over content may need direct color logic (reading the first section's theme). Decorative elements with fixed branding (logos) use literal colors.
|
|
215
|
+
**When to break the rules:** Header/footer components that float over content may need direct color logic (reading the first section's theme). Decorative elements with fixed branding (logos) use literal colors.
|
|
216
216
|
|
|
217
217
|
## Component Development
|
|
218
218
|
|
|
@@ -277,24 +277,25 @@ All defaults belong in `meta.js`, not inline in component code.
|
|
|
277
277
|
|
|
278
278
|
**Utilities:** `cn()` (Tailwind class merge), `filterSocialLinks(links)`, `getSocialPlatform(url)`
|
|
279
279
|
|
|
280
|
-
###
|
|
280
|
+
### Foundation Organization
|
|
281
281
|
|
|
282
282
|
```
|
|
283
283
|
foundation/src/
|
|
284
|
-
├──
|
|
284
|
+
├── sections/ # Section types (auto-discovered via meta.js)
|
|
285
285
|
│ ├── Hero/
|
|
286
|
-
│ │ ├── index.jsx
|
|
286
|
+
│ │ ├── Hero.jsx # Entry — or index.jsx, both work
|
|
287
287
|
│ │ └── meta.js
|
|
288
288
|
│ └── Features/
|
|
289
|
-
│ ├──
|
|
289
|
+
│ ├── Features.jsx
|
|
290
290
|
│ └── meta.js
|
|
291
|
-
├──
|
|
292
|
-
│ ├──
|
|
291
|
+
├── components/ # Your React components (no meta.js, not selectable)
|
|
292
|
+
│ ├── ui/ # shadcn-compatible primitives
|
|
293
|
+
│ │ └── button.jsx
|
|
293
294
|
│ └── Card.jsx
|
|
294
295
|
└── styles.css
|
|
295
296
|
```
|
|
296
297
|
|
|
297
|
-
|
|
298
|
+
Only folders with `meta.js` in `sections/` (or `components/` for older foundations) become section types. Everything else is ordinary React — organize however you like.
|
|
298
299
|
|
|
299
300
|
### Website and Page APIs
|
|
300
301
|
|
|
@@ -325,7 +326,7 @@ const firstBody = block.page.getFirstBodyBlockInfo()
|
|
|
325
326
|
|
|
326
327
|
### Custom Layouts
|
|
327
328
|
|
|
328
|
-
Export a Layout from `foundation/src/
|
|
329
|
+
Export a Layout from `foundation/src/foundation.js`. Kit provides `SidebarLayout` for sidebar-based sites (docs, dashboards):
|
|
329
330
|
|
|
330
331
|
```jsx
|
|
331
332
|
import { SidebarLayout } from '@uniweb/kit/styled'
|
|
@@ -341,9 +342,9 @@ When given a monolithic React file (AI-generated or hand-built), don't port line
|
|
|
341
342
|
1. **Name by purpose** — `Institutions` → `Testimonial`, `WorkModes` → `FeatureColumns`. Components render a *kind* of content, not specific content.
|
|
342
343
|
2. **Separate content from code** — Hardcoded strings → markdown. Layout/styling stays in JSX. Content authors edit words without touching code.
|
|
343
344
|
3. **Use semantic tokens** — Replace `text-slate-900` with `text-heading`, `bg-white` with `bg-surface`. Component works in any context and any brand.
|
|
344
|
-
4. **
|
|
345
|
+
4. **UI components → `components/`** — Buttons, badges, cards go in `src/components/` (no `meta.js` needed).
|
|
345
346
|
|
|
346
|
-
You don't have to convert everything at once. Each section is independent — one can use hardcoded content while another reads from markdown.
|
|
347
|
+
You don't have to convert everything at once. Each section is independent — one can use hardcoded content while another reads from markdown.
|
|
347
348
|
|
|
348
349
|
## Tailwind CSS v4
|
|
349
350
|
|
|
@@ -351,7 +352,7 @@ Theme defined in `foundation/src/styles.css`:
|
|
|
351
352
|
|
|
352
353
|
```css
|
|
353
354
|
@import "tailwindcss";
|
|
354
|
-
@source "./
|
|
355
|
+
@source "./sections/**/*.{js,jsx}";
|
|
355
356
|
@source "../node_modules/@uniweb/kit/src/**/*.jsx";
|
|
356
357
|
|
|
357
358
|
@theme {
|
|
@@ -1,14 +0,0 @@
|
|
|
1
|
-
// Auto-generated foundation entry point
|
|
2
|
-
// DO NOT EDIT - This file is regenerated during build
|
|
3
|
-
|
|
4
|
-
import './styles.css'
|
|
5
|
-
import Section from './components/Section/index.jsx'
|
|
6
|
-
|
|
7
|
-
export const components = { Section }
|
|
8
|
-
|
|
9
|
-
export { Section }
|
|
10
|
-
|
|
11
|
-
export const capabilities = null
|
|
12
|
-
|
|
13
|
-
// Per-component runtime metadata (from meta.js)
|
|
14
|
-
export const meta = {}
|
|
@@ -1,14 +0,0 @@
|
|
|
1
|
-
// Auto-generated foundation entry point
|
|
2
|
-
// DO NOT EDIT - This file is regenerated during build
|
|
3
|
-
|
|
4
|
-
import './styles.css'
|
|
5
|
-
import Section from './components/Section/index.jsx'
|
|
6
|
-
|
|
7
|
-
export const components = { Section }
|
|
8
|
-
|
|
9
|
-
export { Section }
|
|
10
|
-
|
|
11
|
-
export const capabilities = null
|
|
12
|
-
|
|
13
|
-
// Per-component runtime metadata (from meta.js)
|
|
14
|
-
export const meta = {}
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|