Paste a GitHub markdown file that contains a ```mermaid block (flowchart, sequenceDiagram, stateDiagram, classDiagram, erDiagram, gantt, pie, mindmap, journey, timeline, quadrantChart, gitGraph, xychart, sankey, block, architecture, C4, kanban, packet, requirementDiagram, radar, treemap or zenuml). Optional: a numbered list under the diagram becomes the explanation for each step, and - **Box name**: text adds a note to a box.
+
Paste a GitHub markdown file that contains a ```mermaid block (flowchart, sequenceDiagram, stateDiagram, classDiagram, erDiagram, gantt, pie, mindmap, journey, timeline, quadrantChart, gitGraph, xychart, sankey, block, architecture, C4, kanban, packet, requirementDiagram, radar, treemap or zenuml). Optional: a numbered list under the diagram becomes the explanation for each step, and - **Box name**: text adds a note to a box. Or load a public URL (GitHub blob links are rewritten to raw).
+
+
+
+
@@ -2297,6 +2304,39 @@
Flow Explainer
const staticPage=(dim,embed)=>tidyUrl(rootUrl()+'/'+(dim==='3d'?'3d.html':'index.html'))+(embed?'?embed=1':'');
const linkOpts=()=>(DSK!=='original'?'&s='+DSK:'')+(ICONS_ON?'':'&i=0');
const clientLink=async()=>(isStaticHost()?staticPage(is3dView()?'3d':'2d'):pageUrl(is3dView()?'/3d':''))+'#c='+await encode(/** @type {any} */(S).md)+linkOpts();
+/**
+ * Turn a pasted GitHub blob URL into a raw URL browsers can fetch.
+ * @param {string} raw
+ * @returns {string}
+ */
+function normalizeMdUrl(raw){
+ let u;
+ try{u=new URL(String(raw||'').trim())}catch(e){throw new Error('That does not look like a URL.',{cause:e})}
+ if(u.protocol!=='http:'&&u.protocol!=='https:')throw new Error('Only http(s) URLs are allowed.');
+ if(/^(www\.)?github\.com$/i.test(u.hostname)){
+ const m=u.pathname.match(/^\/([^/]+)\/([^/]+)\/blob\/([^/]+)\/(.+)$/);
+ if(m)return 'https://raw.githubusercontent.com/'+m[1]+'/'+m[2]+'/'+m[3]+'/'+m[4]+u.search;
+ }
+ return u.href;
+}
+/**
+ * Fetch markdown text from a public URL (browser CORS applies).
+ * @param {string} raw
+ * @returns {Promise}
+ */
+async function fetchMarkdown(raw){
+ const href=normalizeMdUrl(raw);
+ let res;
+ try{res=await fetch(href,{mode:'cors',credentials:'omit',redirect:'follow'})}
+ catch(e){throw new Error('Could not fetch that URL (network or CORS). Use a public raw URL, paste the file, or share a #c= client link.',{cause:e})}
+ if(!res.ok)throw new Error('Fetch failed ('+res.status+' '+res.statusText+'). Check the URL is public.');
+ const text=await res.text();
+ if(text.length>1500000)throw new Error('File is too large (max about 1.5 MB).');
+ if(!text.trim())throw new Error('That URL returned an empty file.');
+ return text;
+}
+/** Shareable hash that reloads markdown from a URL on open. @param {string} url */
+const urlLink=url=>(isStaticHost()?staticPage(is3dView()?'3d':'2d'):pageUrl(is3dView()?'/3d':''))+'#u='+encodeURIComponent(normalizeMdUrl(url))+linkOpts();
/**
* iframe HTML for pasting into a website, like YouTube's "Embed" code.
* @param {string} url the /embed link (with #c=…)
@@ -2863,6 +2903,18 @@
(async function init(){
if(isEmbed())document.body.classList.add('embed','client');
- let md=null;const m=location.hash.match(/^#([cd])=([^&]+)/);initStyle();wireUi();
- if(m){try{md=await decode(m[2]);if(m[1]==='c')document.body.classList.add('client')}catch(e){md=null}}
+ let md=null,fromHash=false,urlErr='';const m=location.hash.match(/^#([cdu])=([^&]+)/);initStyle();wireUi();
+ if(m){
+ fromHash=true;
+ try{
+ if(m[1]==='u'){md=await fetchMarkdown(decodeURIComponent(m[2]));$('#mdUrl').value=decodeURIComponent(m[2])}
+ else{md=await decode(m[2]);if(m[1]==='c')document.body.classList.add('client')}
+ }catch(e){md=null;urlErr=e instanceof Error?e.message:String(e)}
+ }
if(md==null&&!m&&!isEmbed())try{md=localStorage.getItem('flowx.md')}catch(e){}
- if(md)try{load(md,!!m||isEmbed());return}catch(e){}
+ if(md)try{load(md,fromHash||isEmbed());return}catch(e){if(fromHash&&m&&m[1]==='u'){drawer(true);showErr(e instanceof Error?e.message:String(e));return}}
+ if(urlErr){drawer(true);showErr(urlErr);toast(urlErr)}
const t=document.title;load($('#ex1').textContent.trim()+'\n',true);document.title=t; // keep the descriptive page title for the built-in demo
})();
diff --git a/AGENTS.md b/AGENTS.md
index 7a2bb0e..154eebf 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -6,7 +6,7 @@ Turns pasted GitHub markdown (Mermaid flowchart, sequence, state, class, ER, gan
- `3d.html` — Three.js version (real 3D blocks, rotatable camera). Also served via zo.space (route `/flow-explainer/:file`; Three.js 0.187.0 jsDelivr-minified in `vendor/`, imported as `./vendor/three.module.js` and served by route `/flow-explainer/vendor/:file`).
- Both files are standalone and edited directly; they share the same markdown parser, layout, panel, timeline and `#c=` client-link code (copied, not imported). The shared core (`/* ---------- shared core:` … `/* ---------- end of diagram styles + settings`: helpers, markdown + Mermaid parsers, layout, diagram styles/settings UI) is edited in `index.html` only, then copied with `python3 tools/sync-parser.py` (`--check` to verify). Layout spacing differs per page via `IS_3D_PAGE`. Non-parser fixes (render, buildScene, iconFor) still go into both files by hand.
- Every diagram type is converted into the same `{nodes,links,steps,groups}` graph. Extra node fields: `note`, `icon` (forced emoji), `iconFallback`, `ci` (palette index), `hk` (height factor: pie, journey, xychart, sankey, packet). Graph flags: `fixed` (parser set `gx/gy`, skip `layout()`; non-pie fixed parsers call `routeFixed()` to give links `pts`: timeline, quadrant, git, xychart, block, kanban, packet), `noZones` (colour groups without zone slabs, mindmap), `diagramTitle` (used when the markdown has no heading).
-- Both read the same `localStorage` key `flowx.md`; the 2D/3D button keeps the URL hash and works with both `/flow-explainer` ↔ `/flow-explainer/3d` and `index.html` ↔ `3d.html` (static hosting).
+- Both read the same `localStorage` key `flowx.md`; the 2D/3D button keeps the URL hash and works with both `/flow-explainer` ↔ `/flow-explainer/3d` and `index.html` ↔ `3d.html` (static hosting). Hash loaders: `#c=` / `#d=` compressed markdown, `#u=` public URL (`normalizeMdUrl` / `fetchMarkdown`; GitHub blob → raw). Edit drawer has **Load URL**; `embed.js` accepts `data-u` as an alternative to `data-c`.
- Public repo: https://github.com/solutionforest/flow-explainer (MIT). README images in `docs/images/` were made with the Snapshot button; sample inputs in `examples/`.
- 📸 Snapshot (edit mode only): modal exports a README PNG (title header, optional step-number badges, group legend, optional credit strip `drawCredit()`: icon + “Made with Flow Explainer” + `flow-explainer.laravel.cloud`, on by default) + "Copy README text" (image link + numbered steps). Overlap checker lists label/box/step-number collisions; "minor" = label sitting on an arrow line.
- 2D: `render()` places node labels (lift/side shift), arrow labels and badges greedily to avoid collisions; export serialises the SVG with scene CSS inlined.
diff --git a/README.md b/README.md
index 211a5fa..88bf571 100644
--- a/README.md
+++ b/README.md
@@ -49,7 +49,7 @@ The full source of that picture is [`examples/how-it-works.md`](examples/how-it-
Or [run it yourself](#run-it-yourself).
1. Open `index.html` (2D) or `3d.html` (3D) from any static file server — see [Run it yourself](#run-it-yourself).
-2. Press **New** (or **Edit** to change the current one), paste your markdown, then **Render ▶**. **Use template** fills in a starter file, **Open .md** loads one from your computer, and the **Examples** menu in the top bar loads a sample.
+2. Press **New** (or **Edit** to change the current one), paste your markdown, then **Render ▶**. **Use template** fills in a starter file, **Open .md** loads one from your computer, **Load URL** fetches a public `.md` (GitHub blob links are rewritten to raw), and the **Examples** menu in the top bar loads a sample. You can also open `#u=` directly.
3. Press **▶ Play**, or step with **Next / Back**, the ← → keys, or the numbered timeline at the bottom.
4. Press **Copy client link** and send it. The link opens in view-only mode, without Edit or Snapshot, and in the diagram style you picked.
5. Open **⚙ Settings** (top right) to pick a diagram style, show or hide the emoji icons on the blocks, or switch between 3D and 2D.
@@ -313,7 +313,7 @@ Script tag (GitHub Pages — good default for third-party sites):
data-title="How an online ticket order is handled">
```
-`data-c` is the same payload as a client link’s `#c=`. Optional: `data-view="3d"`, `data-text="1"`, `data-switch="0"`, `data-s="teal"`, `data-i="0"`, `data-size="640x480"`, `data-host="https://flow-explainer.laravel.cloud"` (force Cloud player while loading the script from Pages).
+`data-c` is the same payload as a client link’s `#c=`. Or use `data-u="https://…/file.md"` to have the player fetch public markdown (`#u=`). Optional: `data-view="3d"`, `data-text="1"`, `data-switch="0"`, `data-s="teal"`, `data-i="0"`, `data-size="640x480"`, `data-host="https://flow-explainer.laravel.cloud"` (force Cloud player while loading the script from Pages).
iframe (Cloud) equivalent:
@@ -329,9 +329,10 @@ The host must allow framing (Cloud uses frame = `all`). Diagram data still lives
- Your markdown is kept in your browser's local storage (`flowx.md`) so it survives a reload.
- A client link stores the diagram compressed inside the part of the address after `#`. Browsers never send that part to a server, so the host only sees a request for the page.
+- **Load from URL** (`#u=…` or Edit → Load URL) makes your browser `fetch` that public file. Flow Explainer’s server still does not see the markdown, but the remote host sees the request. CORS must allow the fetch (raw GitHub URLs usually do; many other hosts do not).
- Anyone who has a client link can read the diagram, so treat it like the document itself. The link is compressed, not encrypted. **Copy client link** shows this reminder every time.
- Chat apps, email and browser history keep the full link wherever you paste it.
-- The page loads no fonts, scripts or trackers from other sites. Everything it needs is in this repository.
+- The page loads no fonts, scripts or trackers from other sites (except when you choose to fetch a markdown URL). Everything else it needs is in this repository.
## Project layout
diff --git a/embed.js b/embed.js
index 63dce14..99ae2bd 100644
--- a/embed.js
+++ b/embed.js
@@ -1,6 +1,7 @@
/*! Flow Explainer embed loader
* https://github.com/solutionforest/flow-explainer
* Drop on any site:
+ * Or load markdown from a public URL: data-u="https://…/file.md" (instead of data-c).
* Builds an iframe to the player. data-c is the same payload as a client link’s #c=.
*/
(function () {
@@ -9,8 +10,9 @@
if (!s || !s.getAttribute) return;
var d = s.dataset || {};
var c = d.c || d.payload || '';
- if (!c) {
- if (typeof console !== 'undefined') console.warn('[flow-explainer] data-c is required');
+ var u = d.u || d.url || '';
+ if (!c && !u) {
+ if (typeof console !== 'undefined') console.warn('[flow-explainer] data-c or data-u is required');
return;
}
var view = String(d.view || '2d').toLowerCase() === '3d' ? '3d' : '2d';
@@ -47,7 +49,7 @@
return;
}
- var hash = '#c=' + c;
+ var hash = u ? '#u=' + encodeURIComponent(u) : '#c=' + c;
if (d.s) hash += '&s=' + encodeURIComponent(d.s);
if (d.i === '0') hash += '&i=0';
// Default: hide step text (diagram + controls only). Pass data-text="1" to show it.
diff --git a/index.html b/index.html
index 499646e..78c4ed7 100644
--- a/index.html
+++ b/index.html
@@ -145,6 +145,9 @@
.drawer code{font-family:var(--mono);font-size:.92em}
.drawer textarea{flex:1;resize:none;border:1px solid var(--line-2);border-radius:10px;padding:12px;font-family:var(--mono);font-size:12.5px;line-height:1.5;background:var(--paper);min-height:0;white-space:pre;overflow:auto}
.drawer textarea:focus{outline:2px solid var(--brand-100);border-color:var(--brand)}
+.drawer .url-row{display:flex;gap:6px;align-items:center}
+.drawer .url-row input{flex:1;min-width:0;border:1px solid var(--line-2);border-radius:8px;padding:8px 10px;font:12.5px var(--mono);background:var(--paper);color:var(--ink)}
+.drawer .url-row input:focus{outline:2px solid var(--brand-100);border-color:var(--brand)}
.row{display:flex;gap:8px;flex-wrap:wrap;align-items:center}
.err{display:none;border:1px solid #f0b3a3;background:#fdf0ec;color:#8f2412;border-radius:8px;padding:8px 10px;font-size:13px}
.err.show{display:block}
@@ -431,7 +434,11 @@
Flow Explainer
Paste your markdown
-
Paste a GitHub markdown file that contains a ```mermaid block (flowchart, sequenceDiagram, stateDiagram, classDiagram, erDiagram, gantt, pie, mindmap, journey, timeline, quadrantChart, gitGraph, xychart, sankey, block, architecture, C4, kanban, packet, requirementDiagram, radar, treemap or zenuml). Optional: a numbered list under the diagram becomes the explanation for each step, and - **Box name**: text adds a note to a box.
+
Paste a GitHub markdown file that contains a ```mermaid block (flowchart, sequenceDiagram, stateDiagram, classDiagram, erDiagram, gantt, pie, mindmap, journey, timeline, quadrantChart, gitGraph, xychart, sankey, block, architecture, C4, kanban, packet, requirementDiagram, radar, treemap or zenuml). Optional: a numbered list under the diagram becomes the explanation for each step, and - **Box name**: text adds a note to a box. Or load a public URL (GitHub blob links are rewritten to raw).
+
+
+
+
@@ -2313,6 +2320,39 @@
Flow Explainer
const staticPage=(dim,embed)=>tidyUrl(rootUrl()+'/'+(dim==='3d'?'3d.html':'index.html'))+(embed?'?embed=1':'');
const linkOpts=()=>(DSK!=='original'?'&s='+DSK:'')+(ICONS_ON?'':'&i=0');
const clientLink=async()=>(isStaticHost()?staticPage(is3dView()?'3d':'2d'):pageUrl(is3dView()?'/3d':''))+'#c='+await encode(/** @type {any} */(S).md)+linkOpts();
+/**
+ * Turn a pasted GitHub blob URL into a raw URL browsers can fetch.
+ * @param {string} raw
+ * @returns {string}
+ */
+function normalizeMdUrl(raw){
+ let u;
+ try{u=new URL(String(raw||'').trim())}catch(e){throw new Error('That does not look like a URL.',{cause:e})}
+ if(u.protocol!=='http:'&&u.protocol!=='https:')throw new Error('Only http(s) URLs are allowed.');
+ if(/^(www\.)?github\.com$/i.test(u.hostname)){
+ const m=u.pathname.match(/^\/([^/]+)\/([^/]+)\/blob\/([^/]+)\/(.+)$/);
+ if(m)return 'https://raw.githubusercontent.com/'+m[1]+'/'+m[2]+'/'+m[3]+'/'+m[4]+u.search;
+ }
+ return u.href;
+}
+/**
+ * Fetch markdown text from a public URL (browser CORS applies).
+ * @param {string} raw
+ * @returns {Promise}
+ */
+async function fetchMarkdown(raw){
+ const href=normalizeMdUrl(raw);
+ let res;
+ try{res=await fetch(href,{mode:'cors',credentials:'omit',redirect:'follow'})}
+ catch(e){throw new Error('Could not fetch that URL (network or CORS). Use a public raw URL, paste the file, or share a #c= client link.',{cause:e})}
+ if(!res.ok)throw new Error('Fetch failed ('+res.status+' '+res.statusText+'). Check the URL is public.');
+ const text=await res.text();
+ if(text.length>1500000)throw new Error('File is too large (max about 1.5 MB).');
+ if(!text.trim())throw new Error('That URL returned an empty file.');
+ return text;
+}
+/** Shareable hash that reloads markdown from a URL on open. @param {string} url */
+const urlLink=url=>(isStaticHost()?staticPage(is3dView()?'3d':'2d'):pageUrl(is3dView()?'/3d':''))+'#u='+encodeURIComponent(normalizeMdUrl(url))+linkOpts();
/**
* iframe HTML for pasting into a website, like YouTube's "Embed" code.
* @param {string} url the /embed link (with #c=…)
@@ -2785,6 +2825,18 @@