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.
212 lines
6.8 KiB
Markdown
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.
|