diff --git a/.gitignore b/.gitignore
index 7e83e25..aa885c9 100644
--- a/.gitignore
+++ b/.gitignore
@@ -15,6 +15,9 @@ backend/.env
# --- Node / frontend ---
node_modules/
+# pnpm keeps a content-addressed store; when it lands here rather than in the
+# home directory it is build output, not source.
+.pnpm-store/
frontend/dist/
frontend/dist-ssr/
*.tsbuildinfo
diff --git a/backend/alembic/versions/f8c2d5a73b91_add_line_break_before.py b/backend/alembic/versions/f8c2d5a73b91_add_line_break_before.py
new file mode 100644
index 0000000..f834481
--- /dev/null
+++ b/backend/alembic/versions/f8c2d5a73b91_add_line_break_before.py
@@ -0,0 +1,48 @@
+"""give a sentence the option to start a new line
+
+A paragraph is its sentences concatenated, which is right for prose and wrong
+for the things a paper also puts inside a paragraph: a display formula, a list
+of items, an author line. Those want a line break between them, and until now
+there was nowhere to say so — text pasted with newlines was folded onto one line
+on purpose, so the writer had no way to ask for one.
+
+So the sentence carries the request: ``line_break_before`` prints a break before
+this sentence and nothing else. It is a property of the sentence rather than a
+character in its content because the content is a sentence — folding whitespace
+is what keeps it one — and because a break the writer cannot see cannot be
+removed.
+
+Existing rows default to 0: today's documents render exactly as they did.
+
+Revision ID: f8c2d5a73b91
+Revises: 063f6def01fa
+Create Date: 2026-09-22
+
+"""
+
+from collections.abc import Sequence
+
+import sqlalchemy as sa
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision: str = "f8c2d5a73b91"
+down_revision: str | None = "063f6def01fa"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+ op.add_column(
+ "paper_sentence",
+ sa.Column(
+ "line_break_before",
+ sa.Boolean(),
+ server_default=sa.text("0"),
+ nullable=False,
+ ),
+ )
+
+
+def downgrade() -> None:
+ op.drop_column("paper_sentence", "line_break_before")
diff --git a/backend/app/crud/paper.py b/backend/app/crud/paper.py
index 7f959cf..d7b0740 100644
--- a/backend/app/crud/paper.py
+++ b/backend/app/crud/paper.py
@@ -419,7 +419,13 @@ def build_document(db: Session, paper: Paper) -> PaperDocumentRead:
# than by whoever prints them, so a reader, an export and a preview
# cannot each invent their own spacing.
for earlier, later in zip(sentences, sentences[1:]):
- later.separator_before = sentence_separator(earlier.content, later.content)
+ later.separator_before = (
+ ""
+ if later.line_break_before
+ # A line break already separates the two, and printing a space
+ # as well would indent the new line by one blank.
+ else sentence_separator(earlier.content, later.content)
+ )
paragraph = ParagraphRead(
paper_template_filed_sort=position,
@@ -678,6 +684,7 @@ def replace_paragraph(
paper_template_filed_sort=target,
sort=item.sort if item.sort is not None else base + offset,
content=item.content,
+ line_break_before=item.line_break_before,
citations=_build_citations(item.citations),
)
)
@@ -700,6 +707,7 @@ def append_sentence(db: Session, paper: Paper, data: SentenceCreate) -> PaperSen
paper_template_filed_sort=data.paper_template_filed_sort,
sort=sort,
content=data.content,
+ line_break_before=data.line_break_before,
citations=_build_citations(data.citations),
)
db.add(sentence)
@@ -729,6 +737,8 @@ def update_sentence(
sentence.paper_template_filed_sort = data.paper_template_filed_sort
if data.content is not None:
sentence.content = data.content
+ if data.line_break_before is not None:
+ sentence.line_break_before = data.line_break_before
if data.citations is not None:
sentence.citations.clear()
db.flush()
diff --git a/backend/app/models/paper_sentence.py b/backend/app/models/paper_sentence.py
index d193adb..d83c9da 100644
--- a/backend/app/models/paper_sentence.py
+++ b/backend/app/models/paper_sentence.py
@@ -31,7 +31,7 @@ is assembled on read from the paper's template plus these rows. See
from typing import TYPE_CHECKING
-from sqlalchemy import ForeignKey, Index, Integer, Text
+from sqlalchemy import Boolean, ForeignKey, Index, Integer, Text, text
from sqlalchemy.orm import Mapped, mapped_column, relationship
from app.db.base import Base
@@ -86,6 +86,21 @@ class PaperSentence(TimestampMixin, Base):
#: placeholder and renders as a blank line rather than disappearing.
content: Mapped[str] = mapped_column(Text, nullable=False, default="")
+ #: Print a line break before this sentence.
+ #:
+ #: A paragraph is its sentences concatenated, which is right for prose and
+ #: wrong for what else a paper puts inside one: a display formula, a list of
+ #: items, an author line. The break is a flag rather than a newline in
+ #: ``content`` for two reasons — content folds its whitespace so a sentence
+ #: really is one line, and a break hidden in a string is a break the writer
+ #: cannot see or remove.
+ line_break_before: Mapped[bool] = mapped_column(
+ Boolean,
+ nullable=False,
+ default=False,
+ server_default=text("0"),
+ )
+
paper: Mapped["Paper"] = relationship(back_populates="sentences")
#: References quoted by this sentence, in citation order. Eager-loaded
diff --git a/backend/app/schemas/paper.py b/backend/app/schemas/paper.py
index 3cca11b..33bb5c2 100644
--- a/backend/app/schemas/paper.py
+++ b/backend/app/schemas/paper.py
@@ -97,6 +97,8 @@ class SentenceInput(BaseModel):
sort: int | None = Field(default=None, ge=-1_000_000, le=1_000_000)
content: str = ""
+ #: Start a new line at this sentence rather than running on from the last.
+ line_break_before: bool = False
citations: list[CitationInput] = Field(default_factory=list)
@field_validator("content")
@@ -135,6 +137,7 @@ class SentenceUpdate(BaseModel):
default=None, ge=-1_000_000, le=1_000_000
)
content: str | None = None
+ line_break_before: bool | None = None
citations: list[CitationInput] | None = None
@field_validator("content")
@@ -168,6 +171,9 @@ class SentenceRead(BaseModel):
paper_template_filed_sort: int
sort: int
content: str
+ #: Whether a line break prints before this sentence. See
+ #: :attr:`app.models.paper_sentence.PaperSentence.line_break_before`.
+ line_break_before: bool
citations: list[CitationRead]
#: Text to print before this sentence when the paragraph is put back
#: together — ``""`` or a single space, never anything else. Derived on
diff --git a/backend/scripts/smoke_papers.py b/backend/scripts/smoke_papers.py
index 066d2a3..7b03b37 100644
--- a/backend/scripts/smoke_papers.py
+++ b/backend/scripts/smoke_papers.py
@@ -267,7 +267,42 @@ def main() -> int:
# Clear it again so the counts asserted below stay meaningful.
call("PUT", f"/papers/{paper['id']}/paragraphs/{second_sort}", {"sentences": []})
- print("8. reject a citation with no quote")
+ print("8. a sentence can ask for a line break")
+ # The flag replaces the separator rather than adding to it: a break
+ # already separates the two, and a space as well would indent the new
+ # line by one blank.
+ broken = call(
+ "PUT",
+ f"/papers/{paper['id']}/paragraphs/{second_sort}",
+ {
+ "sentences": [
+ {"content": "连排的第一句。"},
+ {"content": "另起一行的一句。", "line_break_before": True},
+ {"content": "English runs on.", "line_break_before": True},
+ ]
+ },
+ )
+ paragraph_breaks = next(
+ p
+ for p in broken["paragraphs"]
+ if p["paper_template_filed_sort"] == second_sort
+ )
+ check(
+ "the flag is stored per sentence",
+ [s["line_break_before"] for s in paragraph_breaks["sentences"]]
+ == [False, True, True],
+ str([s["line_break_before"] for s in paragraph_breaks["sentences"]]),
+ )
+ check(
+ "it also survives a read back",
+ all(
+ s["line_break_before"] is False or s["separator_before"] == ""
+ for s in paragraph_breaks["sentences"]
+ ),
+ )
+ call("PUT", f"/papers/{paper['id']}/paragraphs/{second_sort}", {"sentences": []})
+
+ print("9. reject a citation with no quote")
bad = call(
"PUT",
f"/papers/{paper['id']}/paragraphs/{first_sort}",
@@ -285,7 +320,7 @@ def main() -> int:
)
check("citation without content refused", "detail" in bad)
- print("9. a sentence with no paragraph in the template survives a switch")
+ print("10. a sentence with no paragraph in the template survives a switch")
# A position neither template defines, so the check means the same
# thing before and after the switch below.
orphan_sort = (
@@ -313,7 +348,7 @@ def main() -> int:
p for p in document["paragraphs"] if p["paper_template_filed_sort"] == orphan_sort
)["name"] is None)
- print("10. switch the template")
+ print("11. switch the template")
switched = call("PATCH", f"/papers/{paper['id']}", {"template_id": narrow["id"]})
check("template changed", switched["template_id"] == narrow["id"])
document = call("GET", f"/papers/{paper['id']}/document")
@@ -343,7 +378,7 @@ def main() -> int:
),
)
- print("11. move one paragraph onto another position")
+ print("12. move one paragraph onto another position")
document = call(
"PUT",
f"/papers/{paper['id']}/paragraphs/{orphan_sort}",
@@ -358,18 +393,18 @@ def main() -> int:
all(p["paper_template_filed_sort"] != orphan_sort for p in document["paragraphs"]),
)
- print("12. paper list reports progress")
+ print("13. paper list reports progress")
listing = call("GET", f"/papers?keyword=冒烟&status=writing")
check("found by keyword and status", listing["total"] == 1, str(listing["total"]))
row = listing["items"][0]
check("paragraph count", row["paragraph_count"] == 1, str(row["paragraph_count"]))
check("sentence count", row["sentence_count"] == 3, str(row["sentence_count"]))
- print("13. a template in use cannot be deleted")
+ print("14. a template in use cannot be deleted")
conflict = call("DELETE", f"/templates/{narrow['id']}", expect=409)
check("template delete refused", "正被论文使用" in conflict["detail"], conflict["detail"])
- print("14. single sentence edit and delete")
+ print("15. single sentence edit and delete")
sentence_id = target["sentences"][0]["id"]
updated = call(
"PATCH",
@@ -385,7 +420,7 @@ def main() -> int:
sum(len(p["sentences"]) for p in document["paragraphs"]) == 2,
)
- print("15. a paper with no template still works")
+ print("16. a paper with no template still works")
bare = call(
"POST",
"/papers",
@@ -408,7 +443,7 @@ def main() -> int:
call("DELETE", f"/papers/{bare['id']}", expect=204)
created_papers.remove(bare["id"])
- print("16. delete the paper")
+ print("17. delete the paper")
call("DELETE", f"/papers/{paper['id']}", expect=204)
created_papers.clear()
for reference_id in created_references:
diff --git a/docs/OVERVIEW.md b/docs/OVERVIEW.md
index ed7bfda..434562e 100644
--- a/docs/OVERVIEW.md
+++ b/docs/OVERVIEW.md
@@ -306,6 +306,23 @@ stop (`。`) and nothing else — deliberately conservative: an English abstract
survives that migration as a single row rather than being cut at the first
`et al.`, and one long line is a line the writer can split by hand.
+#### A line break is asked for, never guessed
+
+A paragraph is its sentences run together — that is the model. Everything a
+paper also puts *inside* a paragraph that is not prose (a display formula, a
+list of items, an author line) therefore needs a way to say "start a new line
+here", and that is `paper_sentence.line_break_before`.
+
+It is a flag rather than a newline inside `content` for two reasons. Content
+folds its whitespace, deliberately, so that a sentence really is one line and a
+pasted newline cannot split one in half; and a break buried in a string is a
+break nobody can see, count or remove. A flag prints a ` ` and is visible in
+the editor as a checkbox on the sentence's row.
+
+A break also **replaces** the separator rather than adding to it: the new line
+already separates the two sentences, and a space as well would indent the line
+by one blank.
+
#### What goes at the seam
A paragraph is printed by concatenating its sentences in `sort` order, so the
@@ -662,6 +679,29 @@ are not lists (the paper document) keep scrolling normally.
| `/references` | reference table + CRUD (`?tag=` filters, `?new=1` opens the create dialog) | `references` |
| `/references/tags` | tag library + CRUD (the UI label is 标签管理) | `references` |
+### Sentences are stored as LaTeX and typeset on read
+
+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.
+
+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.
+
+Two 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 — so the
+ formulas in a paper sit centred on their own lines with no extra flagging.
+- **KaTeX never throws.** `throwOnError: false` renders a formula it cannot read
+ as its own source in red, so one typo shows itself instead of blanking the
+ paragraph the writer is looking at. Text segments are escaped before they go
+ through `v-html`, and KaTeX runs with `trust` off, so a sentence cannot inject
+ markup.
+
### The paper view
`PapersView` is the library; `papers/PaperDetailView` is the writing surface.
diff --git a/frontend/package.json b/frontend/package.json
index 16123b5..09160c2 100644
--- a/frontend/package.json
+++ b/frontend/package.json
@@ -14,6 +14,7 @@
"@element-plus/icons-vue": "^2.3.2",
"axios": "^1.20.0",
"element-plus": "^2.14.5",
+ "katex": "^0.18.7",
"pinia": "^4.0.2",
"pinia-plugin-persistedstate": "^4.7.1",
"vue": "^3.5.40",
diff --git a/frontend/pnpm-lock.yaml b/frontend/pnpm-lock.yaml
index 6052872..142035a 100644
--- a/frontend/pnpm-lock.yaml
+++ b/frontend/pnpm-lock.yaml
@@ -17,6 +17,9 @@ importers:
element-plus:
specifier: ^2.14.5
version: 2.14.5(vue@3.5.42(typescript@6.0.3))
+ katex:
+ specifier: ^0.18.7
+ version: 0.18.7
pinia:
specifier: ^4.0.2
version: 4.0.3(@vue/devtools-api@8.2.1)(typescript@6.0.3)(vue@3.5.42(typescript@6.0.3))
@@ -543,6 +546,10 @@ packages:
resolution: {integrity: sha512-FQN4MRfuJeHf7cBbBMJFXhKSDq+2kAArBlmRBvcvFE5BB1HZKXtSFASDhdlz9zOYwxh8lDdnvmMOe/+5cdoEdg==}
engines: {node: '>= 0.8'}
+ commander@15.0.0:
+ resolution: {integrity: sha512-z67u4ZhzCL/Tydu1lJARtEZYWbWaN7oYLHbsuzocr6y4N6WZAagG3RQ4FW61V1/0+jImpj293XfrcYnd1qxtPg==}
+ engines: {node: '>=22.12.0'}
+
confbox@0.1.8:
resolution: {integrity: sha512-RMtmw0iFkeR4YV+fUOSucriAQNb9g8zFR52MWCtl+cCZOFRNL6zeB395vPzFhEjjn4fMxXudmELnl/KF/WrK6w==}
@@ -749,6 +756,10 @@ packages:
engines: {node: '>=6'}
hasBin: true
+ katex@0.18.7:
+ resolution: {integrity: sha512-h+UCwkZ+4Jz8WQ7MLGfj7UVFrRCizGb912fwF4luGdYsC5paYG1vx+jy+KRcC/XkpjGva/P7nAWuxNnPzRvzHw==}
+ hasBin: true
+
kolorist@1.8.0:
resolution: {integrity: sha512-Y+60/zizpJ3HRH8DCss+q95yr6145JXZo46OTpFvDZWLfRCE4qChOyk1b26nMaNpfHHgxagk9dXT5OP0Tfe+dQ==}
@@ -1761,6 +1772,8 @@ snapshots:
dependencies:
delayed-stream: 1.0.0
+ commander@15.0.0: {}
+
confbox@0.1.8: {}
confbox@0.2.4: {}
@@ -1936,6 +1949,10 @@ snapshots:
json5@2.2.3: {}
+ katex@0.18.7:
+ dependencies:
+ commander: 15.0.0
+
kolorist@1.8.0: {}
lightningcss-android-arm64@1.33.0:
diff --git a/frontend/src/api/papers.ts b/frontend/src/api/papers.ts
index e0f2dde..050ab1b 100644
--- a/frontend/src/api/papers.ts
+++ b/frontend/src/api/papers.ts
@@ -84,6 +84,14 @@ export interface Sentence {
/** Position inside that paragraph. */
sort: number
content: string
+ /**
+ * Whether a line break prints before this sentence.
+ *
+ * A paragraph is normally its sentences run together; this is how the writer
+ * asks for a new line — a display formula, a list of items, an author line —
+ * without splitting the paragraph in two.
+ */
+ line_break_before: boolean
citations: Citation[]
/**
* What to print before this sentence when the paragraph is put back
@@ -181,6 +189,8 @@ export interface CitationInput {
export interface SentenceInput {
sort?: number | null
content: string
+ /** Start a new line at this sentence. */
+ line_break_before?: boolean
citations: CitationInput[]
}
diff --git a/frontend/src/components/papers/PaperParagraph.vue b/frontend/src/components/papers/PaperParagraph.vue
index 0b67157..97d083d 100644
--- a/frontend/src/components/papers/PaperParagraph.vue
+++ b/frontend/src/components/papers/PaperParagraph.vue
@@ -27,6 +27,7 @@ import { Edit } from '@element-plus/icons-vue'
import type { PaperParagraph } from '@/api/papers'
import { PARAGRAPH_UNSET_LABEL, levelIndent } from '@/utils/format'
+import { escapeHtml, hasDisplayMath, renderRich } from '@/utils/math'
const props = defineProps<{
paragraph: PaperParagraph
@@ -49,10 +50,39 @@ const headingStyle = computed(() => {
/** Indentation follows the field's level, exactly as the template outline does. */
const headingIndent = computed(() => levelIndent(props.paragraph.level))
+/**
+ * Every sentence, prepared for printing.
+ *
+ * Typesetting happens here rather than in the template so it runs once per
+ * sentence instead of on every re-render, and so the line-break rule — a break
+ * replaces the separator, it does not add to it — is stated in one place.
+ */
+interface RenderedSentence {
+ sentence: PaperParagraph['sentences'][number]
+ /** The sentence as HTML: its separator escaped, its formulas typeset. */
+ html: string
+ /** A `$$ … $$` formula, which takes a line of its own by definition. */
+ display: boolean
+ /** The writer asked for a line break before this sentence. */
+ lineBreak: boolean
+}
+
+const rendered = computed(() =>
+ props.paragraph.sentences.map((sentence) => ({
+ sentence,
+ html:
+ escapeHtml(sentence.line_break_before ? '' : sentence.separator_before) +
+ renderRich(sentence.content),
+ display: hasDisplayMath(sentence.content),
+ lineBreak: sentence.line_break_before,
+ })),
+)
+
/** Whether anything has actually been written here. */
const hasContent = computed(() =>
- props.paragraph.sentences.some(
- (sentence) => sentence.content.trim().length > 0 || sentence.citations.length > 0,
+ rendered.value.some(
+ (item) =>
+ item.sentence.content.trim().length > 0 || item.sentence.citations.length > 0,
),
)
@@ -95,13 +125,22 @@ const anchor = computed(() => `paragraph-${props.paragraph.paper_template_filed_
-