frontend: insert a figure into a sentence, and print it as one
The editor gains 「插入图片」: it uploads the file and appends the sentence that
shows it, and a file dropped anywhere in the dialog does the same. Each row then
prints the picture it holds, not only the path to it — checking that the right
curve landed in the right paragraph is the whole reason to look at the editor.
Reading it back, one rule decides the layout: a sentence holding nothing but an
image is a figure — its own line, centred, the text in the brackets printed
underneath as its 图注 — while an image inside a run of text stays on the line,
height capped so a pasted screenshot cannot stretch a line of prose. The size is
optional, in pandoc's `{width=70%}` form, and is validated to digits plus one
unit before it becomes a CSS length.
`utils/math.ts` becomes `utils/rich.ts`, because it now reads two families of
markup rather than one: the formulas it always parsed, and the images a sentence
keeps as Markdown. A figure is deliberately not built inside the `v-html` string
the rest of a sentence is: `PaperParagraph` prints it as a real `<img>`, so it
can carry the writer's size and open at full resolution when clicked — an
experiment figure on a page is often too small to check a curve against.
This commit is contained in:
+93
-8
@@ -358,6 +358,68 @@ sentences printed correctly by accident (the full stop hides the missing space),
|
||||
so nothing looked wrong until the first English paper, whose sentences would
|
||||
have run together.
|
||||
|
||||
### An image is an object, and the sentence keeps only its address
|
||||
|
||||
Not everything in a paper is text, and the parts that are not do not get a table.
|
||||
The bytes of a 插图 live in **MinIO** (k3s, S3 protocol) and the sentence keeps
|
||||
the address, as Markdown:
|
||||
|
||||
```
|
||||
试验装置如  所示。
|
||||
{width=70%}
|
||||
```
|
||||
|
||||
A table was the obvious alternative — `paper_image` with a `sort`, a caption and
|
||||
a paragraph position — and it is wrong here, for the reason the sentence model
|
||||
already gives: a paragraph is *reassembled from sentences ordered by one number*,
|
||||
and a second table holding its own `sort` beside that one gives a paragraph two
|
||||
orderings that eventually disagree. Keeping the picture inside `content` means a
|
||||
figure moves between paragraphs by being cut and pasted, survives a template
|
||||
switch with the sentence it belongs to, and needs no new endpoint to write. The
|
||||
same argument that made citations a table (a citation carries data of its own,
|
||||
and is queried in both directions) is what keeps images out of one.
|
||||
|
||||
Three properties of the storage are deliberate:
|
||||
|
||||
- **The key is the digest of the picture.** `2026/09/9f8c1a4b7e2d0c33.png` is
|
||||
derived from the bytes, so uploading the same screenshot twice — from two
|
||||
paragraphs, or by accident — stores one object, and the address can never come
|
||||
to mean a different picture than the one it was written for. That is what makes
|
||||
the year-long `immutable` cache header safe to hand out.
|
||||
- **The format is sniffed, never trusted.** The declared content type and the
|
||||
filename are the uploader's claims; the magic bytes are the fact. PNG, JPEG,
|
||||
GIF and WebP are accepted — and **SVG is not**, because an uploaded SVG served
|
||||
from this origin is stored XSS, while the page already renders text the writer
|
||||
controls. The served content type comes from a whitelist on our side, with
|
||||
`X-Content-Type-Options: nosniff`.
|
||||
- **The key space is also the access rule.** `GET /api/images/{key}` serves keys
|
||||
of the shape this application writes and nothing else, so the read route cannot
|
||||
become a browser for the rest of the bucket, whatever else is in it.
|
||||
|
||||
Images are served through the API rather than from a public bucket URL so that a
|
||||
sentence never embeds a host name: the same paper is read from the LAN in
|
||||
development and from the public address later, and a hard-coded origin would
|
||||
break on the other. It also means the bucket stays private. The response streams
|
||||
the object out of MinIO rather than reading it into memory, and releases the
|
||||
connection when the reader stops.
|
||||
|
||||
Two rules decide how a picture prints, and both follow from "a sentence is a
|
||||
line":
|
||||
|
||||
| What the sentence holds | How it prints |
|
||||
|---|---|
|
||||
| nothing but `` | a **figure**: its own line, centred, the brackets' text as 图注 underneath |
|
||||
| an image inside a run of text | **inline**, on the line with the words, height capped at `12em` |
|
||||
|
||||
The size is optional and comes from pandoc's attribute form — `{width=70%}`,
|
||||
`{width=400px}` — and is validated to digits plus one unit before it becomes a
|
||||
CSS length, so no second declaration can be smuggled through it.
|
||||
|
||||
Configuration is three variables (`MINIO_ENDPOINT`, `MINIO_ACCESS_KEY`,
|
||||
`MINIO_SECRET_KEY`, plus `MINIO_BUCKET`). Left empty, the paper still writes and
|
||||
reads: only the image routes answer `503`, saying which variables are missing.
|
||||
The bucket is created on the first upload if it is not there.
|
||||
|
||||
### Citations are a table, not a column
|
||||
|
||||
One sentence may quote several references, so
|
||||
@@ -465,6 +527,8 @@ All routes are mounted under `/api`. Interactive docs at `/docs`.
|
||||
| `PUT` | `/papers/{id}/paragraphs/{sort}` | full replacement; optional `target_sort` moves it |
|
||||
| `POST` | `/papers/{id}/sentences` | append one sentence |
|
||||
| `PATCH` `DELETE` | `/papers/{id}/sentences/{id}` | edit or remove one sentence |
|
||||
| `POST` | `/images` | `multipart/form-data`, one `file` field; answers `key`, `url`, ready-to-paste `markdown`, `content_type`, `size`, `sha256` |
|
||||
| `GET` | `/images/{key}` | streams the picture; only keys this app wrote, cached `immutable` for a year |
|
||||
|
||||
Conventions worth knowing:
|
||||
|
||||
@@ -510,6 +574,12 @@ Conventions worth knowing:
|
||||
rail's labels compose with the toolbar's.
|
||||
- A DOI is stored without its ``https://doi.org/`` prefix, so the column holds
|
||||
one spelling whichever way it was pasted.
|
||||
- An uploaded image is refused with `415` when its bytes are not PNG/JPEG/GIF/
|
||||
WebP (SVG included), `413` when it is over `MAX_IMAGE_BYTES` (20 MiB) and `400`
|
||||
when it is empty. A key that has no object, or one this application did not
|
||||
write, is `404`.
|
||||
- An image URL is relative (`/api/images/…`) and same-origin on purpose: the
|
||||
client prints it as it stands, and the paper does not name a host.
|
||||
|
||||
## MCP server
|
||||
|
||||
@@ -693,15 +763,16 @@ are not lists (the paper document) keep scrolling normally.
|
||||
|
||||
A formula is stored exactly as the writer typed it — `$\ell$`, `$$ … \tag{1} $$`
|
||||
— because that is the form that can be edited; an equation image cannot be
|
||||
changed by one character. Typesetting happens when the paper is read, in
|
||||
`src/utils/math.ts`, which splits a sentence into text and formulas, hands the
|
||||
formulas to KaTeX and escapes everything else.
|
||||
changed by one character. The same is true of a picture: the sentence keeps the
|
||||
Markdown that points at it. Typesetting happens when the paper is read, in
|
||||
`src/utils/rich.ts`, which splits a sentence into text, formulas and images,
|
||||
hands the formulas to KaTeX and escapes everything else.
|
||||
|
||||
Four delimiters are recognised, because a writer's habit decides which they use:
|
||||
`$$…$$` and `\[…\]` for display, `$…$` and `\(…\)` for inline. An unmatched
|
||||
`$` is left alone rather than swallowing the rest of the paragraph.
|
||||
|
||||
Three rules are worth knowing when reading the renderer:
|
||||
Four rules are worth knowing when reading the renderer:
|
||||
|
||||
- **A display formula is a block.** It takes its own line whether or not the
|
||||
sentence asked for a break, because that is what "display" means.
|
||||
@@ -723,6 +794,14 @@ Three rules are worth knowing when reading the renderer:
|
||||
through `v-html`, and KaTeX runs with `trust` off, so a sentence cannot inject
|
||||
markup.
|
||||
|
||||
An image is the one thing the renderer does *not* build inside that HTML string.
|
||||
A figure is printed by `PaperParagraph` as a real `<img>` — so it can carry the
|
||||
writer's size and be opened at full resolution by a click — and `figureOf()`
|
||||
decides whether a sentence is a figure: it is one when the sentence holds nothing
|
||||
but a picture and whitespace. The reader's click is handled once, on the
|
||||
paragraph body, because inline pictures arrive through `v-html`, where no
|
||||
listener can be bound to them from a template.
|
||||
|
||||
### The paper view
|
||||
|
||||
`PapersView` is the library; `papers/PaperDetailView` is the writing surface.
|
||||
@@ -780,11 +859,12 @@ in correctly.
|
||||
paper-doc/
|
||||
├── backend/ # FastAPI application
|
||||
│ ├── app/
|
||||
│ │ ├── api/routes/ # route handlers (health, papers, references,
|
||||
│ │ ├── api/routes/ # route handlers (health, images, papers, references,
|
||||
│ │ │ # reference_tags, templates, template_title)
|
||||
│ │ ├── citation_styles/ # how a reference prints: springer.py, and the
|
||||
│ │ │ # registry that names the styles
|
||||
│ │ ├── core/ # settings and configuration
|
||||
│ │ ├── core/ # settings, and the object store (MinIO) the
|
||||
│ │ │ # images a paper embeds are kept in
|
||||
│ │ ├── crud/ # data-access helpers
|
||||
│ │ ├── db/ # engine, session, declarative base
|
||||
│ │ ├── mcp/ # MCP server: tools, specs, transports, self-check
|
||||
@@ -795,6 +875,7 @@ paper-doc/
|
||||
│ ├── scripts/smoke_papers.py # end-to-end check of the writing loop
|
||||
│ ├── scripts/smoke_references.py # end-to-end check of the reference library
|
||||
│ │ # and its tags
|
||||
│ ├── scripts/smoke_images.py # end-to-end check of upload, serve and refusal
|
||||
│ ├── scripts/check_citation_styles.py # the formatter, one entry per type
|
||||
│ │ # (no server, no database)
|
||||
│ ├── scripts/mcp_server.py # MCP entry point (stdio / http)
|
||||
@@ -811,7 +892,8 @@ paper-doc/
|
||||
│ │ ├── stores/ # pinia stores (UI prefs persisted, the paper and
|
||||
│ │ │ # tag lists not)
|
||||
│ │ ├── styles/ # global reset and the shell viewport contract
|
||||
│ │ ├── utils/ # formatting helpers
|
||||
│ │ ├── utils/ # formatting helpers, and rich.ts — the reader for
|
||||
│ │ │ # a sentence's LaTeX and its images
|
||||
│ │ └── views/ # route-level components (papers/, references/,
|
||||
│ │ # templates/)
|
||||
│ ├── package.json
|
||||
@@ -832,6 +914,8 @@ paper-doc/
|
||||
- Python 3.10+ with `venv`
|
||||
- Node.js 18+ with `pnpm`
|
||||
- Network access to the TiDB instance (local development uses the NodePort)
|
||||
- *Optional:* a MinIO (or any S3-compatible) endpoint, for the images a paper
|
||||
embeds. Without one, everything still works except uploading pictures.
|
||||
|
||||
**Backend**
|
||||
|
||||
@@ -839,7 +923,8 @@ paper-doc/
|
||||
cd backend
|
||||
python3 -m venv .venv && source .venv/bin/activate
|
||||
pip install -r requirements.txt
|
||||
cp .env.example .env # then fill in the database credentials
|
||||
cp .env.example .env # then fill in the database credentials, and the
|
||||
# MINIO_* ones if the paper is to hold images
|
||||
uvicorn app.main:app --reload --port 8000
|
||||
```
|
||||
|
||||
|
||||
Reference in New Issue
Block a user