AetheriaLore/README.md
Meta Vens 5f459932de Prefer real note slugs; update docs and PS1
Return a real note's slug when present (instead of a synthetic folder `index` slug) in FileTrie.slug and add a unit test to assert that behavior. Expand README with a repository map, local development quick start, build/test instructions, where-to-edit guidance, and troubleshooting notes. Update the Windows helper script (scripts/quartz/quartz.ps1) to prefer the bundled portable Node/npm runtime when available and pin npm's cache to .npm-cache inside the repo for reproducible local runs.
2026-04-20 00:24:22 +01:00

212 lines
6.8 KiB
Markdown

# AetheriaLore
AetheriaLore is an Obsidian vault for the Aetheria setting and the source for the live Quartz-powered site at `https://aetheria.gamecult.org`.
The setting is a politically charged science-fantasy / science-fiction world shaped by corporate power, technological escalation, ideological struggle, and the long consequences of social collapse. The repository is both:
- a readable worldbuilding vault under `Aetheria/`
- a customized static site implementation under `quartz-site/`
## Repository Map
The most important top-level paths are:
- `Aetheria/`: the actual vault content
- `quartz-site/`: the vendored Quartz site source and custom UI code
- `scripts/quartz/quartz.ps1`: beginner-friendly helper for local builds and the dev server
- `.github/workflows/deploy-quartz.yml`: GitHub Pages deployment workflow
- `AGENTS.md`: project writing and editing conventions
Within the vault, most published setting material lives under `Aetheria/Worldbuilding/`:
- `Pre-Elysium`: solar-system-era history, factions, technologies, movements, and timeline notes
- `Post-Elysium`: transformed-era concepts, species, and technologies
- `Politics`: strategic, legal, and institutional notes about power and warfare
If you want to read the setting in sequence, start with:
1. `Aetheria/Introduction.md`
2. `Aetheria/Narrative Themes.md`
3. `Aetheria/Worldbuilding/Pre-Elysium/Timeline.md`
## Local Development Quick Start
### The easiest path on Windows
From the repository root, run:
```powershell
.\scripts\quartz\quartz.ps1 dev
```
That command:
- starts the local Quartz development server
- watches the vault for changes
- rebuilds automatically as you edit notes or site files
- uses the bundled portable Node.js runtime in `.tools/` if it exists
Quartz will print the local address when it starts. In this repo it is usually `http://localhost:8080`.
When you are done, stop it with `Ctrl+C`.
### Build a static output locally
To do a one-off production-style build:
```powershell
.\scripts\quartz\quartz.ps1 build
```
The generated site goes to:
```text
quartz-site/public
```
That folder is build output, not source of truth.
### Important beginner note
Do **not** test the site by double-clicking `quartz-site/public/index.html` and opening it as a `file://` page. Quartz features such as search, explorer behavior, and some client-side routing expect a real HTTP server. Use the dev host instead.
## Direct npm Workflow
If you prefer to work directly inside `quartz-site/` instead of using the helper script:
```powershell
cd quartz-site
npm ci
npm run dev
```
For a one-off build:
```powershell
cd quartz-site
npm run build
```
This is the more portable path on non-Windows systems. The PowerShell helper is mainly there to make local development smoother on Windows and to hide the bundled-runtime setup.
## Testing And Verification
The fastest useful smoke test is a full site build:
```powershell
.\scripts\quartz\quartz.ps1 build
```
If you are changing Quartz TypeScript logic, you can also run the vendored Quartz test suite from `quartz-site/`:
```powershell
cd quartz-site
npm test
```
Useful additional checks:
```powershell
cd quartz-site
npm run check
```
## Where To Edit Things
### Setting content
- `Aetheria/**/*.md`
This is where the worldbuilding actually lives. If you are changing lore, faction descriptions, timelines, concepts, or overview notes, you are probably editing here.
### Site-wide Quartz settings
- `quartz-site/quartz.config.ts`
Use this for:
- site title
- base URL
- ignored vault paths
- theme colors and fonts
- Quartz plugins and emitters
### Page layout and which UI pieces appear where
- `quartz-site/quartz.layout.ts`
Use this when you need to change the overall shell for note pages: header, breadcrumbs, sidebars, footer, and which components are rendered before or after the note body.
### Main site-specific styling
- `quartz-site/quartz/styles/custom.scss`
This is the primary place to adjust Aetheria-specific look and feel:
- dark-only theme behavior
- layout spacing and panel treatment
- title bar styling
- sidebar styling
- breadcrumb appearance
- note chrome and atmosphere
Quartz base styles also live nearby in `quartz-site/quartz/styles/`, but `custom.scss` is the intended first stop for project-specific visual changes.
### Aetheria-specific custom components
These are the most important custom UI files:
- `quartz-site/quartz/components/AetheriaMasthead.tsx`: the top title bar and major section navigation
- `quartz-site/quartz/components/AetheriaOverviewSidebar.tsx`: the left navigation sidebar
- `quartz-site/quartz/components/AetheriaThemeLock.tsx`: dark-mode lock
- `quartz-site/quartz/components/aetheria.ts`: note/tagline/overview parsing logic used by the custom shell
### Custom behavior worth knowing about
- `quartz-site/quartz/components/Breadcrumbs.tsx`: breadcrumb rendering
- `quartz-site/quartz/util/fileTrie.ts`: path and ancestry logic used by breadcrumbs and folder-like navigation
- `quartz-site/quartz/components/Head.tsx`: page titles and metadata behavior
- `quartz-site/quartz/components/renderPage.tsx`: page assembly
### Deployment
- `.github/workflows/deploy-quartz.yml`
Pushes to `main` trigger the GitHub Actions build and deploy the static site to GitHub Pages.
## Working With The Vault
If you open the repository in Obsidian, internal wiki links such as `[[Megas]]`, `[[Aether]]`, or `[[Pan-Solar Consortium]]` give the best reading and editing experience.
Published overview/navigation notes are usually `index.md` files inside their branch folders. In this repo they are not throwaway placeholders: they drive navigation, taglines, and sidebar behavior in the generated site.
Some vault paths are intentionally excluded from the published site, including:
- `Brainstorming/`
- `Inspiration/`
They can still exist in the vault for internal work.
## Contributor Notes
Start with `AGENTS.md` before making broad writing changes. It documents the tone, structural conventions, navigation expectations, and thematic lenses used across the setting.
If you need semantic vault navigation support while editing locally, the repo also includes a local RAG helper under `scripts/rag/`.
## Troubleshooting
### `npm` was not found
The helper script will use the bundled Windows runtime in `.tools/node-v24.15.0-win-x64` if present. If that folder is missing, install Node.js and npm locally.
### Build warnings about inaccurate dates
Quartz can warn that dates are inaccurate for notes that are not yet tracked by Git. That usually means you need to commit the new file before Git-backed modified dates become meaningful.
### The dev site looks broken but the build succeeded
Make sure you opened the served URL from `npm run dev` or `.\scripts\quartz\quartz.ps1 dev`, not a raw file from `quartz-site/public`.
## License
See `LICENSE` for repository licensing details.