Images And Files

You can put images and files straight into a journal entry or page. An image shows inline as you write. Any other file, a PDF, a spreadsheet, an archive, becomes a link you can open or download. EtherPK calls both an asset, and stores them with the graph: in the assets/ folder of a local graph (Local Graphs), or encrypted on the Sync Server for a synced one.

Add an asset

Three routes end in the same place:

• Drag and drop. Drag an image or a file from your desktop onto the editor and drop it where it should go. A reference appears at the drop point.
• Paste. Copy a screenshot, an image from a web page or a file from your file manager, then press Ctrl+V (Cmd+V on a Mac) in the editor. The reference lands at the cursor, replacing anything selected. A screenshot has no name of its own, so it is saved as image- followed by the date and time you pasted it, image-2026-09-02-14-32-08.png for example. A copied file keeps its name. If what you copied holds text as well as a picture (cells from a spreadsheet, say), the text is pasted instead.
• The upload window. Type / and choose Upload asset, or tap the upload button on the phone's command bar. The window has a drop zone, a Browse files button and a Paste from clipboard button. Pick or paste one or more files and they are inserted where the cursor was. Ctrl+V works in this window too. On a phone or tablet, where there is no Ctrl+V, the paste button reads images from the clipboard but not other kinds of file, so a copied PDF needs a desktop.

An image shows inline at once. Another kind of file becomes a link.

Images are made smaller on the way in

A screenshot or a phone photo is usually far larger than it needs to be, and every device that opens the note has to fetch it. So as an image is added, EtherPK re-saves it as WebP at 90% quality, the same pixels at the same size on screen, and keeps that version only if it is at least a tenth smaller. Otherwise the file is stored exactly as you gave it, so an image that is already well compressed is left alone.

• Dimensions never change. A display-size hint is a separate, on-screen matter.
• Only PNG, JPEG, WebP and BMP files are candidates. An animated GIF, an SVG and an AVIF are stored as given, as is anything that is not an image.
• The stored file has a .webp extension, so a screenshot added as shot.png is referenced as ../assets/shot.a1b2c3d4.webp. The description in the note still reads shot.
• A photo's camera metadata (location, capture time, camera model) does not survive. Its orientation is applied to the picture itself, so nothing appears sideways.
• The message in the corner says what happened: "1 asset uploaded, 3.1 MB → 480.0 KB". A file kept as given shows no arrow.

Pasting or dropping onto the editor always optimises. To keep an original, a lossless PNG for pixel-exact work for instance, use the upload window and untick Optimise images before you choose the file. The box is ticked again the next time the window opens.

In a browser that cannot write WebP (Safari as of September 2026, which means every browser on an iPhone or iPad), a JPEG is re-saved as a JPEG at 90% quality and everything else is stored as given. EtherPK checks what the browser can do rather than assuming.

An import never optimises: it copies its source faithfully (Importing From Logseq Obsidian Or EtherPK). Nor does an agent's upload through the Headless Client.

How an asset looks in the markdown

An asset is an ordinary markdown image or link that points into the graph's assets/ folder:

![Quarterly chart](../assets/quarterly-chart.a1b2c3d4.png)

[Q3 report](../assets/q3-report.5e6f7a8b.pdf)

EtherPK writes these lines for you, and they are yours to edit.

An image address on the web works too: ![A photo](https://example.org/photo.png) renders inline like an uploaded one. It is fetched from that site each time the note is shown, so the site can see that somebody at your address viewed it and when. Upload the picture instead if that matters, or if you want it to outlive the site.

Control an image's display size

An image without a hint renders at its natural size, never wider than the editor. To cap it, add a display-size hint after a | in the image's description, the text between ![ and ]:

![A diagram|300](../assets/a-diagram.a1b2c3d4.png)

The hint is a maximum. A larger image scales down to fit, keeping its proportions; a smaller one is left at its natural size and never enlarged.

• |300 limits the width to 300 pixels. The height follows to keep the proportions.
• |640x480 limits the width and the height.

The hint is part of the description, so it travels with the note and reads as plain alt text in any other markdown editor. Remove it to go back to the natural size. Click onto the image's line to see and edit the raw markdown; click away to see the result.

A default size for every upload

Images you upload arrive with a hint already applied, |800 unless you say otherwise, so a large photo never swamps the page. To choose your own, open Settings > General and fill in Default maximum image display size on upload with a width such as 300, or a width and height such as 300x200. From then on, images uploaded into that graph arrive with that limit, and you can still change or remove it on any one image. Enter 0 to upload with no hint. Leave the field blank to return to 800. The setting belongs to the graph, so every member of a shared graph gets the same default (Graph Settings).

Copy, download, open and delete

Every asset in a note carries the same actions wherever it appears. A picture has one more:

• Copy image (pictures only) puts the picture on the clipboard, ready to paste into a chat, an email or another note. It always arrives as a PNG, whatever format the file is stored in, because that is the format every clipboard accepts. The button ticks for a moment and the corner says "Image copied".
• Download saves the file to your computer under its own name, without the fingerprint. An image that was made smaller downloads as the WebP that was stored.
• Open in a new tab opens the file in its own EtherPK tab, for the types EtherPK can show. Images and PDFs both work. A PDF is drawn by EtherPK itself, so it looks the same in every browser.
• Delete removes the reference and, when it is safe, the file. See Delete a file.

Where the actions are:

• On a picture. Hover over it and the icons appear in its top right corner, copy first.
• On a file link. The icons sit after the link and brighten as the pointer nears them.
• On a phone or tablet, or by right-click. Long-press the picture or the link (right-click on a desktop) for the same actions in a menu. A touch screen has no hover, so this is the route there.
• In the Backlinks panel. A reference that mentions a file shows the picture or the link's own label rather than its path, with Copy image, Download and Open in a new tab in the same places. There is no bin there: deleting happens in the note, because that is the only place the reference can be removed. Pictures show as thumbnails; open one in a tab to see it full size.

Clicking a file link downloads it. To put the cursor inside the link text and edit it, hold Ctrl (Cmd on a Mac) as you click.

Delete a file

The bin icon does two things at once, and only when it is safe: it takes the picture or link out of the note and deletes the file itself.

The second part is permanent, so EtherPK first checks whether anything else uses the file:

• If this is the only place, you get a confirmation and both go.
• If the file is used elsewhere too, EtherPK does not delete it. The dialog names the notes that use it, each one a link so you can go and clear them, and offers to remove the reference from this note only.

A synced graph has one more check. Another device might have added a reference you have not received yet, so before deleting a file EtherPK confirms it is online and fully caught up with the server. If it is not, it says so and offers to remove the reference from this note only. The file stays, and you can delete it once caught up.

Removing the reference is an ordinary edit, so Ctrl+Z brings it back. Deleting the file is not. Undo after a delete brings the picture back as a broken image with its description showing, because there is no file behind it any more.

Deleting an ![...] or [...] line by hand leaves the file behind. To tidy up later, open Settings > Maintenance and run Scan for orphaned assets. It lists every file no note references and lets you delete them, with a confirmation. It works in local and synced graphs.

Where assets are stored

In a local graph, assets are files in the assets/ folder inside the graph folder, next to journals/ and pages/. Back them up, sync them, or open them in any other app, like the notes.

Each asset is saved under a unique name: the original name in lower case with hyphens, then a short fingerprint of the contents, then the extension:

assets/quarterly-chart.a1b2c3d4.png

The fingerprint means the same image is only ever stored once. Drop the same picture into ten notes and there is one file, referenced ten times. The contents decide, not the name: add the same picture again under a different filename and EtherPK points at the file it already has, while the description in the note keeps the name you added it with.

A synced graph does the same, though the server never sees the fingerprint. Your device sends a scrambled version that only has meaning inside your graph. If the graph already holds those exact bytes, the server says so, nothing is uploaded, your storage does not grow, and the corner reads "already in this graph, reused". The server learns only that two things in your graph are identical, never what they are, and cannot compare across graphs. An asset the graph held before it kept this index is indexed for reuse the next time you run Scan for orphaned assets.

A synced graph's assets exist only in encrypted form on the server, so there is no folder to open them from. For readable copies on your own disk, turn on a Local Mirror: it downloads and decrypts every attachment the graph holds into a folder you choose. See Keeping A Local Copy Of A Synced Graph.

Who can reach a synced asset

A synced asset is not a public file. A signed-in EtherPK user cannot fetch an asset from somebody else's graph unless they are an active member of that graph. Knowing the graph id, the asset id or the storage path is not enough, and a token for a different graph does not help.

That is the graph's protection, not a document's. A file attached to a protected document (Protected Documents) is encrypted for the graph like any other asset, so every member can open it, and a link to it from any other document shows it. The protection passphrase covers the document's text only.

A download has two separate checks:

1. EtherPK asks the Sync Server for the asset. The server checks that the credential belongs to an active member of this exact graph before returning anything.
2. The server returns signed download addresses for that asset's encrypted chunks only. Each address expires after 15 minutes. An unsigned request to the storage bucket is refused.

The signed address is not the decryption key. Assets are split into chunks and encrypted on your device with AES-256-GCM under a random key for that asset. The asset key, original filename, file type and content fingerprint are themselves encrypted under the graph's key, and objects in the bucket are named by random ids rather than filenames. The server and the storage operator hold ciphertext and cannot turn it back into the original.

What that does not cover:

• A signed address is temporary bearer access to one encrypted chunk. Anyone who gets a copy can download that ciphertext until the address expires, but still needs the graph's key to read it.
• Removing a Player blocks new asset requests at once, even if their sync token has not expired. An address already issued stays valid for the rest of its 15 minutes. As with notes, a former Player keeps anything they downloaded while they were a member.
• Any current member can save or share an asset after decrypting it. Encryption cannot stop an authorised person copying what they can already read.
• A compromised unlocked device, a malicious browser extension or a leaked graph key exposes the plaintext.

For a file that should stay where it is on your computer rather than travel with the graph, link to it instead: Links To Websites And Files.