Assets
Images, SVG and PDF: what is accepted, and how the library works.
Assets
Section titled “Assets”An asset is a file your pages reference: a screenshot, a diagram, a logo, a downloadable specification.
What is accepted
Section titled “What is accepted”| Type | Extension |
|---|---|
| PNG | .png |
| JPEG | .jpg, .jpeg |
| GIF | .gif |
| WebP | .webp |
| SVG | .svg |
.pdf |
Two limits apply to every upload:
- 25 MB. Generous for a screenshot, deliberately mean for a video. Use
:::embedfor video. - 50 megapixels. Width times height. A 100 MP PNG can be small on disk and gigabytes once a browser decodes it, so the pixel count is capped as well as the byte count.
Note
The Content-Type your browser declares is ignored. Staleless reads the first
bytes of the file and decides the type from those. A .png that is really an
executable is rejected.
SVG is sanitised, not trusted
Section titled “SVG is sanitised, not trusted”An SVG is a document that can carry script. Every uploaded SVG is rewritten against an allowlist of elements and attributes. Anything outside it is removed, and the upload result names what was removed, so you can see whether the file still says what you meant.
How files are named
Section titled “How files are named”Every asset is stored by the hash of its bytes: sha256/<hash>.<ext>.
This has three consequences worth knowing:
- The same file uploaded twice is one file. The hash is identical.
- A URL is safe to cache for a year. Different bytes cannot produce the same key, so a changed image is a changed URL.
- A filename you chose never becomes a path. Path traversal is not defended against here; it is unreachable.
Using an asset
Section titled “Using an asset”:::figure{src="/assets/publish-flow.png" alt="The publish flow"}A change is staged, committed, then merged by a person.:::An src that points at no asset fails the missing-asset rule, so a commit
cannot leave a broken image on a page.
The library
Section titled “The library”The asset library lists every file in the project with its thumbnail, type, size, uploader, upload date and usage count.
Three actions:
Replace. Upload new bytes in place of old ones. Every page that references the asset shows the new file. Use this for a screenshot that went out of date.
Alt text. Set or correct the alternative text from the library rather than on each page.
Delete. Before anything is destroyed, the library shows every page that uses the file. Deleting a referenced asset needs an explicit confirmation, and the deletion is named in the audit log, because it destroys bytes while pages may still point at them.
Private projects
Section titled “Private projects”An asset in a private project is not served from a permanently public URL. The bytes are behind the same gate as the pages. See Private documentation.