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.
Sites deployed through the Press/YAP Pages artifact workflow can opt out of publishing the browser-editor entry HTML. Commit a regular .press-pages-no-editor file and explicitly set features.editorEntry.enabled: false as a block mapping in site.yaml; both signals are required, and malformed, inline, or ambiguous opt-in mappings fail closed. The feature flag alone only hides public editor links. This policy removes only index_editor.html and index_editor_preview.html from the Pages artifact; source repositories, Press system ZIPs, and YAP runtime syncs retain both files. Existing YAP sites must adopt the YAP builder, policy script, and workflow changes manually because runtime sync intentionally preserves YAP-owned scripts and workflows.
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:
npm ci --ignore-scripts
npm run quality
node scripts/run-tests.mjs --check-manifest
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 scripts/test-encrypted-content.js
node scripts/test-system-updates.mjs
node scripts/test-theme-manager.mjs
node scripts/test-theme-contracts.mjs
node scripts/test-content-model.jsnpm run quality is the project-local code-quality gate. It runs the zero-warning ESLint correctness profile, proves source eslint-disable comments cannot suppress the real project config, remeasures the exact diagnostic/file counts for every reviewed excluded rule, checks the locked TypeScript debt probe, checks incremental Prettier policy, and verifies vendored dependency provenance with the exact tool versions in package-lock.json. Existing unformatted first-party files are listed in scripts/prettier-baseline.json. After bootstrap, that baseline may retain only untouched paths or transfer an exact-content rename; touching a legacy file requires formatting it and removing it from the baseline. New candidate files must pass Prettier and must not be added to the historical baseline. After intentionally formatting a legacy file, regenerate the remaining set with node scripts/check-format.mjs --write-baseline and review that the diff only removes paths or records exact renames.
npm run types:probe runs TypeScript 5.9.3 through the compiler API over the deterministic Git-tracked, non-vendor assets/js JavaScript/module root set. scripts/typescript-debt-baseline.json records the compiler options, root-set count/hash, aggregate first-party/transitive-vendor/global counts, and the exact normalized path + TS code + flattened-message multiset. The probe also uses TypeScript's parsed commentDirectives / checkJsDirective semantics across every root and repository-local assets/js source loaded into the program; the zero baseline prohibits real @ts-ignore, @ts-expect-error, and @ts-nocheck comments without misclassifying identical text in strings or ordinary prose. The normal command requires an exact head match; CI also rejects every new diagnostic key or count increase relative to the merge base. After an intentional type-debt reduction, run npm run types:probe -- --write-baseline and review that the baseline diff only removes keys, lowers counts, or updates the root fingerprint for the reviewed source change. Baseline growth and suppression directives are not accepted update paths.
Vendored browser dependencies are registered in scripts/vendor-manifest.json with their package version, canonical source and release URLs, upstream artifact integrity, local transformation notes, file inventory, and SHA-256 digests. When updating vendored bytes, update that provenance first, then run node scripts/test-vendor-manifest.mjs --write-digests followed by npm run vendor:check; the verifier rejects unowned, missing, altered, or version-mismatched files.
Merges 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, or the exact two-entry editor projection when the tracked opt-in is active, 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