README file from
GithubChessboard Viewer
This plugin adds the capability to visualize Chess FEN positions on an SVG chessboard directly in preview mode.
By design, this plugin is focused on visualization. It renders static SVG boards for FEN positions, supports experimental PGN rendering, and can optionally add interactive navigation controls for PGN diagrams. It is optimized for diagrams and HTML/PDF exports rather than full game analysis or editing.
If you want a more fully featured interactive chess plugin, I recommend Chesser.
How to use it
After you install the plugin, just write the FEN position representation inside a code block with the chessboard language.
Example
For example, something like this
```chessboard
fen: r2qrbk1/1bp2pp1/p2p1n1p/1p6/Pn1PP3/5N1P/1P1N1PP1/RBBQR1K1 b - - 2 17
annotations: Hf5 He5 Hd5 Ae1-e8/g Ab1-h7/g Ad4-d5
annotations: Hf6/g
```
will be rendered as in the following picture:
Change Board Orientation
Use the orientation command. It can be white (default) or black.
```chessboard
fen: r1bqkbnr/pppp1ppp/2n5/1B2p3/4P3/5N2/PPPP1PPP/RNBQK2R
orientation: black
```
Invalid Positions
Use the strict command to allow non-standard positions. This is useful for antichess or illustrating example positions.
```chessboard
fen: 8/8/8/8/8/8/8/kP6
strict: false
```
Annotations (Beta)
You can annotate your diagram with arrows, highlights and icons:
```chessboard
fen: r1bqkbnr/pppp1ppp/2n5/1B2p3/4P3/5N2/PPPP1PPP/RNBQK2R
annotations: Af8-b4 Hf8 Ha7/g !!f8 ??a7 ?e4 Fe8 !?d8
orientation: white
```
Annotation Syntax
The annotations are written in the annotations field, and you can use the following syntax:
A<square>-<square>, draws an arrow from the first square to the second square. E.g.,Af8-b4.H<square>, highlight a specific square. E.g.,Hf8. If you add/gor/ror/byou can highlight the square in green, red or blue.S<square>, draws a box around a square.C<square>, draws a circle around a square.Q<square>, draws a squircle around a square.!!<square>, adds a "brilliant move" icon to the specified square. E.g.,!!e5.??<square>, adds a "blunder" icon to the specified square. E.g.,??e5.?<square>, adds a "questionable move" icon to the specified square. E.g.,?e5.!<square>, adds an "excellent move" icon to the specified square. E.g.,!e5.!?<square>, adds an "okay move" icon to the specified square. E.g.,!?e5.F<square>, adds a "forced move" icon to the specified square. E.g.,Fe5.#B<square>, adds a black "checkmated" icon to the specified square. E.g.,#Be5.#W<square>, adds a white "checkmated" icon to the specified square. E.g.,#We5.
Note that the annotation syntax is beta and may change in the future. If you have suggestions, don't hesitate to open an issue.
Experimental: PGN
It is also possible to render games written in PGN. This is done by using the chessboard-pgn code block.
```chessboard-pgn
[Event "Casual Game"]
[Site "Berlin GER"]
[Date "1852.??.??"]
[EventDate "?"]
[Round "?"]
[Result "1-0"]
[White "Adolf Anderssen"]
[Black "Jean Dufresne"]
[ECO "C52"]
[WhiteElo "?"]
[BlackElo "?"]
[PlyCount "47"]
1.e4 e5 2.Nf3 Nc6 3.Bc4 Bc5 4.b4 Bxb4 5.c3 Ba5 6.d4 exd4 7.O-O
d3 8.Qb3 Qf6 9.e5 Qg6 10.Re1 Nge7 11.Ba3 b5 12.Qxb5 Rb8 13.Qa4
Bb6 14.Nbd2 Bb7 15.Ne4 Qf5 16.Bxd3 Qh5 17.Nf6+ gxf6 18.exf6
Rg8 19.Rad1 Qxf3 20.Rxe7+ Nxe7 21.Qxd7+ Kxd7 22.Bf5+ Ke8
23.Bd7+ Kf8 24.Bxe7# 1-0
```
Select Game Position
It is also possible to specify which ply (half-move) to render in the diagram. You can do that by using the ply property. In the following example, we will render the 10th ply (that is, after black moves Ba5 on move 5).
```chessboard-pgn
ply: 10
show-move: squares
[Event "Casual Game"]
[Site "Berlin GER"]
[Date "1852.??.??"]
[EventDate "?"]
[Round "?"]
[Result "1-0"]
[White "Adolf Anderssen"]
[Black "Jean Dufresne"]
[ECO "C52"]
[WhiteElo "?"]
[BlackElo "?"]
[PlyCount "47"]
1.e4 e5 2.Nf3 Nc6 3.Bc4 Bc5 4.b4 Bxb4 5.c3 Ba5 6.d4 exd4 7.O-O
d3 8.Qb3 Qf6 9.e5 Qg6 10.Re1 Nge7 11.Ba3 b5 12.Qxb5 Rb8 13.Qa4
Bb6 14.Nbd2 Bb7 15.Ne4 Qf5 16.Bxd3 Qh5 17.Nf6+ gxf6 18.exf6
Rg8 19.Rad1 Qxf3 20.Rxe7+ Nxe7 21.Qxd7+ Kxd7 22.Bf5+ Ke8
23.Bd7+ Kf8 24.Bxe7# 1-0
```
It is also possible to highlight the ply. By using show-move you can select the style:
squares: it highlights the origin and destination squares of the move in green.arrow: it draws an arrow from the origin to the destination square of the move.none: no highlighting (default).
Interactive Mode
It is possible to specify a PGN diagram as interactive by using the interactive: true option. If a diagram is interactive, the plugin will show buttons to go to the previous or next move (or the first and last).
You can also add move-list: true to show a move list next to the board (SAN in two columns, one full move per row). Click any half-move to jump there; the current position is highlighted. On small widths the list wraps below the board. If you set move-list: true without interactive: true, the plugin enables interactive mode for you so navigation and the list stay in sync.
Annotations in PGN Mode
PGN diagrams support the same annotations: syntax as FEN boards (see Annotations above). Annotations are displayed only at the target ply: the value of ply: if specified, or the last move in the game if ply: is omitted. In interactive mode, annotations appear when the board is at the target ply and disappear when you navigate away.
```chessboard-pgn
ply: 12
annotations: Ac7-c5/r Hc7/g Hc5/g !c5 Ag7-g6
1.d4 d5 2.Nc3 Nf6 3.Bf4 g6 4.e3 Bg7 5.Nf3 O-O 6.Be2 c5
```
If I find a viable syntax, I'd also like to implement annotations for multiple moves as well.
Current Limitations
This supports the full PGN specification but, for now, the feature is experimental. The syntax in PGN games is still unstable and may change in new versions.
How to compile the plugin
First, install the dependencies with
npm i
Then, you can compile the plugin with:
npm run build
This will create a main.js file in the project root. That is the entry point of the plugin.
Planned Features
- Chessboard color customization.
- Pieces color customization.
- Chessboard annotation and highlights.
- Custom annotation shapes.
Chess Pieces
The SVG pieces were made by jurgenwesterhof (adapted from work of Cburnett), CC BY-SA 3.0 https://creativecommons.org/licenses/by-sa/3.0, via Wikimedia Commons.
