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:

.\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:

.\scripts\quartz\quartz.ps1 build

The generated site goes to:

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:

cd quartz-site
npm ci
npm run dev

For a one-off build:

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:

.\scripts\quartz\quartz.ps1 build

If you are changing Quartz TypeScript logic, you can also run the vendored Quartz test suite from quartz-site/:

cd quartz-site
npm test

Useful additional checks:

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.