# Chess lesson links

Turn a chess explanation into one link to https://rookoo.app. The link opens a board that steps through the moves with ← and →. Each step shows your explanation, coloured arrows, highlighted squares and notes pinned to pieces.

Humans: https://rookoo.app/#lesson has example lessons and the ones they opened before.

## The link

```
https://rookoo.app/#lesson/<encoded PGN>
```

Everything after # stays out of the request for the page, so the only limit is the browser's, over 1 MB. Keep links under about 8,000 characters: they are quicker to write and less likely to break.

## Write the lesson as PGN

Standard PGN, read leniently:

- Headers come first and are all optional: [Title "..."], [FEN "..."] to start from a position, [Orientation "black"] to show the board from Black's side, [White "..."] and [Black "..."] to name the sides.
- Moves are SAN, such as Nf3, exd5, O-O or e8=Q. Move numbers are optional and not checked. Every move must be legal. The lesson stops at the first illegal move and the page says which move and position failed.
- A `{comment}` after a move is the explanation shown at that move. A comment before the first move is shown on the starting position.
- `( ... )` is a variation: an alternative to the last move before it, even with pauses in between. Variations can nest. The arrow keys follow the main line; each variation is offered by its name at the move it replaces, for the reader to explore. Start a variation at the move where it differs: two lines that begin with the same move are one variation, with the other as a variation of the move where they part.
- `[%line Best]` in a comment names the line the comment is in, shown where the line is offered and at each of its steps. Name lines for what they are, in a few words with no moves, such as Game for the moves a game played, Best, The threat or If Black takes. A comment before the first move names the main line.
- `--` is a pause: a new step on the same position where nothing moves. Use pauses to explain one position over several steps, or to show a position with no moves at all.
- A glyph after a move (!, ?, !!, ??, !?, ?!, or $1 to $6) shows with the move. !!, !, ?!, ? and ?? also draw a badge on the board.

## Draw on the board

Write these commands inside a comment. They apply only to the step where they are written, so repeat them at every step that needs them.

- `[%cal Ge2e4,Rd8d1]` draws arrows: a colour letter, then the from and to squares.
- `[%csl Gf3,Rd5]` highlights squares.
- `[%note f3 Pinned to the queen]` pins a numbered note to the piece or square on f3 and lists it under the explanation. Write one square per note. The text ends at ].

Colours: G green for good moves and plans, R red for threats and weaknesses, Y yellow for key squares, B blue for alternatives.

Square names in an explanation, such as e4, Nf3 or exd5, light up their square when the reader hovers them. Write `**bold**` for bold text.

## Encode the link

Turn the PGN into the part after #lesson/:

- space → _
- line break → %0A
- ( → %28 and ) → %29
- " → %22, % → %25, _ → %5F, < → %3C, > → %3E. The % opening `[%cal`, `[%csl`, `[%note` and `[%line` stays as written.
- Leave everything else as written, including + # ! ? [ ] { } , : and /.
- Write plain ASCII: - rather than an em dash, ' rather than a curly quote.

Standard percent-encoding, such as JavaScript's encodeURIComponent, also works. It is just longer. It writes a space as %20, and a link with %20 in it reads _ as an underscore rather than a space, so do not mix the two forms. An encoded link has no spaces or parentheses, so it is safe as a bare URL and inside a Markdown link: `[Open the lesson](URL)`.

## Example

```
[Title "Legal's trap"]
{A pin only holds while the pinned piece matters. Watch White break this one by offering the queen.}
1. e4 e5 2. Nf3 d6 3. Bc4 Bg4 {Black pins the knight on f3 to the queen on d1. [%cal Rg4d1] [%csl Rf3]}
4. Nc3 g6?! {Too slow. Black spends a move on the kingside while f7 is weak. [%note f7 Only the king defends f7] [%cal Gc4f7]}
5. Nxe5! {White ignores the pin. The knight hits f7 together with the bishop, and the queen on d1 is left hanging. [%cal Ge5f7,Gc4f7,Rg4d1] [%csl Rf7]}
5... Bxd1?? {Greed. Taking the queen allows mate in two.}
(5... dxe5 {[%line Better] The calm answer.} 6. Qxg4 {White takes the bishop back and is a pawn up. [%csl Gg4]})
6. Bxf7+ Ke7 {Forced: d7 is covered by the knight on e5. [%csl Re7] [%cal Ge5d7]}
7. Nd5# {Legal's mate. Three minor pieces beat a queen because every flight square is covered. [%cal Gd5e7] [%csl Re7] [%note d5 Gives check and covers f6 and c7] [%note f7 Covers e8 and e6] [%note e5 Covers d7]}
```

Encoded:

```
https://rookoo.app/#lesson/[Title_%22Legal's_trap%22]%0A{A_pin_only_holds_while_the_pinned_piece_matters._Watch_White_break_this_one_by_offering_the_queen.}%0A1._e4_e5_2._Nf3_d6_3._Bc4_Bg4_{Black_pins_the_knight_on_f3_to_the_queen_on_d1._[%cal_Rg4d1]_[%csl_Rf3]}%0A4._Nc3_g6?!_{Too_slow._Black_spends_a_move_on_the_kingside_while_f7_is_weak._[%note_f7_Only_the_king_defends_f7]_[%cal_Gc4f7]}%0A5._Nxe5!_{White_ignores_the_pin._The_knight_hits_f7_together_with_the_bishop,_and_the_queen_on_d1_is_left_hanging._[%cal_Ge5f7,Gc4f7,Rg4d1]_[%csl_Rf7]}%0A5..._Bxd1??_{Greed._Taking_the_queen_allows_mate_in_two.}%0A%285..._dxe5_{[%line_Better]_The_calm_answer.}_6._Qxg4_{White_takes_the_bishop_back_and_is_a_pawn_up._[%csl_Gg4]}%29%0A6._Bxf7+_Ke7_{Forced:_d7_is_covered_by_the_knight_on_e5._[%csl_Re7]_[%cal_Ge5d7]}%0A7._Nd5#_{Legal's_mate._Three_minor_pieces_beat_a_queen_because_every_flight_square_is_covered._[%cal_Gd5e7]_[%csl_Re7]_[%note_d5_Gives_check_and_covers_f6_and_c7]_[%note_f7_Covers_e8_and_e6]_[%note_e5_Covers_d7]}
```

## Checklist

1. Play every move through from the position before it. Most broken lessons have an illegal move deep in a line.
2. Give each step one idea in one to four sentences.
3. End each line on the move that makes its point. Every move is a step to click through, so leave off moves with nothing left to show.
4. Repeat arrows, highlights and notes at every step that needs them.
5. Name every variation with `[%line]`, and the main line too when it is a game.
6. Encode, then give the link.