feat(library): write essays in the app — editor, full Markdown, and a writing guide - #121
Merged
Merged
Conversation
…Markdown
The Submit page gets an essay editor, and essays get all of Markdown.
Editor (library-ui.js, essayEditor):
- Write / Split / Preview, Obsidian's split: the Markdown beside the page
it makes, scrolled together; Ctrl/Cmd+E toggles reading.
- "Open .md file…" or a file dropped on the editor loads an essay already
written (Markdown or plain text, up to 1 MB); "Save as .md" writes it
back out; replacing a draft can be undone.
- The preview is the real renderer with this machine's own facts, its
figures drawn in the worker, [[links]] checked against the index, and
the warnings the PR check would give listed underneath.
- Drafts are kept per machine in localStorage; an author updating their
entry starts from its published essay.
Markdown (article.js, now on markdown-it):
- CommonMark and GFM (tables, task lists, strikethrough, autolinks),
footnotes, definition lists, ==mark==, ~sub~, ^sup^, smart quotes;
Obsidian's > [!note] callouts (foldable) and [[id|text]] links;
YAML front matter dropped; the shallowest heading becomes an h2.
- Math, {{facts}} and ::: figures are plugins; $5 and $10 is not math.
- Safety stays the renderer's: links must be http(s), mailto, # or lib:,
images https; raw HTML only as bare allow-listed tags; balanceHtml
keeps an author's unclosed or stray tags inside the essay.
- Loaded lazily in the app (its own ~120 KB chunk).
Transport:
- The essay rides inside the submitted document (meta.library.essay), so
it shares the machine's compressed link instead of the issue URL.
- issue-to-entry.mjs writes it beside the machine as .md and strips it
from the machine file; the form's own Essay field (last, so headings in
an essay cannot end it early) wins for hand-filled forms; an update with
no essay keeps the published one; one past 60,000 characters is refused.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01L8hKpV2hiVoJMZ9f6X4Zwu
…site
js/library/essay-guide.md is the one text: everything an essay can hold,
written in the essay format itself. Every ```example block is shown as its
source beside what the real renderer makes of it, with a real machine's
facts and figures (BB(2)), so the guide cannot describe what the renderer
does not do.
- The editor's Guide button shows it in the preview's place, beside the
Markdown being written (loaded lazily with ?raw).
- The website builds it into /writing/, linked from Submit and the footer.
- tests/essay.test.js holds it to the code: it renders with no warnings,
and it names every fact, figure, callout kind and allowed HTML tag, and
the real limits. A feature added without its documentation fails there.
Two renderer fixes the guide turned up:
- A dollar sign that is not math ("$5 and $10", or a written \$) gets an
element of its own, so KaTeX's auto-render cannot pair it into math
after the page is drawn. The parser's price rule was not enough alone.
- A #heading link now carries the id prefix, so it reaches the heading in
the app too; and a footnote shown as `[^x]` in code is no longer
reported as a missing note.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01L8hKpV2hiVoJMZ9f6X4Zwu
|
You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Essays (added in thethinkmachine/AutomataStudio#119) could so far only arrive by pull request, in a small hand-written Markdown dialect. This lets authors write them in the app, supports all of Markdown, and documents it all.
Two commits:
7065ec9Essay editor, full Markdown, and sending essays from the app9598fd7A guide to writing an essay, in the app and on the websiteThe editor (Submit a machine)
Ctrl/⌘ Etoggles between writing and reading.{{facts}}from this machine's own analysis, figures drawn in the worker,[[links]]checked against the index, and the warnings the PR check would give listed underneath. A step count past the dialog's run budget shows as a pending…, filled in by CI.Full Markdown (
js/library/article.js, now on markdown-it)==mark==,~sub~,^sup^and smart quotes.> [!note] Titlecallouts (foldable with-/+),[[id|text]]links, YAML front matter dropped, and the shallowest heading becomes an h2.{{facts}}and:::figures are plugins. A price like$5 and $10is not math: the parser uses Pandoc's rule, and each non-math$gets its own element so KaTeX's auto-render can't pair it either.\$is a literal dollar.#orlib:, and images must be https. Raw HTML is allowed only as bare, allow-listed tags with no attributes; anything else is escaped and reported.balanceHtmlkeeps an author's unclosed or stray tags inside the essay, because the website writes the essay into the page's own markup.#headinglinks carry the id prefix, so they work in the app too.essay.jsno longer imports the renderer; the build's check moved toessay-check.js.Sending an essay
meta.library.essay), sharing the machine's compressed share link, or the clipboard when that is too long, as for large machines.issue-to-entry.mjswrites it beside the machine as.md(the submission workflow already commitsmachines/**) and strips it from the machine file.### Licenceheading inside an essay can't end it early.The writing guide (
js/library/essay-guide.md)```exampleblocks is shown as source beside what the real renderer makes of it, using BB(2)'s real facts and figures.?raw), and built by the website into/writing/, linked from Submit and the footer.Testing
npm test: 2611 pass, 1 skipped (the test that needs a locally built library).tests/essay.test.js(21 tests): every Markdown feature, the security rules (<script>, event handlers,javascript:/data:links, non-https images, disallowed HTML), tag balancing, prices vs math, footnotes, id and anchor prefixing, figure bounds, and the guide checks above.tests/library.test.js: the CI writing the essay out of a submission (from the document, from the form field, update without essay, too long), the draft store, the file reader, the editor (file picker, front matter, facts, links, callout, warnings, undo, draft restore), update prefill, the Guide pane, and the/writing/page.vite buildsucceeds. markdown-it (article-*.js) and the guide (essay-guide-*.js) are their own lazy chunks..mdthrough the picker, used split, preview,Ctrl+Eand the Guide pane, and viewed/writing/in light, dark and at phone width.Merge order
Merge this before thethinkmachine/automata-library#5. The library's CI runs this repo's
main, so the library's new Essay form field is only read once this has landed.🤖 Generated with Claude Code
https://claude.ai/code/session_01L8hKpV2hiVoJMZ9f6X4Zwu