Kifu

by Lux Betancourt
5
4
3
2
1
Score: 51/100

Description

Print-style Go (baduk, weiqi) boards for Obsidian notes: positions, numbered figures, problems, and SGF files

Reviews

No reviews yet.

Stats

3
stars
240
downloads
0
forks
41
days
3
days
3
days
0
total PRs
0
open PRs
0
closed PRs
0
merged PRs
0
total issues
0
open issues
0
closed issues
84
commits

Latest Version

4 days ago

Changelog

Cards in a base now follow the Cards view, the comment in the move tree can be resized, and an unlocked board keeps its comment formatted.

  • In a base shown as Kifu boards, the first property you choose for the view is the card's title, as in Cards. Untick "file name" and the name is no longer shown (it used to stay whatever you chose); put another property first, such as a formula like file.asLink("Problem " + number), and it is the title instead. With no properties a card is just its board. A click anywhere on a card but a board being played opens its note (with Ctrl or Cmd, or the middle button, in a new tab), and changing the properties no longer draws the boards again, so a problem half solved stays half solved. (An .sgf file's card is titled with its whole name, as Cards shows it.)
  • Drag the line between the move tree and the comment in the panel to give the comment more room or less, with the mouse or with a finger. The height is kept, after a restart too; a double click on the line gives the comment back its own size.
  • Unlocking a board no longer turns its comment into plain text with the markdown showing. It stays formatted, and is plain only while you type it in the panel.

README file from

Github

Kifu

Go boards for Obsidian notes that look like the diagrams in a book: black ink, thin lines, numbered stones, nothing shiny. A board can be

  • a position — the whole board or just a corner, with triangles, squares and letters on it;
  • a numbered figure — a sequence shown as stones 1, 2, 3…;
  • a problem — you click a move and the lines you saved answer it, until the line ends correct or incorrect.

Boards are stored as SGF, either right in the note or in an .sgf file the note points at.

A numbered figure, a problem and a diagram with marks

(The pictures on this page were made with the plugin's test page, which imitates Obsidian's default theme.)

Install

In Obsidian open Settings → Community plugins → Browse, search for Kifu, install it and switch it on.

To install it by hand instead, download main.js, manifest.json and styles.css from the latest release, put them in a folder <your vault>/.obsidian/plugins/kifu/, and switch Kifu on under Settings → Community plugins (press the refresh button next to Installed plugins if it is not listed).

Needs Obsidian 1.13 or later. It works on desktop, tablet and phone. It reads nothing outside your vault, and goes online only for games and problems you ask for (see below): when you import one from OGS, goproblems.com or Josekipedia, or when a note is shown that embeds a link to a game or problem on a Go site or to an SGF file elsewhere. It then fetches that one game, problem or file, and nothing else is ever sent anywhere. (After an update, the What's new window loads its animations from the plugin's page on GitHub; it can be turned off.) The only time it looks through the vault's files is when you open the SGF file picker, which lists the .sgf files to choose from; a board reads only the file it points at.

To see everything at once, copy the two files in demo/ into your vault and open Kifu demo.

A first board

Run the command Kifu: Insert board (or right-click in the editor: Kifu → Insert 19 × 19 board, 13 × 13 or 9 × 9): the new board arrives unlocked, ready to set up. Or type the block yourself:

```kifu
```

That is an empty 19 × 19 board.

  • Hover over it: a lock appears beside its upper right corner. (On a touch screen it is always there, faintly.) The lock is there only while the note is being edited: in the reading view boards stay locked, and a board you left unlocked is locked (and saved) when you switch the note to reading.
  • Locked (the normal state), clicking plays stones — captures, ko and all — but nothing you do is saved. Once you have played, ‹ › buttons appear under the lock: ‹ takes back your last move, › plays it again. They only step through what you played, never into the moves saved in the block, so they do not give a problem's answer away. The ↺ button, or Esc, puts everything back.
  • A locked board that is not a problem — a game record, a sequence — has a ▶ play button under the lock: it plays the main line through, a move each second, from the beginning (or from where you are, if there is more to come). Press it again to pause. Playing a move yourself, stepping, or ↺ stops it.
  • Click the lock to edit. Tools appear under the board, and what you do now is written into the block as SGF: once you pause for three seconds, when you lock the board again, or when the board leaves the screen (the note is closed, you scroll away). Waiting keeps quick input from being lost, because writing makes Obsidian draw the block afresh. Click the lock again when you are done.

What a locked board shows:

  • a problem shows its starting position;
  • any other board shows the last position of its main line — so a sequence you drew with the play tool looks the way you left it;
  • a numbers: line turns that into a numbered figure, and a move: line picks another position (move: 0 is the start). The ⚑ tool writes that line for you.

Editing

While a board is unlocked the whole board is shown, with the part that will be hidden afterwards faded, and the moves carry their numbers (unless a numbers: line or the settings say otherwise).

A board being edited, with the move tree beside it

Tool What it does
① Play Plays moves, alternating colours, and builds the tree: go back and play something else to add a variation. Click the tool again to change who plays next from here.
⏩ Pass Records a pass for the side to play, as a move of its own (B[] or W[]).
● ○ Stones Puts a stone down without it being a move (for setting up a position). Click a stone of the same colour to take it off.
△ □ ○ ✕ Marks. They belong to the move you are on, so every move can carry its own.
A Labels. The little box holds the next label: type a, A, 1, 51… and each click counts on from there. Click the tool again to switch between a, A and 1.
Eraser Removes a mark or label; a second click removes the stone under it.
Crop Drag to choose the part of the board the locked board shows. Double-click (or double-tap) to go back to the automatic crop.
⚑ Start Makes the position on the board the one the locked board opens at, by writing a move: line. Click it again on that position to take the choice back. Only positions on the main line can be chosen: step there with ‹ › first. A problem chosen this way is solved from that position. Deleting that position (or a move before it) takes the line away as well.
# Makes the locked board a numbered figure of the main line, or takes the numbers off again. Whatever a numbers: line said before is put back, so a range like 51-100, or an off, is not lost by trying the switch.
↶ Undo (Ctrl/Cmd+Z while the board has the keyboard; Ctrl/Cmd+Shift+Z or Ctrl+Y redoes).
‹ › Previous / next move.
✓ ✗ Mark the line through this move as correct or incorrect.
↑ Move this variation up, towards being the main line.
🗑 Delete this move and everything after it.

Click and drag with the stones, the marks, the labels or the eraser to put down (or take off) a run of points in one stroke; labels count on as you go. A plain click still does what it did: on a stone of the same colour, or a mark that is already there, it takes it off. One undo puts the whole stroke back.

Moving a stone: drag the stone of the current move (the one the board is on, usually the last one played) to another point. The moves after it stay as they are; a point where it could not have been played (a stone is there, or another variation plays there) leaves it where it was. One undo puts it back. On a touch screen a finger that starts on that stone drags it; anywhere else it scrolls as usual. If the record has another stone set up on that same point, it shows through while you drag.

Two things worth knowing:

  • If you have been playing on a locked board and then unlock it, you are asked what to do with the moves you played: Save them (the line on the board becomes part of the tree; undo takes it out again), or Discard them and edit the board as it was. Close the prompt to leave the board locked.
  • Locking puts the board back to the position the note shows.

Comments are written in the move tree panel (see below). A link in one, like [[a note]], follows that note when it is renamed or moved: Obsidian does not reach into code blocks, so the plugin does, in every note and .sgf file. (Not when Settings → Files and links → Automatically update internal links is off.)

Problems

A problem is a starting position plus the lines you saved from it.

  1. Unlock an empty board and set the position up with the stone tools (stones of both colours: that is what tells the plugin it is a problem).
  2. Switch to Play and play the answer; the plugin alternates colours. Go back (‹) and play other tries to add them as variations.
  3. Mark lines with ✓ and ✗ if you like, add comments in the panel, lock.

On the locked board the solver's move is looked up in the tree. If it is there, a saved reply is played after a short pause (where you saved several, one of them at random, so the problem does not always answer the same way; the settings can make it always the first); if it is not, the move is simply incorrect. When a line ends a large ✓ or ✗ appears over the board for a moment, and the verdict and the line's comment stay underneath, the comment on its own line with any markdown rendered (bold, italics, links, Obsidian wikilinks).

Stuck? The eye button under the lock shows the solution: the board starts over and plays out the first saved line judged correct, with the moves numbered, and the move tree panel shows all the saved lines. Step back through it with ‹ ›, or start over with ↺. (No ✓ appears for an answer that was shown rather than found.)

A wrong answer: the saved reply, the verdict and the comment

How a line is judged:

  • A ✓ or ✗ on a move covers everything after it; the mark nearest the end of the line wins.
  • A line with no mark at all is incorrect if some other line is marked ✓. If nothing anywhere is marked ✓, the main line (the first one you entered) is the answer and every other line is incorrect.
  • "Main line" is about the solver's moves only: where the other side has several saved replies, every one of them keeps you on it.

So the quickest way to write a problem is: enter the answer first, then the failures, and mark nothing.

SGF files from elsewhere work too. TE and BM are read as ✓ and ✗ (that is also what the plugin writes). So is a comment on a move that opens with "Correct", "Right", "Solved", "Success", "Wrong", "Incorrect" or "Fail…" as a word of its own, or that begins or ends with RIGHT in capitals, the way files from goproblems.com do.

A board is treated as a problem when its position was set up with stones of both colours and there are moves saved from it. Marks alone do not make one: a reviewed game has its good and bad moves marked too, and stays a game record. Say problem: yes or problem: no to decide yourself, or use the switch: the 🎓 graduation cap button under the lock while a board is unlocked, or Kifu → Problem board in the editor's right-click menu (for the board you right-clicked, or the block the cursor is in). The switch writes a problem: line only when the board would not decide the same by itself. A board that is not a problem still follows saved moves and answers them, but it does not judge by itself: only a line you marked ✓ or ✗ shows its verdict, once it has been played out to the end. With problem: no, nothing is judged at all.

To keep a problem from looking familiar, press the shuffle button under the lock while the board is unlocked (or write randomize: on). Each time the note is opened, the locked board is then shown turned or mirrored (any of the eight ways for a square board; a board that is not square is only mirrored), and half the time with the colours swapped, so a "Black to play" problem becomes "White to play". Captions and comments follow: "Black" and "White" in them change places. Only the picture changes: what you play is looked up as recorded, and unlocking shows the board the way it is written.

Figures and numbers

Press # while editing — or add numbers: on — and the locked board shows the main line played out with the stones numbered.

```kifu
numbers: on
(;GM[1]SZ[19];B[pd];W[nc];B[qf];W[pb];B[qc];W[kc])
```

For a stretch of a longer game, give the moves:

Line Shows
numbers: on every move, numbered from 1
numbers: 51-100 the position after move 100, with moves 51–100 numbered 51–100
numbers: 51-100 from 1 the same stones numbered 1–50
numbers: on from 7 every move, the first one called 7
numbers: off no numbers on this board, not even while playing
move: 50 just the position after move 50, no numbers

A figure is drawn the way kifu are printed: a stone captured during the figure stays where it was, and a move played on an occupied point is listed underneath ("⑦ at ③"). As soon as you step through the moves or play on, you see the real position.

To number stones that are not moves — or to start anywhere you like — use the label tool and type the first number into its box.

Showing part of the board

By default a board is cropped to its stones (every variation counts), with two lines of margin, and snaps to the edge when the edge is close. Lines that run off a cut side are left open, as in print; real edges get the heavy border. Star points are drawn for any size.

Use the crop tool, or a view: line:

Line Shows
view: full the whole board
view: auto cropped to the stones
view: top-right a corner (also top-left, bottom-left, bottom-right; tr, ne … work too)
view: top a side (also bottom, left, right)
view: center the middle
view: top-right 9x7 a corner 9 columns wide and 7 rows tall
view: top 6 the top six rows
view: K10-T19 exactly this rectangle

Board size comes from the SGF (SZ[13], SZ[19:13]). For a new board use size: 13 or size: 13x9, or change the default in the settings.

Pointing at SGF files

```kifu
sgf: [[Cho Chikun - Elementary.sgf]]
game: 12
```
  • sgf: takes a wikilink, a file name, or a path from the vault root or the note's folder. The command Kifu: Insert board from an SGF file, or Kifu → Display SGF file… in the editor's right-click menu, lets you pick one. Only .sgf files are ever used: a note that happens to have the same name is left alone. Renaming or moving the file updates the line.
  • game: picks a game from a file that holds several (problem collections usually do). The first is 1.
  • Every other option works as usual, so several boards can show different moves or corners of one file.
  • Unlocking and editing such a board changes the file; the note keeps pointing at it. Other boards on the same file follow. If the file changes on disk (sync, another program) open boards reload.
  • A board that could not show its file (not found, no such game in it) looks again when a file appears, moves or changes.
  • A file that is not UTF-8, or whose game is cut short (no closing parenthesis), is shown but cannot be edited from here.
  • A game record shows its last position; add move: or numbers: to show another.
  • To pull a board's inline game out into its own file, click the board and run the command Kifu: Move the focused board to an SGF file. A new .sgf file appears beside the note and the block is pointed at it, keeping its other options.

Embedding an SGF file

An SGF file of the vault can also be embedded the way an image is, with no block at all:

![[game.sgf]]
![[game.sgf#50]]
![[game.sgf#Q16]]
  • With no #, a game shows its last position (a problem its start), as a block would.
  • #50 opens it after move 50; #Q16 opens it at the first move of the main line played at Q16 (the start, if no move is played there). #last works too.
  • The board is played like any other, and follows the file when it changes. It is not edited from the note: open the file itself (see below), or show it with a kifu block (sgf: [[game.sgf]]), to edit it.
  • A link to an SGF file on the web takes the same #: ![](https://files.example.com/go/game.sgf#50).

Opening an SGF file

Click an .sgf file in the file explorer (or a link to one) and it opens in a tab of its own, as a board as large as the tab. It works like a board in a note: play on it locked, unlock it to edit, and the move tree panel follows it. Edits go straight into the file.

  • To start a new one, right-click a folder in the file explorer and choose New SGF (under New base): an empty game of your default board size, named Untitled, opens in its tab.
  • A file that holds several games (problem collections usually do) has a picker above the board.
  • The crop, the numbered-figure switch, the ⚑ start, and the problem and shuffle switches are not offered here: what they set is written as an option line in a kifu block, and an SGF file has no place for one.
  • Kifu tells Obsidian that .sgf files are its to open, so they are listed in the file explorer and found for links and embeds without Detect all file extensions. (If another plugin opens SGF files already, it keeps them; then turn that setting on for links and embeds.)

Boards in Bases

A base can show its notes as Kifu boards: choose it in the base's view menu, next to Table and Cards.

A base shown as Kifu boards: problems with their level and topic, and a numbered opening Each note gets a card with its first board, whichever comes first, a kifu block or an embedded link to a game or problem (see Boards from links), or, for an .sgf file in the base, its game; then the properties you chose for the view, as in Cards.

  • As in Cards, the first property is the card's title: the file name, unless you put another property first (a formula such as file.asLink("Problem " + number) makes titles like "Problem 3") or untick it, and then the name is not shown at all. With no properties ticked, a card is just its board. The rest are listed under the title, empty ones left out.
  • The boards can be played: solve a problem or step through a game right in the grid. Nothing is written from here; click anywhere on a card but its board to open the note (with Ctrl or Cmd, or the middle button, in a new tab) and edit it there.
  • The view's settings choose the board size, and whether the boards are playable or just pictures (a click then opens the note).
  • A board that points at an SGF file (sgf:) shows that file's game. A note with no board says so.
  • Boards are drawn as their cards come into sight, so a base of hundreds of problems stays quick, and a card whose note has not changed is kept as it is when the base updates (a problem half solved stays half solved).

This works wherever a base is shown: in a .base file, embedded with ![[Problems.base]], or in a base code block.

Embed a link to a game, review or puzzle on OGS, a problem on goproblems.com, a game on another Go server (see the list below), or an SGF file anywhere on the web, the way you would embed an image:

![](https://online-go.com/game/12345)
![](https://online-go.com/puzzle/2)
![](https://www.goproblems.com/problems/5)
![](https://files.example.com/go/my-game.sgf)
![](https://www.josekipedia.com/#path:pdqf)

Instead of an image you get a board, fetched from the site each time the note is shown, in the reading view and in Live Preview (put the cursor on the link to edit it). A puzzle or problem can be solved on it and a game stepped through, like any other board, but nothing is ever written: to change one, import it instead (see below) and edit the copy in your note. A link that is shown again within a few minutes is not fetched again. A link to anything else stays an ordinary embed.

These links work, besides OGS and goproblems.com:

Site Link to embed
KGS the game's SGF file from the game archive, https://files.gokgs.com/games/…/….sgf
Dragon Go Server the game page, https://www.dragongoserver.net/game.php?gid=…
Fox (野狐) the page its "share" button makes, https://h5.foxwq.com/yehunewshare/?chessid=…
GoQuest the game record page, https://kifu.questgames.net/go/… (GoQuest keeps games for a while only)
Pandanet an SGF file it offers, such as a tournament game (ordinary games are kept in its app)
Stone.gs an OGS game it shows, https://stone.gs/games/ogs/…
Josekipedia a position, https://www.josekipedia.com/#path:… (see Joseki from Josekipedia)
Sensei's Library a page, https://senseis.xmp.net/?Ladder, for its first diagram; …?Ladder#3 for its third (see Diagrams from Sensei's Library)

Games on Tygem, WBaduk and PlayGo, and problems on BlackToPlay, 101weiqi, Tsumego Hero (tsumego.com) and Tsumego Dragon, can not be shown: these sites offer no record that can be fetched through a public interface without signing in, or their terms forbid it. Tsumego Hero does offer a Download SGF button once you have solved a problem: that file can be opened or embedded like any .sgf file in your vault.

An SGF file can be on a server of your own: any http or https link whose path ends in .sgf works (a query after it, such as an access key, is fine). It is treated like an SGF file in your vault: a problem is judged as one, a game record opens at its last move, and a file in an older charset (CA, such as Shift_JIS) is read in it. A server that asks you to sign in can not be used, since the plugin has no way to sign in.

Games and puzzles from OGS

Run Kifu: Import a game or puzzle from online-go.com (or right-click in the editor: Kifu → Import from online-go.com…) and paste a link to a game, a review (demo board) or a puzzle on OGS. A bare number works too: choose what it is under Kind.

  • A game or review arrives as a game record, with its variations and comments; above it, a link back to it with the players, their ranks and the result. Chat that OGS could not write into its files ("someone: [object Object]") is left out.
  • A puzzle arrives as a problem: its stones, the player to move, every line from the puzzle, and a ✓ or ✗ on the lines OGS calls correct or wrong, with their comments.

Only public games, reviews and puzzles can be imported (OGS needs no account for them).

Problems from goproblems.com

Run Kifu: Import a problem from goproblems.com (or right-click in the editor: Kifu → Import from goproblems.com…) and give the problem's number, or paste a link to it (https://www.goproblems.com/problems/5). The problem arrives where the cursor is, variations and comments included, as a board of its own with a link back to its page above it:

[goproblems.com #5](https://www.goproblems.com/problems/5) · Tesuji, 14 kyu, by adum

```kifu
problem: yes
(;AW[pe][pf]…
```

goproblems.com marks a correct line by ending its comment with RIGHT. On import that becomes a ✓ on the move (and the word leaves the comment), so the problem judges itself the way it does on the site.

Only a problem's own page (/problems/<number>) is a board. A time trial, a rush, a collection test, a tournament or an invasion on goproblems.com is a session that serves one problem after another, with scores, and a leaderboard lists them: the number in such a link (/time-trials/…, /rushes/…) is the session's, not a problem's, so there is no board behind it. Embedded, the link shows a line saying what it is in the board's place; it can not be imported. To keep a problem you met in a session, open it on the site and take the link from its own page.

Public problems need nothing more. To import problems that are not public, create an API token in your goproblems.com account and choose it under Settings → Kifu → Importing from goproblems.com. It is kept in Obsidian's secret storage, not in the plugin's settings file, and is sent only to goproblems.com, only with an import.

Network use: the plugin goes online only to fetch a game or problem you asked for: when you import one from OGS, goproblems.com, Josekipedia or Sensei's Library, or when a note is shown that embeds a link to one (on those sites, the other Go servers listed above, or an SGF file anywhere). Each time it asks one place (the site the link is to, or for a Stone.gs link OGS; for a page of Sensei's Library, the page and then the diagram's file) for that one game, problem, position or file, sending nothing but the request itself (and, for goproblems.com, your token if you chose one). The one other time is after an update, if the What's new window is on: it loads its animations from this plugin's page on GitHub.

Diagrams from Sensei's Library

Sensei's Library is the Go wiki. Its pages carry diagrams, and each diagram is kept as an SGF file of its own: the setup, the moves, the marks and letters, and the caption. Embed a link to a page, with the diagram you want after a # (none, or #1, for the first), or run Kifu: Import a diagram from Sensei's Library (right-click in the editor: Kifu → Import from Sensei's Library…) and paste one:

![](https://senseis.xmp.net/?Ladder)
![](https://senseis.xmp.net/?Ladder#3)

The board shows the diagram's caption, and an import puts a link back to the page above it. Two things to know:

  • The number counts the diagrams on the page in order, so if the page is edited and a diagram added above yours, #3 points at another one. For something you want to keep, link the diagram's own file instead: right-click the diagram on the page, copy the link to its .sgf file, and embed that. That address does not change, and an .sgf link on the web is drawn as a board anyway.
  • The library's content is under the Open Content License, which allows copying and modifying it. The page is read for its diagram links, the way a browser follows them; nothing is sent but the request.

Joseki from Josekipedia

Josekipedia is a joseki dictionary written by its readers. Embed a link to a position there (copy it from the address bar: it ends in #path: and the moves), or run Kifu: Import a joseki from Josekipedia (right-click in the editor: Kifu → Import from Josekipedia…) and paste one. You get

  • the moves that lead to the position, each with the comment Josekipedia's contributors wrote for it;
  • the board resting at that position;
  • the moves that may follow, as variations with their comments: click one to play it.

An import puts a link back to the position above the board. The comments are Josekipedia's contributors' work; keep the link with them.

The board asks Josekipedia for the position one move at a time, as its own pages do, through the interface its site describes as public. That interface is not documented, so a change on Josekipedia's side could stop this working until the plugin follows.

The move tree panel

The panel lives in the right sidebar (command Kifu: Show move tree; on a computer it also comes forward when you unlock a board). It follows the board you last used and shows

  • the tree, moves running downwards and variations branching to the right — click any move to go there, or right-click it for a menu: go there; mark its line ✓ or ✗, move its variation up, open the board there (⚑), edit its comment, or delete it and what follows (these are greyed out while the board is locked); dashed stones are ones you played on a locked board and are not saved;
  • ✓ / ✗ on lines that carry a verdict, a dot on moves that have a comment, and a small ⚑ over the position a move: line opens the board at;
  • the comment of the current move, with any markdown rendered (bold, italics, links, Obsidian wikilinks) while the board is locked, and a plain text box to edit it while unlocked. Drag the line between the tree and the comment to give the comment more room or less; the panel keeps that height (a double click on the line gives the comment back its own size);
  • above the tree, the game's name, players and result; while the board is unlocked, the ⓘ button beside them opens Game info, a form for the game name, event, round, date, place, the players and their ranks, komi, handicap, rules, result and source (the SGF properties GN, EV, RO, DT, PC, PB, BR, PW, WR, KM, HA, RU, RE, SO). An empty field takes the property away; one undo puts it all back.

While a problem is locked the panel keeps the answers to itself: it shows only the moves that are on the board. The eye button shows all the saved lines; starting over hides them again. (There is a setting for this. Stepping forward with → walks along a saved line, so that shows the answer too.)

Keys

With the keyboard on a board (click it) or on the panel:

Key
← → previous / next move
↑ ↓ previous / next variation
Home End first position / end of the line
Esc locked: back to the resting position · unlocked: lock · while dragging a crop: never mind
Delete Backspace unlocked: delete the current move and what follows (one per press; undo brings it back)
Ctrl/Cmd+Z unlocked: undo · locked: take back your last step
Ctrl/Cmd+Shift+Z, Ctrl+Y unlocked: redo · locked: make that step again

In the panel's comment box every key belongs to the text you are typing, undo included.

While a board has the keyboard, what you type, paste or undo stays with the board and never reaches the note's text. Obsidian's own hotkeys keep working, though — including ones that act on the editor.

All options

Option lines come first in the block, one per line, before any SGF.

Option Values
sgf link or path take the game from a file
game number which game, when the file (or the block) holds several
size 19, 13x9 size of a board with no SGF yet
view see above part of the board to show
move number, last, a point (Q16) position to show (a point: the first move of the main line played there)
numbers see above numbered figure
scale 80%, 1.5, fit size of this board (fit: as wide as the note, with lines as thin as at the usual size)
coords on / off coordinates beside the board's edges (the real ones, where the part shown has any)
caption text text under the board at rest
comments on / off show move comments under the board
problem yes / no judge moves or not
style paper / theme white paper, or the theme's colours
align left / center / right
randomize on / off show the board turned, mirrored and maybe recoloured, a new way each time the note opens

Settings

Settings → Kifu holds the defaults: scale, colours, crop, coordinates, alignment, new board size, whether played moves are numbered, whether comments show under the board, how replies are chosen (a random saved answer, or always the first) and how long they wait, whether the panel hides a problem's answers, and whether unlocking brings the panel forward. Every one of them is only a default: an option line in a block wins.

What's new: once after each update, a window shows the new features, each with a short animation (loaded from the plugin's page on GitHub when the window opens). A fresh install shows nothing. Turn it off under Settings → Kifu → Updates, or with the link at the bottom of the window.

Changing the look

The drawing is plain SVG coloured by CSS variables, so a snippet can restyle it:

.kifu {
	--kifu-font: "Gill Sans", sans-serif; /* numbers and letters */
	--kifu-ink: #111;                      /* lines, outlines, labels */
	--kifu-paper: #fdfcf8;                 /* background */
	--kifu-black: #111;                    /* black stones */
	--kifu-white: #fff;                    /* white stones */
}

Speed

  • The whole plugin is one file of about 140 kB with no libraries in it.
  • Starting Obsidian only registers things: nothing is read, parsed or drawn, and no settings file is opened, until a board is actually on screen. In the test page, loading the file takes about 4 ms and starting the plugin under half a millisecond; in Obsidian itself, with its caches warm, loading and starting it again takes 20–50 ms.
  • A board is around fifteen SVG nodes however many stones it has (all stones of one colour share a path), plus one per label; its buttons are not made until the pointer comes over it. Drawing one takes under a millisecond, a full board with 180 numbered stones about 2 ms, and a step through such a game a quarter of a millisecond. A note of 320 problems opens in under 100 ms.
  • In Live Preview, the plugin's editor extension costs nothing measurable per keystroke or cursor move, with or without links in the note.

Good to know

  • Saving changes only the lines between a block's two fences, and of those only the option lines and the one game the board shows: a second game or a remark you put in the block stays as it is. While the note is open in an editor the change goes through the editor, so the note's own undo takes it back.
  • Which block is whose. A board knows its block by its place among the note's boards (the third of five, say) and by the block's exact text. As the note changes, that place is carried along one change at a time, the way an editor carries a cursor: text typed elsewhere, or boards added, removed and moved around, do not send an edit to the wrong lines. In an editor the board simply moves with its block. An edit is written only where place and exact text both still fit. If the block itself was changed or removed while an edit was waiting for it (by hand, by a sync, by the same board open in another pane), or the note was rearranged so thoroughly in one go that it is no longer certain which block is meant, nothing is written and a notice says so. An edit that was refused is gone, it does not wait for a later chance: the board goes back to what it was drawn from.
  • Boards that read exactly the same (a row of empty boards, say) are kept apart by their places. The one thing a note's text cannot show is which is which once identical blocks have traded places; an edit then goes to the block under the board that shows it. A board that was left unlocked or played out and then scrolled out of sight comes back the way you left it, with one exception: a board that has twins comes back locked if the note was edited by hand meanwhile, rather than risk unlocking the wrong one.
  • Where Obsidian does not tell a board which lines it stands on (an embedded note is the likely case), the board is found by its text, provided no other board of the note reads the same. Two that do cannot be told apart there: the edit is refused with a notice, and giving one of them a caption: line settles it. In the editor and the reading view this does not arise.
  • If the note or an SGF file cannot be written (a sync program has it locked, a drive has stopped answering), the edit stays on the board and saving is tried again by itself; a notice says so once. Edits still waiting when you switch the plugin off or quit Obsidian are written first.
  • A block whose SGF is not closed properly (a missing )) is shown but cannot be edited, so that nothing after it gets swallowed. A game: line asking for a game the block does not have shows a message instead of a board.
  • Changing only an option (the crop, the figure switch) leaves the SGF text exactly as you wrote it. Changing the game writes that game out afresh: properties the plugin does not understand are kept, line breaks are its own.
  • An SGF file that is not UTF-8 is displayed using its CA charset.
  • Links inside code blocks are not tracked by Obsidian, so renaming an .sgf file does not update sgf: lines. Moving it to another folder is fine as long as the name stays unique.
  • A board in a Canvas text card can be viewed and played, not edited.

Status

Version 1.0.0, the first public release. Besides being used in Obsidian on the desktop, it is checked automatically: the built plugin runs in a browser against a stand-in for the Obsidian API, with Live Preview played by a real CodeMirror editor, and on touch screens in Safari's engine (WebKit) as well as Chromium. Wherever Obsidian's behaviour is not documented, the checks are run with the stand-in behaving both ways. The part that writes into notes got the most attention: it was reviewed independently three times, and is exercised by a randomized test on top of the fixed scenarios.

Found a bug, or a board that looks wrong? Please open an issue, with the block's text if you can.

License

GNU General Public License v3.0.

Building it yourself

npm install
npm run build          # type-check and bundle main.js
npm test               # unit tests: SGF, rules, sessions, finding blocks in Markdown
npm run test:browser   # the built plugin in Chromium (once: npx playwright install chromium)
npm run test:monkey    # randomized runs of the same, a few minutes
npm run lint           # Obsidian's own lint rules
  • tests/*.test.ts — unit tests. markdown.test.ts checks the code that finds and rewrites a block against a CommonMark parser on thousands of generated notes.
  • tests/harness/obsidian-mock.js — the stand-in for the Obsidian API; cm-lp.ts — Live Preview on a real CodeMirror 6.
  • tests/harness/touch.mjs — taps on tablet and phone profiles, in WebKit (once: npx playwright install webkit) and Chromium.
  • tests/harness/interact.mjs, editor.mjs, identity.mjs — the scenarios (the last one is all about boards that read the same, notes rearranged under a board, panes that are behind, and writes that fail); ONLY='pattern' in the environment runs the scenarios whose names match. perf.mjs — timings (startup, a board, a note of 320 problems, what the editor extension costs per keystroke in a large note); profile.mjs — CPU profiles of those paths, with the functions named (it builds an unminified bundle for itself); shots.mjs, docs.mjs — pictures; whatsnew.mjs — the animations of the What's new window (needs ffmpeg).
  • tests/harness/monkey.mjs — a "monkey" that places and removes stones, marks and labels, types comments, locks, scrolls and (in its rougher profiles) edits the note by hand at the same time: types into blocks, deletes, copies and moves them, undoes, changes the file from outside. It does so in eight arrangements of panes and five kinds of note, most of them full of identical boards. After every step it checks that nothing is in a block other than the one whose board was used, and at the end that nothing outside the blocks changed, that every board shows what its block says, that no edit vanished without a notice, that none vanished at all from a block nobody had touched by hand, and that nothing typed by hand was taken back. node tests/harness/monkey.mjs live,both hands 1-10 runs chosen arrangements, profiles and seeds.

Releasing

  1. Put the new version (x.y.z) in manifest.json and package.json, and add it to versions.json with the lowest Obsidian version it needs.
  2. Commit, tag the commit with exactly the version, and push only the tag: git tag -a 1.0.1 -m "Kifu 1.0.1" && git push origin 1.0.1.
  3. The release workflow (.github/workflows/release.yml) checks that the tag matches the manifest, builds, runs the unit tests and publishes the release with main.js, manifest.json and styles.css.
  4. Once the release is there, push the branch: git push.

The order matters. Obsidian installs a plugin by reading manifest.json on the default branch and downloading the release with that version; if the branch names a version whose release does not exist yet, installing fails.