README: reflow into a narrative arc (story-first), impact-ordered for vibe coders
Reorder sections so it reads like a journey (indirect, no cheesy labels): the dream + the wall you hit → the language (glossary) → what you get → the powers → the honest decision → the commitment → first steps → the data caveat → docs → the mission. Same ideas + section content; only the order changed so the most impactful part (the story) leads.
This commit is contained in:
doxa-maps
parent
d2b8ad979f
commit
ccf6938e4f
1 changed files with 60 additions and 60 deletions
120
README.md
120
README.md
|
|
@ -15,31 +15,6 @@
|
|||
|
||||
---
|
||||
|
||||
## Key terms (don't be afraid of these — you can learn each in one search)
|
||||
|
||||
New to this? Read this table first. You do **not** need to memorize it — just know the words exist and where to learn them.
|
||||
|
||||
| Term | In plain words | Learn more |
|
||||
|---|---|---|
|
||||
| **Vibe coder** | Someone who builds with AI writing most of the code. That's who this is for. | — |
|
||||
| **JAMstack** | A way of building where the front end is just **J**avaScript, **A**PIs, and **M**arkup (HTML/CSS). It runs almost anywhere — including WordPress. | [jamstack.org](https://jamstack.org) |
|
||||
| **Bundler** | A tool that takes all your code and packs it into a few ready‑to‑ship files. This repo *is* a bundler for maps. | [vite.dev/guide](https://vite.dev/guide/) |
|
||||
| **Build step** | The one command (`bun run build`) that turns your code into those shippable files. Your agent can run it for you. | — |
|
||||
| **bun** | A fast, all‑in‑one replacement for `npm` (installs packages, runs scripts). We use it here. | [bun.sh](https://bun.sh) |
|
||||
| **node modules** | The reusable code packages your project depends on. If you use VUE, and VITE you need Node Modules. It is like installing libraries and dependencies that allow VUE to work. `bun install` downloads them into your doxa-maps folder on your laptop `node_modules/`. | [bun.sh/docs](https://bun.sh/docs/cli/install) |
|
||||
| **Dev server** | A local preview website (run this command 'bun run dev' after 'bun install') that updates live as you edit. You run it, it let's you see all the maps in one place so you can give your agents feedback, and see changes almost real time when the agent makes edits. It runs at `http://localhost:5173`. | — |
|
||||
| **Vue / React** | Popular, well‑supported frameworks for building front ends. This bundler is built on **Vue** + **Vite**. You commit to learning one. | [vuejs.org](https://vuejs.org) |
|
||||
| **Web component** | A custom HTML tag (like `<doxa-map>`) that works on any page, no framework required. Each of your maps becomes one. | [MDN: Web Components](https://developer.mozilla.org/en-US/docs/Web/API/Web_components) |
|
||||
| **iframe** | A safe window that embeds one site inside another. Simple, isolated. Each map comes with iframe support by default | [MDN: iframe](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe) |
|
||||
| **Shadow DOM** | Lets your map's JavaScript run *directly* inside the host page (not walled off in an iframe) so it can integrate deeply — while keeping its styles from clashing. | [MDN: Shadow DOM](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_shadow_DOM) |
|
||||
| **SPA (single‑page application)** | One page that composes several maps together in a layout — a whole multi-map site from one build. | [MDN: SPA](https://developer.mozilla.org/en-US/docs/Glossary/SPA) |
|
||||
| **CDN** | A URL that serves a file (JavaScript/CSS) to be fetched and run in a browser. When you use Mapbox, you're loading its CDN. Your built maps are served the same way. JAMstack allows these map frontends to run through a CDN, yes they are that modular! Or, you can run them directly in your site, but CDN allows them to embed via iframe onto partner websites easily with a single URL | [MDN: CDN](https://developer.mozilla.org/en-US/docs/Glossary/CDN) |
|
||||
| **Minify** | The build shrinks your code into compact, hard‑to‑read (but still working) form — smaller and harder to copy. | [MDN: Minification](https://developer.mozilla.org/en-US/docs/Glossary/Minification) |
|
||||
| **Capacitor** | Wraps your maps app into a real iOS/Android apps, or make a SPA ('single-page application' see above) by joining multiple maps together into a layout, and bundling that SPA into IOS/Android easily — **same code, no Swift, no Flutter, no React Native.** | [capacitorjs.com](https://capacitorjs.com) |
|
||||
| **Lazy loading** | Only loads each map when it's actually needed, so a page with many maps stays fast. | [web.dev: lazy loading](https://web.dev/articles/lazy-loading) |
|
||||
|
||||
---
|
||||
|
||||
## Have you ever dreamed of making maps?
|
||||
|
||||
Here's the story. Maybe it's yours too.
|
||||
|
|
@ -65,6 +40,31 @@ That's what this is. Built for communities of map makers who want to make open s
|
|||
|
||||
---
|
||||
|
||||
## Key terms (don't be afraid of these — you can learn each in one search)
|
||||
|
||||
New to this? Read this table first. You do **not** need to memorize it — just know the words exist and where to learn them.
|
||||
|
||||
| Term | In plain words | Learn more |
|
||||
|---|---|---|
|
||||
| **Vibe coder** | Someone who builds with AI writing most of the code. That's who this is for. | — |
|
||||
| **JAMstack** | A way of building where the front end is just **J**avaScript, **A**PIs, and **M**arkup (HTML/CSS). It runs almost anywhere — including WordPress. | [jamstack.org](https://jamstack.org) |
|
||||
| **Bundler** | A tool that takes all your code and packs it into a few ready‑to‑ship files. This repo *is* a bundler for maps. | [vite.dev/guide](https://vite.dev/guide/) |
|
||||
| **Build step** | The one command (`bun run build`) that turns your code into those shippable files. Your agent can run it for you. | — |
|
||||
| **bun** | A fast, all‑in‑one replacement for `npm` (installs packages, runs scripts). We use it here. | [bun.sh](https://bun.sh) |
|
||||
| **node modules** | The reusable code packages your project depends on. If you use VUE, and VITE you need Node Modules. It is like installing libraries and dependencies that allow VUE to work. `bun install` downloads them into your doxa-maps folder on your laptop `node_modules/`. | [bun.sh/docs](https://bun.sh/docs/cli/install) |
|
||||
| **Dev server** | A local preview website (run this command 'bun run dev' after 'bun install') that updates live as you edit. You run it, it let's you see all the maps in one place so you can give your agents feedback, and see changes almost real time when the agent makes edits. It runs at `http://localhost:5173`. | — |
|
||||
| **Vue / React** | Popular, well‑supported frameworks for building front ends. This bundler is built on **Vue** + **Vite**. You commit to learning one. | [vuejs.org](https://vuejs.org) |
|
||||
| **Web component** | A custom HTML tag (like `<doxa-map>`) that works on any page, no framework required. Each of your maps becomes one. | [MDN: Web Components](https://developer.mozilla.org/en-US/docs/Web/API/Web_components) |
|
||||
| **iframe** | A safe window that embeds one site inside another. Simple, isolated. Each map comes with iframe support by default | [MDN: iframe](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe) |
|
||||
| **Shadow DOM** | Lets your map's JavaScript run *directly* inside the host page (not walled off in an iframe) so it can integrate deeply — while keeping its styles from clashing. | [MDN: Shadow DOM](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_shadow_DOM) |
|
||||
| **SPA (single‑page application)** | One page that composes several maps together in a layout — a whole multi-map site from one build. | [MDN: SPA](https://developer.mozilla.org/en-US/docs/Glossary/SPA) |
|
||||
| **CDN** | A URL that serves a file (JavaScript/CSS) to be fetched and run in a browser. When you use Mapbox, you're loading its CDN. Your built maps are served the same way. JAMstack allows these map frontends to run through a CDN, yes they are that modular! Or, you can run them directly in your site, but CDN allows them to embed via iframe onto partner websites easily with a single URL | [MDN: CDN](https://developer.mozilla.org/en-US/docs/Glossary/CDN) |
|
||||
| **Minify** | The build shrinks your code into compact, hard‑to‑read (but still working) form — smaller and harder to copy. | [MDN: Minification](https://developer.mozilla.org/en-US/docs/Glossary/Minification) |
|
||||
| **Capacitor** | Wraps your maps app into a real iOS/Android apps, or make a SPA ('single-page application' see above) by joining multiple maps together into a layout, and bundling that SPA into IOS/Android easily — **same code, no Swift, no Flutter, no React Native.** | [capacitorjs.com](https://capacitorjs.com) |
|
||||
| **Lazy loading** | Only loads each map when it's actually needed, so a page with many maps stays fast. | [web.dev: lazy loading](https://web.dev/articles/lazy-loading) |
|
||||
|
||||
---
|
||||
|
||||
## What doxa-maps gives you
|
||||
|
||||
- **One repository for all your maps.** Each map is an *application profile* in `app-profiles/<your-map>/`.
|
||||
|
|
@ -99,41 +99,6 @@ That's what this is. Built for communities of map makers who want to make open s
|
|||
|
||||
---
|
||||
|
||||
## Quickstart
|
||||
|
||||
You need [**bun**](https://bun.sh) installed (`bun.lock` is committed, so installs are reproducible).
|
||||
|
||||
```bash
|
||||
bun install # download node_modules (one time)
|
||||
|
||||
bun run dev # the playground: http://localhost:5173
|
||||
# every map, clickable, with a copy-paste embed snippet for each
|
||||
|
||||
bun run build # the build step: every app-profiles/<map>/ becomes
|
||||
# public/doxa-maps/<map>/<map>.js + a standalone index.html per map
|
||||
```
|
||||
|
||||
`bun run build` writes everything into **`public/doxa-maps/`** — that's your output folder. Copy it wherever
|
||||
your site or CDN serves files (for example, a host repo's `public/` directory), and your maps are live.
|
||||
|
||||
### Embed a map
|
||||
|
||||
```html
|
||||
<!-- 1) the map engine (Mapbox shown here) -->
|
||||
<link href="https://api.mapbox.com/mapbox-gl-js/v3.24.0/mapbox-gl.css" rel="stylesheet" />
|
||||
<script src="https://api.mapbox.com/mapbox-gl-js/v3.24.0/mapbox-gl.js"></script>
|
||||
|
||||
<!-- 2) your built map + its custom tag -->
|
||||
<script src="/doxa-maps/my-map/my-map.js"></script>
|
||||
<doxa-map profile-config='{"profile":"my-map","tk":"pk.eyJ..."}'></doxa-map>
|
||||
```
|
||||
|
||||
Prefer not to run JavaScript on the host page? **iframe the generated page instead:**
|
||||
`/doxa-maps/<map>/<profile>/index.html`. Both snippets are pre‑generated for every map in
|
||||
`public/doxa-maps/manifest.json`.
|
||||
|
||||
---
|
||||
|
||||
## A word before you decide
|
||||
|
||||
This architecture is probably different from what you're used to. **Different doesn't mean worse** — it
|
||||
|
|
@ -169,6 +134,41 @@ That's the wall. It's small, and everything past it is the maps of your dreams.
|
|||
|
||||
---
|
||||
|
||||
## Quickstart
|
||||
|
||||
You need [**bun**](https://bun.sh) installed (`bun.lock` is committed, so installs are reproducible).
|
||||
|
||||
```bash
|
||||
bun install # download node_modules (one time)
|
||||
|
||||
bun run dev # the playground: http://localhost:5173
|
||||
# every map, clickable, with a copy-paste embed snippet for each
|
||||
|
||||
bun run build # the build step: every app-profiles/<map>/ becomes
|
||||
# public/doxa-maps/<map>/<map>.js + a standalone index.html per map
|
||||
```
|
||||
|
||||
`bun run build` writes everything into **`public/doxa-maps/`** — that's your output folder. Copy it wherever
|
||||
your site or CDN serves files (for example, a host repo's `public/` directory), and your maps are live.
|
||||
|
||||
### Embed a map
|
||||
|
||||
```html
|
||||
<!-- 1) the map engine (Mapbox shown here) -->
|
||||
<link href="https://api.mapbox.com/mapbox-gl-js/v3.24.0/mapbox-gl.css" rel="stylesheet" />
|
||||
<script src="https://api.mapbox.com/mapbox-gl-js/v3.24.0/mapbox-gl.js"></script>
|
||||
|
||||
<!-- 2) your built map + its custom tag -->
|
||||
<script src="/doxa-maps/my-map/my-map.js"></script>
|
||||
<doxa-map profile-config='{"profile":"my-map","tk":"pk.eyJ..."}'></doxa-map>
|
||||
```
|
||||
|
||||
Prefer not to run JavaScript on the host page? **iframe the generated page instead:**
|
||||
`/doxa-maps/<map>/<profile>/index.html`. Both snippets are pre‑generated for every map in
|
||||
`public/doxa-maps/manifest.json`.
|
||||
|
||||
---
|
||||
|
||||
## The data caveat
|
||||
|
||||
Read this so nothing surprises you: **the maps ship without their data.** Because they're JAMstack (pure
|
||||
|
|
|
|||
Loading…
Reference in a new issue