doxa-maps-88655c70 2509a6e347

Deploy to GitHub Pages / build (push) Waiting to run

Details

Deploy to GitHub Pages / deploy (push) Blocked by required conditions

Details

README: three outputs, not five methods; a Languages section; screenshot gates see every shot again

- Deployment is now organised around what the build makes: (1) one web
  folder (536 files, 76 MiB), embedded by iframe and JavaScript (proven) and
  WordPress (just for fun); (2) the mobile app (Capacitor, built); (3) the
  desktop app (Tauri, proof of concept). A hosting table says where the folder
  can go: dx-life's public/, Cloudflare Pages drag-and-drop (fits its 1,000-file
  / 25 MiB limits), GitHub + jsDelivr (JS embeds only: measured, jsDelivr serves
  HTML as text/plain), or any web server, with the one _headers line JS embeds
  need. No Docker. The diagram and the map-cruncher picture say three outputs.
- Languages: 11 locales via ?lang=, Arabic right to left, with an Arabic shot of
  UPG-100 (Big Picture still leaks English in Arabic; reported). The partner
  profile-config locale is deliberately not documented until it is fixed.
- check-shot-freshness and check-shot-distinctness parsed only '...' paths, so
  after 44ef31b2 turned them into `/${TREE_NAME}/...` templates they saw 2 of 26
  shots: distinctness failed, freshness passed vacuously and hid 22 stale shots.
  Both now accept either form and resolve TREE_NAME, and exit 75 (NOT MEASURED)
  unless every `await shot(` call is parsed (the one dynamic dx-life call is
  marked). Negative-tested. The 22 shots are retaken and checked by eye.
- how-to: the shell no longer overwrites the Studio (it now lives in the output
  folder); README serve line points at doxa-maps/index.html.
- Docs follow the rename to dx-maps (09014f8a): every output-folder path and URL in
  README, how-to, reference, CONTRIBUTING, the CLI section and the develop guide now says
  public/dx-maps/. The repo name, the config file name, the WordPress plugin folder and
  the doxa-* tag names are unchanged (tags are a separate landing).
- Hosting: a live example, the dx-life branch research-gallery, which drops the folder
  into dx-life public/ and fills /research with the Research Gallery.

2026-09-25 19:40:03 +00:00

2.9 KiB

Raw Blame History

Contributing to doxa-maps

Everything a contributor needs, short. Recipes live in documentation/how-to.md, lookups in documentation/reference.md, depth in documentation/architecture/.

The mental model — three zones

  library/  (@map)          plugin-designs/<map>/          internal/
  shared, parameterized ──► your map: its screens ──►    the build machine
  legend · map · controls    (.vue) + private colors,     (scripts, staging)
  REUSE, never customize     api wiring, components       NEVER touch
  per-map                    BUILD EVERYTHING HERE

Rule of thumb: local by default — code moves into library/ only when a second map genuinely needs it. One fix in library/ reaches every map on the next build.

Two ways one bundle shows many maps

Pattern A — parameterized: one .vue, many instances differing only by config (*.instances.json → the build emits one standalone page per instance).
Pattern B — multi-profile: several .vue screens in one bundle, selected by profile-config.profile.

Pick A when the maps differ by configuration, B when they differ by layout/behavior. Full walkthrough + the migration story: documentation/architecture/patterns-and-provenance.md.

The two build steps (never confuse them)

Command	What	Writes to `public/`?
`bun run dev`	HMR plugin gallery at `localhost:5173` — iterate on a map in isolation	No
`bun run build`	every bundle → `public/dx-maps/<bundle>/<bundle>.js` + generated pages	Yes

To see a change on the served site: bun run build (or BUNDLE=<name> bun run build:bundle), then refresh. dev never updates the served tree.

Two-terminal workflow for integration work: terminal 1 bun run build:watch (rebuilds into public/ on save) · terminal 2 serves the host site / public/.

Where the bundles go

public/ is the committed web-root — serve it from anywhere and every map is embeddable from it (script tag or the generated per-map page). Same-origin vs external-CDN modes, paths, embedBaseUrl: documentation/how-to.md → "Where do the maps get served from?".

Ground rules

Never edit library/ to customize one map (bundle-private code goes in your src/).
Never bake tokens or data into a bundle — everything arrives at runtime via profile-config.
Before a PR: bun run build && bun run verify must pass (adds drop-portability + parse gates).
Colors are values, not logic: documentation/contributing/COLORS.md.

One-line recap

Copy plugin-designs/template-bundle/, change exactly four things (folder name, tag in index.js, tag/profile strings in index.html, .vue filenames), build everything inside your folder from @map blocks, bun run build, embed the snippet. That's the whole job.

2.9 KiB Raw Blame History