Skip to content

Commit 66d1616

Browse files
PurpleReverieclaude
andcommitted
Add markdown-sample example
End-to-end demo of @reactwright/markdown. sample.md is a 2-page essay with frontmatter (title, author, template, references), sections, paragraphs, emphasis, an ordered list, a blockquote, two inline citations, and a footnote. The package's mockup script invokes the reactwright-md CLI and writes HTML+PDF into build/mockups. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
1 parent c0b1bec commit 66d1616

3 files changed

Lines changed: 139 additions & 0 deletions

File tree

examples/markdown-sample/README.md

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
# markdown-sample
2+
3+
End-to-end demo of the `@reactwright/markdown` workflow.
4+
5+
`sample.md` is a short essay with YAML frontmatter (title, author,
6+
template, references). Run:
7+
8+
```sh
9+
pnpm mockup
10+
```
11+
12+
The script invokes the `reactwright-md` CLI on `sample.md` and writes
13+
`markdown-sample.html` + `markdown-sample.pdf` into `build/mockups/`.
14+
The frontmatter `template: essay` selects `@reactwright/template-essay`;
15+
override with `--template=ieee` or `--template=report` on the command
16+
line if you want to see the same content wrapped in a different
17+
template.
18+
19+
Workflow:
20+
21+
1. The CLI reads `sample.md` and parses it via `markdownToReactwright`,
22+
producing a `<document>` React element plus a frontmatter object.
23+
2. The frontmatter `template` field selects the Reactwright template
24+
package; the CLI dynamically imports its `Template` export.
25+
3. Content + template flow through the engine's existing render
26+
pipeline (content IR → resolve → HTML → PDF).
Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
{
2+
"name": "@example/markdown-sample",
3+
"version": "0.0.0",
4+
"private": true,
5+
"type": "module",
6+
"scripts": {
7+
"mockup": "PUPPETEER_EXECUTABLE_PATH=\"${PUPPETEER_EXECUTABLE_PATH:-/Applications/Google Chrome.app/Contents/MacOS/Google Chrome}\" node --import tsx ../../packages/markdown/src/cli.ts ./sample.md --output ../../build/mockups/markdown-sample.pdf"
8+
},
9+
"devDependencies": {
10+
"@reactwright/markdown": "workspace:*",
11+
"@reactwright/template-essay": "workspace:*",
12+
"@types/node": "^22.15.18",
13+
"react": "^19.1.0",
14+
"reactwright": "workspace:*",
15+
"tsx": "^4.19.2",
16+
"typescript": "^5.8.3"
17+
}
18+
}

examples/markdown-sample/sample.md

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
---
2+
title: On the Discipline of Saying Less
3+
author: J. Wren Harrow
4+
template: essay
5+
references:
6+
- key: aristotle-poetics
7+
text: "Aristotle. *Poetics*, trans. S. H. Butcher. Macmillan, 1902."
8+
- key: orwell1946
9+
text: "Orwell, G. 'Politics and the English Language.' *Horizon*, vol. 13, no. 76, 1946, pp. 252-265."
10+
- key: strunk-white
11+
text: "Strunk, W. and White, E. B. *The Elements of Style*, 4th ed., Allyn and Bacon, 2000."
12+
---
13+
14+
# The Argument
15+
16+
The longer a sentence runs, the more it must justify itself. This is
17+
not a rule of taste so much as a rule of attention: a reader's gaze
18+
is finite, and every clause that fails to earn its presence borrows
19+
from the next one's budget. *Brevity* is therefore less a stylistic
20+
preference than an act of fiscal honesty — a writer who insists on
21+
length must, sooner or later, pay for it.
22+
23+
Critics have framed this case for a long time. Aristotle warned
24+
against speeches that "weary the hearer" [@aristotle-poetics], and
25+
Orwell, two and a half millennia later, called for the deletion of
26+
"every word that can be cut" [@orwell1946]. The principle outlasts
27+
its eras because it concerns a constraint of mind rather than a
28+
fashion of prose.
29+
30+
## A Working Definition
31+
32+
Brevity, as used here, is not the same as shortness. A short sentence
33+
can be bloated; a long sentence can be lean. The relevant quantity is
34+
the ratio of information to syllables. Strunk and White, in a book
35+
that is itself an example of the discipline it preaches, gave the
36+
matter the cleanest formulation: "Omit needless words" [@strunk-white].
37+
38+
The phrase is famously self-demonstrating. Three words; one
39+
instruction; no qualifications. A writer who internalises this
40+
sentence has already done most of the work the rest of the book
41+
proposes.
42+
43+
> Vigorous writing is concise. A sentence should contain no
44+
> unnecessary words, a paragraph no unnecessary sentences, for the
45+
> same reason that a drawing should have no unnecessary lines and a
46+
> machine no unnecessary parts.
47+
48+
The metaphor is mechanical, and the choice matters: a machine with
49+
extra parts is not merely uglier but less reliable. Prose, the
50+
analogy implies, has the same property. Each unjustified word is a
51+
small risk of failure.
52+
53+
# Three Tests
54+
55+
A practical writer needs more than aphorism. Here are three tests,
56+
applied at the level of the sentence, that approximate the
57+
discipline:
58+
59+
1. **The strike test.** Read the sentence aloud, then strike each
60+
word in turn and re-read. If the sentence survives the loss, the
61+
word was not earning its place.
62+
2. **The reorder test.** Swap two adjacent clauses. If the meaning
63+
is unchanged, the clauses were not arguing with each other; one
64+
is probably redundant.
65+
3. **The replace test.** Replace any abstract noun with a concrete
66+
one. If the sentence becomes clearer, the abstraction was a
67+
placeholder, not a thought.
68+
69+
None of these is infallible, but the three together catch most of
70+
the slack in ordinary prose. They cost a writer nothing but minutes,
71+
and they pay in clarity that no amount of revision-by-mood can
72+
reproduce.
73+
74+
# What Brevity Is Not
75+
76+
It bears repeating that brevity is not an aesthetic of austerity[^1].
77+
The writer who composes a paragraph by counting words rather than
78+
weighing them produces something stunted, not something taut. Hemingway
79+
is often cited as the patron saint of compression, but his sentences,
80+
read closely, are full of small luxuries — a rhythm here, a colour
81+
there. What they avoid is *unearned* expansion: the second adjective
82+
when the first will do, the qualifier that doubles back to soften an
83+
honest claim.
84+
85+
[^1]: The Spartan writers of the early twentieth century deserve
86+
better than they have received. A discipline practised without joy
87+
is not a discipline; it is a fear of being caught.
88+
89+
# Conclusion
90+
91+
The case for brevity is not that short prose is better than long
92+
prose. It is that prose which earns its length is better than prose
93+
which assumes the reader's patience. The difference is moral as much
94+
as it is stylistic: a writer who pays for their words respects the
95+
reader who reads them.

0 commit comments

Comments
 (0)