Write an aside into a document from code, as the parser reads it

Open
#315 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
3/5
Estimated time
1-2 days
Newbie friendliness
64/100
Issue type
Feature
Clarity
Clearly specified
Activity status
Active
Tech stack
javascript, markdown
Domain
tooling

Research direction

Start in features/asides/, where the existing aside parser lives, and see how it recognises the alias mark, the optional style and topic parts, and the repeat mark on multi-line asides. Add a sibling writer module exported as reader/asides, following the API sketch in the issue, and use reader-authors' lib/markdown.js and its escapeLineStart only as a reference for escaping. Done is a round-trip test that parses writeAside output back to the same aside for every option, plus a check that no other line of the file changes apart from the front matter declareReviewer adds.

Written by the indexing model from the issue text.

Description

polish

Part of #68.

Today

Only people write asides. Code that wants to add one, such as a review copy taking a reviewer's notes (#68), a review sent back to reader (#69), or reader-margin committing a commenter's asides, has to spell the syntax out again. Then it drifts from the parser, as reader-authors' lib/markdown.js does every time the syntax changes (gh-305).

What to do

Add a writer next to the parser in features/asides/, exported as reader/asides:

let { src, alias } = declareReviewer(src, 'Maria');   // adds `reviewer à: Maria`, or finds her
src = writeAside(src, {
  line: 41,                // 0-based, as data-line counts
  alias,
  topics: ['c'],           // optional
  words: 'the lazy dog',   // optional: ~à[the lazy dog]
  style: 'circle',         // optional: {circle}
  reply: false,            // true writes ~~à in the thread under the line
  text: 'Which dog?\nAnd why lazy?',
});
  • Aliases. declareReviewer gives a new reviewer a character no alias in the file uses. It picks from accented letters (à á â ä …), then other scripts, and leaves ASCII to the writer's own reviewers and topics. reader already reads any single character as an alias.
  • Lines. An aside is written straight under its line, or under the asides already there. Every line of a several-line aside repeats its mark (gh-305), and a blank line in the text becomes the mark alone.
  • Escaping. What someone typed can't become anything but the aside's text. A line that would read as another block, a front-matter key, ---, a fence or raw HTML is escaped, as escapeLineStart does in reader-authors. So is text that starts with a box, [ ] or [x], written \[x]: straight after the aliases a box makes the aside a thread to resolve (gh-199), so a commenter could otherwise open or resolve a thread by typing it.

Done when

  • The parser reads whatever writeAside writes as the same aside: its line, who, topics, words, style and text. A test does this round trip for every option, and for text that tries to break out, or starts with a box.
  • Writing an aside changes no other line of the file, except the front matter declareReviewer adds to.

🤖 Generated with Claude Code

Dominant language
JavaScript
Stars
0
Forks
1
Avg merge
2d 4h
Merged PRs (30d)
26

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from jzheaux/reader

All issues in jzheaux/reader

Similar issues

More JavaScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.