Where knowledge becomes pages.
This repository is the Ekily Press runtime, editor, built-in theme fallback, theme management infrastructure, official documentation site, and Markdown rendering regression corpus.
Press is the main development repository for the Ekily Press runtime, editor, native fallback theme, Theme Manager, official documentation, and realistic Markdown content used to exercise the renderer.
Official non-native themes are developed as one repository per theme. A Press site still loads themes only from local assets/themes/<slug> folders; Theme Manager installs, updates, and uninstalls those folders by staging GitHub commit changes through the editor Publish flow.
The wwwroot/ folder is intentionally not minimal. It hosts the official Press documentation, release/history pages, SEO examples, media-heavy examples, and edge-case posts that help catch regressions in Markdown parsing, front matter handling, media resolution, search, tags, SEO metadata, and theme rendering.
The clean starter template lives in EkilyHQ/YAP. YAP owns starter content and site defaults, while this repository publishes runtime system packages that YAP syncs.
Use that starter repository when you want to create your own site. This repository is useful when you want to develop Press itself, inspect the official documentation source, or test behavior against the full documentation corpus.
The theme starter template lives in EkilyHQ/Press-Theme-Starter. Use it when you want to create a new Press theme repository with the release workflow and contract-compatible starter theme already wired up.
The official documentation site remains the full setup guide:
- Official site: https://ekilyhq.github.io/Press/
- Documentation: Documentation for Press
- Theme contract: Press Theme Contract
- GitHub Pages guide: Configure GitHub Pages for Press
index.html- public site entrypoint.index_editor.html- browser editor entrypoint.assets/- runtime JavaScript, i18n, schemas, the built-innativetheme, installed theme registry, and static assets.assets/themes/packs.json- site-specific installed theme registry used by Site Settings and Theme Manager.- Official theme catalog - external list loaded by Theme Manager from
EkilyHQ/Press-Theme-Catalog. wwwroot/- official documentation site content and Markdown regression corpus.site.yaml- official documentation site configuration.scripts/- repository checks and focused regression scripts.templates/- repository template input for YAP.
Press is a zero-build static site. For local development:
python3 -m http.server 8000Then open http://localhost:8000/.
For local-only content experiments, copy site.local.example.yaml to site.local.yaml and point it at wwwroot.local/. Both files are ignored by git, and the main guard prevents them from entering main.
When testing the editor Publish flow, deleting managed posts or pages now stages real repository deletions for the corresponding Markdown files. Same-document local assets/... media is only deleted when the editor can prove it is not still referenced.
For GitHub App-backed publishing, install the Ekily Connect GitHub App on the site repository and open the editor's Repository settings. Connect publishing is configured per browser: the editor stores the selected Connect URL locally and defaults to the official Ekily Connect deployment. Switch the Repository settings publish method to Personal token when you need the fine-grained Personal Access Token fallback.
Run the focused checks before merging:
bash scripts/test-main-guard.sh
bash scripts/test-frontmatter-roundtrip.sh
bash scripts/test-system-release-package.sh
bash scripts/test-system-release-workflow.sh
bash scripts/test-product-state-workflow.sh
node scripts/test-editor-app-kernel.mjs
node scripts/test-release-intent.js
node scripts/test-product-state-ledger.js
node scripts/test-product-state-dashboard.js
node --experimental-default-type=module scripts/test-encrypted-content.js
node --experimental-default-type=module scripts/test-system-updates.js
node --experimental-default-type=module scripts/test-theme-manager.js
node --experimental-default-type=module scripts/test-theme-contracts.js
node scripts/test-content-model.jsMerges to main that change Press runtime files publish the explicit SemVer recorded in assets/press-system.json with a dedicated press-system-vX.Y.Z.zip update package. Runtime changes must bump that source version before release. The package is intentionally limited to the application shell and runtime assets: index.html, index_editor.html, assets/press-system.json, assets/main.js, assets/js/, assets/i18n/, assets/schema/, and assets/themes/native/**. The encrypted-article envelope helper in assets/js/encrypted-content.js is part of that runtime boundary.
Press source files stay in development form and must not contain materialized press-system-vX.Y.Z cache keys. scripts/package-system-release.sh runs node scripts/sync-runtime-cache-keys.mjs --materialize-root ... so the release archive receives query keys, and scripts/build-pages-artifact.sh applies the same materializer to the Pages deployment artifact. The materializer writes assets/press-runtime-manifest.json with the runtime file inventory plus a materialized asset graph. CI runs node scripts/sync-runtime-cache-keys.mjs --check against source, bash scripts/test-system-release-package.sh against the generated package, and bash scripts/test-pages-artifact.sh to verify the Pages artifact and system ZIP carry the same materialized runtime graph while preserving their separate site-vs-system boundaries.
System release manifests include upgradeFrom compatibility metadata. The editor blocks update staging when the current installed Press version does not satisfy that source range, so future releases can require intermediate updates before older compatibility code is removed.
Official documentation, site content, installed theme registry state, and external theme directories stay out of system update packages. Changes that only touch wwwroot/ do not create a system release, and update packages must never include wwwroot/, site.yaml, CNAME, robots.txt, sitemap.xml, repository policy files, workflow files, scripts, site-specific media such as assets/avatar.png and assets/hero.jpeg, assets/themes/packs.json, or arbitrary assets/themes/<slug> directories outside native.
After a system release is published, the release workflow runs scripts/dispatch-system-release.js to notify downstream repositories declared in scripts/release-targets.js. Configure the Ekily Release GitHub App for the EkilyHQ organization, install it on YAP, Press-Theme-Starter, and the official theme repositories, then set EKILY_RELEASE_APP_ID as a repository variable and EKILY_RELEASE_PRIVATE_KEY as a repository secret in Press. The workflow exchanges those credentials for an installation token and sends press-system-release repository dispatch events to rebuild YAP, refresh the theme starter version marker, and update official theme demo sites. Product-state observes the same target registry, so dispatch targets and convergence checks stay aligned. Missing GitHub App credentials or incomplete downstream dispatches fail the release job instead of silently leaving the product surface partially unsynced.
The workflow also publishes a release intent manifest for each system release. Immutable copies live at release-artifacts/vX.Y.Z/system-release.json and release-artifacts/vX.Y.Z/release-intent.json, with latest convenience copies at release-artifacts/system-release.json and release-artifacts/release-intent.json; the latest system manifest points at the release intent. Release intent freezes the release target list, expected Press version/tag, artifact/runtime metadata, observed downstream paths, and idempotent reconciler kinds for that release. Downstream repository dispatch payloads include the intent pointers so later reconcilers can treat dispatch as a wake-up signal rather than the source of control truth.
The workflow also publishes a browser-readable product-state ledger at release-artifacts/product-state.json and a human-readable dashboard at release-artifacts/product-state.html. These files are generated status surfaces, not new sources of truth: they materialize the current Press system release, its release intent, runtime asset graph summary, observed YAP and theme-demo runtime versions, the theme starter marker, official catalog entries, theme release manifests, and Connect health into one red/yellow/green product view. The ledger keeps the Press release target under desired, current repository/deployment facts under observed, and the convergence decision under verdict. Initial release publication may show pending downstream reconcilers, but the automatic Product State workflow now polls after successful system releases and fails unless the refreshed verdict converges. A product release is complete only when that converged ledger has been published. Theme Manager reads the JSON ledger to show official theme release state, but still installs from the catalog and theme release manifests. Run node scripts/product-state-ledger.js --system-release dist/system-release.json --release-intent dist/release-intent.json --out dist/product-state.json and node scripts/product-state-dashboard.js --state dist/product-state.json --out dist/product-state.html to generate the same surfaces locally. Add --check for release-state verification, and add --require-converged when checking that the full product surface has caught up to the desired Press release.
The long-lived doc branch is retired. main is now the stable source for the runtime and the official documentation site.
Use short-lived feat/* or codex/* branches for work, then merge them into main after review and verification. See BRANCHING.md for the full policy.
- Press official documentation - the documentation site hosted from this repository.
Want to list your site here? Open a PR with the site URL and a one-line description.
Official themes use separate repositories such as EkilyHQ/Press-Theme-Arcus. New theme repositories should start from EkilyHQ/Press-Theme-Starter. Each theme repository owns its theme source, Press engine range in theme/theme.json, contract checks, release workflow, press-theme-<slug>-vX.Y.Z.zip artifact, SHA-256 digest, and root theme-release.json manifest. EkilyHQ/Press-Theme-Catalog owns the official theme list. Press owns only the runtime infrastructure and native; each site owns its installed packs.json.
- Add LaTeX support.
- Implement comments backed by GitHub Discussions.
MIT License © 2025 Ekily