mkdocs-chess-plugin 0.1.0__py3-none-any.whl

mkdocs_chess_plugin/assets/vendor/chess.js-LICENSE.txt

@@ -0,0 +1,23 @@
+Copyright (c) 2025, Jeff Hlywa (jhlywa@gmail.com)
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice,
+   this list of conditions and the following disclaimer.
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
+LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGE.

mkdocs_chess_plugin/assets/xiangqi-rules.mjs

@@ -0,0 +1,122 @@
+/** Board indices run from a9 (0) to i0 (89), independent of display orientation. */
+export const START = 'rnbakabnr/9/1c5c1/p1p1p1p1p/9/9/P1P1P1P1P/1C5C1/9/RNBAKABNR w - - 0 1';
+export const names = { K:'帅', A:'仕', B:'相', N:'马', R:'车', C:'炮', P:'兵', k:'将', a:'士', b:'象', n:'马', r:'车', c:'炮', p:'卒' };
+export const side = p => p ? (p === p.toUpperCase() ? 'w' : 'b') : null;
+export const opposite = s => s === 'w' ? 'b' : 'w';
+export const coord = i => String.fromCharCode(97 + i % 9) + (9 - Math.floor(i / 9));
+export const index = s => /^[a-i][0-9]$/.test(s) ? (9 - Number(s[1])) * 9 + s.charCodeAt(0) - 97 : -1;
+const palace = (x,y,s) => x >= 3 && x <= 5 && (s === 'w' ? y >= 7 && y <= 9 : y >= 0 && y <= 2);
+const elephants = new Set(['2,0','6,0','0,2','4,2','8,2','2,4','6,4']);
+const advisors = new Set(['3,0','5,0','4,1','3,2','5,2']);
+
+export function parseFen(input) {
+  const f = input.trim().split(/\s+/);
+  if (![2,6].includes(f.length) || !/^[wb]$/.test(f[1])) throw Error('FEN 需包含十行棋盘及行棋方 w（红）或 b（黑）。');
+  if (f.length === 6 && (f[2] !== '-' || f[3] !== '-' || !/^\d+$/.test(f[4]) || !/^[1-9]\d*$/.test(f[5]) || !Number.isSafeInteger(+f[4]) || !Number.isSafeInteger(+f[5]))) throw Error('FEN 计数或占位字段无效。');
+  const rows = f[0].split('/'), board = [];
+  if (rows.length !== 10) throw Error('棋盘必须有十行。');
+  for (const row of rows) {
+    const cells = [];
+    for (let c of row) {
+      if (/^[1-9]$/.test(c)) cells.push(...Array(+c).fill(null));
+      else {
+        c = ({h:'n',H:'N',e:'b',E:'B'})[c] || c;
+        if (!names[c]) throw Error('FEN 包含未知棋子。');
+        cells.push(c);
+      }
+    }
+    if (cells.length !== 9) throw Error('棋盘每行必须有九个位置。');
+    board.push(...cells);
+  }
+  const counts = {};
+  board.forEach((p,i) => {
+    if (!p) return;
+    counts[p] = (counts[p] || 0) + 1;
+    const s = side(p), t = p.toLowerCase(), x = i % 9, y = Math.floor(i/9), homeY = s === 'b' ? y : 9-y;
+    if (t === 'k' && !palace(x,y,s)) throw Error('将帅必须位于九宫。');
+    if (t === 'a' && !advisors.has(`${x},${homeY}`)) throw Error('仕士位置无效。');
+    if (t === 'b' && !elephants.has(`${x},${homeY}`)) throw Error('相象位置无效。');
+    if (t === 'p' && (homeY < 3 || (homeY < 5 && x % 2))) throw Error('兵卒位置无效。');
+  });
+  for (const s of ['w','b']) {
+    for (const [type,limit] of Object.entries({k:1,a:2,b:2,n:2,r:2,c:2,p:5})) {
+      const key = s === 'w' ? type.toUpperCase() : type;
+      if ((counts[key] || 0) > limit || (type === 'k' && counts[key] !== 1)) throw Error('棋子数量无效，双方须各有一枚将帅。');
+    }
+  }
+  const state = {board, turn:f[1], halfmove:+(f[4] || 0), fullmove:+(f[5] || 1)};
+  if (inCheck(state, opposite(state.turn))) throw Error('非行棋方处于被将军状态，或将帅照面；请检查行棋方和局面。');
+  return state;
+}
+export function fen(state) {
+  const rows = [];
+  for (let y=0;y<10;y++) {
+    let row='', empty=0;
+    for (const p of state.board.slice(y*9,y*9+9)) {
+      if (!p) empty++;
+      else { if (empty) row+=empty; empty=0; row+=p; }
+    }
+    if (empty) row+=empty;
+    rows.push(row);
+  }
+  return `${rows.join('/')} ${state.turn} - - ${state.halfmove} ${state.fullmove}`;
+}
+export function pseudo(board, from, to) {
+  const p=board[from], target=board[to];
+  if (!p || from===to || to<0 || to>=90 || side(p)===side(target)) return false;
+  const x=from%9,y=Math.floor(from/9),tx=to%9,ty=Math.floor(to/9),dx=tx-x,dy=ty-y,ax=Math.abs(dx),ay=Math.abs(dy),s=side(p);
+  const type=p.toLowerCase();
+  if (type==='n') return ax===2 && ay===1 ? !board[from+Math.sign(dx)] : ax===1 && ay===2 && !board[from+9*Math.sign(dy)];
+  if (type==='b') return ax===2 && ay===2 && (s==='w'?ty>=5:ty<=4) && !board[from+dx/2+9*dy/2];
+  if (type==='a') return ax===1 && ay===1 && palace(tx,ty,s);
+  if (type==='p') return (dx===0 && dy===(s==='w'?-1:1)) || (ay===0 && ax===1 && (s==='w'?y<=4:y>=5));
+  if (type==='k' && ax+ay===1 && palace(tx,ty,s)) return true;
+  if (dx!==0 && dy!==0) return false;
+  const step=dx===0?9*Math.sign(dy):Math.sign(dx);
+  let screens=0;
+  for(let i=from+step;i!==to;i+=step) if(board[i]) screens++;
+  if(type==='r') return screens===0;
+  if(type==='c') return screens===(target?1:0);
+  return type==='k' && target?.toLowerCase()==='k' && dx===0 && screens===0;
+}
+export function inCheck(state, who=state.turn) {
+  const king=state.board.indexOf(who==='w'?'K':'k');
+  return king<0 || state.board.some((p,i)=>side(p)===opposite(who) && pseudo(state.board,i,king));
+}
+export function legal(state, from, to) {
+  if (side(state.board[from])!==state.turn || state.board[to]?.toLowerCase()==='k' || !pseudo(state.board,from,to)) return false;
+  const board=state.board.slice(); board[to]=board[from]; board[from]=null;
+  return !inCheck({...state,board});
+}
+export function moves(state, from=null) {
+  const result=[];
+  for(let i=0;i<90;i++) if ((from===null || i===from) && side(state.board[i])===state.turn)
+    for(let j=0;j<90;j++) if(legal(state,i,j)) result.push(coord(i)+coord(j));
+  return result;
+}
+export function play(state, move) {
+  if (!/^[a-i][0-9][a-i][0-9]$/.test(move)) throw Error('着法坐标无效。');
+  const from=index(move.slice(0,2)),to=index(move.slice(2));
+  if (!legal(state,from,to)) throw Error('这步棋不合法，请重新选择。');
+  const board=state.board.slice(),p=board[from],capture=!!board[to]; board[to]=p; board[from]=null;
+  return {board,turn:opposite(state.turn),halfmove:capture||p.toLowerCase()==='p'?0:state.halfmove+1,fullmove:state.fullmove+(state.turn==='b'?1:0)};
+}
+export function notation(state, move) {
+  const from=index(move.slice(0,2)),to=index(move.slice(2)),p=state.board[from];
+  if(!p || to<0) return move;
+  const red=side(p)==='w',x=from%9,y=Math.floor(from/9),tx=to%9,ty=Math.floor(to/9);
+  const number=n=>(red?'〇一二三四五六七八九':'０１２３４５６７８９')[n];
+  const file=n=>number(red?9-n:n+1),type=p.toLowerCase();
+  let prefix=names[p]+file(x);
+  let peers=state.board.map((q,i)=>q===p&&i%9===x?i:-1).filter(i=>i>=0).sort((a,b)=>red?a-b:b-a);
+  if (type==='p') {
+    const groups=Array.from({length:9},(_,col)=>state.board.map((q,i)=>q===p&&i%9===col?i:-1).filter(i=>i>=0)).filter(g=>g.length>1);
+    if(groups.length>1 && peers.length>1) {
+      const all=groups.sort((a,b)=>red?b[0]%9-a[0]%9:a[0]%9-b[0]%9).flatMap(g=>g.sort((a,b)=>red?a-b:b-a));
+      prefix='一二三四五'[all.indexOf(from)]+names[p];
+    } else if(peers.length>1) prefix=(peers.length===2?'前后':peers.length===3?'前中后':'一二三四五')[peers.indexOf(from)]+names[p];
+  } else if(peers.length>1 && !['a','b','k'].includes(type)) prefix=(peers[0]===from?'前':'后')+names[p];
+  if(ty===y) return prefix+'平'+file(tx);
+  const direction=(red?ty<y:ty>y)?'进':'退';
+  return prefix+direction+(['n','b','a'].includes(type)?file(tx):number(Math.abs(ty-y)));
+}

mkdocs_chess_plugin/markdown.py

@@ -0,0 +1,301 @@
+"""Turn FEN-titled admonitions into SVG boards with a no-script fallback."""
+
+from dataclasses import dataclass
+import re
+from typing import Callable
+import xml.etree.ElementTree as ET
+
+from markdown.extensions import Extension
+from markdown.treeprocessors import Treeprocessor
+from mkdocs.exceptions import PluginError
+
+from .themes import Geometry, ThemeCatalog
+
+
+XIANG_NAMES = dict(zip("KABNRCPkabnrcp", "帅仕相马车炮兵将士象马车炮卒"))
+XIANG_ALIASES = str.maketrans("HhEe", "NnBb")
+MAX_COUNTER = str(2**53 - 1)
+
+# Original flat silhouettes on a 48 × 48 canvas, shared by both colors.
+CHESS_SHAPES = {
+    "k": ("M22 4H26V10H32V14H26V20H22V14H16V10H22Z",
+          "M14 33C13 27 10 23 10 20C10 15 18 14 24 22C30 14 38 15 38 20C38 23 35 27 34 33L36 41H12Z"),
+    "q": ("M8 16L17 24L24 13L31 24L40 16L34 34L36 41H12L14 34Z",
+          "M14 34H34"),
+    "r": ("M9 8H16V14H20V8H28V14H32V8H39V20L33 25V34L37 40H11L15 34V25L9 20Z",
+          "M15 25H33M15 34H33"),
+    "b": ("M24 8C27 12 35 18 35 24C35 29 31 32 27 34H34L37 41H11L14 34H21C17 32 13 29 13 24C13 18 21 12 24 8Z",
+          "M26 17L21 24M21 34H27"),
+    "n": ("M12 41H36C37 28 34 16 27 10L19 6L18 14L9 25L12 30L22 25C21 29 15 32 12 35Z",
+          "M21 17H22"),
+    "p": ("M24 8A8 8 0 0 1 28 23C29 28 31 33 36 37V41H12V37C17 33 19 28 20 23A8 8 0 0 1 24 8Z",),
+}
+
+
+def xiang_piece(node, piece):
+    node.set("class", "fen-board-xiang-light" if piece.isupper() else "fen-board-xiang-dark")
+    ET.SubElement(node, "circle", {"r": "22", "class": "fen-board-disc"})
+    ET.SubElement(node, "circle", {"r": "18.5", "class": "fen-board-ring"})
+    ET.SubElement(node, "text", {"y": "1", "class": "fen-board-character"}).text = XIANG_NAMES[piece]
+
+
+def chess_piece(node, piece):
+    color = "light" if piece.isupper() else "dark"
+    drawing = ET.SubElement(node, "g", {"class": f"fen-board-chess-{color}", "transform": "translate(-24 -24)"})
+    for path in CHESS_SHAPES[piece.lower()]:
+        ET.SubElement(drawing, "path", {"d": path})
+    if piece.lower() == "q":
+        for x, y in ((8, 13), (24, 10), (40, 13)):
+            ET.SubElement(drawing, "circle", {"cx": str(x), "cy": str(y), "r": "2.6"})
+    if piece.lower() == "b":
+        ET.SubElement(drawing, "circle", {"cx": "24", "cy": "6", "r": "2.5"})
+
+
+def xiang_grid(svg):
+    grid = ET.SubElement(svg, "g", {"class": "fen-board-xiang-grid"})
+    for y in range(10):
+        ET.SubElement(grid, "path", {"d": f"M40 {40 + y * 50} H440"})
+    for x in range(9):
+        file = 40 + x * 50
+        path = f"M{file} 40 V490" if x in (0, 8) else f"M{file} 40 V240 M{file} 290 V490"
+        ET.SubElement(grid, "path", {"d": path})
+    ET.SubElement(grid, "path", {"d": "M190 40 L290 140 M290 40 L190 140 M190 390 L290 490 M290 390 L190 490"})
+    ET.SubElement(grid, "rect", {"x": "34", "y": "34", "width": "412", "height": "462"})
+    river = ET.SubElement(svg, "g", {"class": "fen-board-river"})
+    for x, label in ((140, "楚 河"), (340, "汉 界")):
+        ET.SubElement(river, "text", {"x": str(x), "y": "273"}).text = label
+    files = ET.SubElement(svg, "g", {"class": "fen-board-coords"})
+    for x, label in enumerate("九八七六五四三二一"):
+        file = str(40 + x * 50)
+        ET.SubElement(files, "text", {"x": file, "y": "526", "class": "fen-board-xiang-light"}).text = label
+        ET.SubElement(files, "text", {"x": file, "y": "15"}).text = str(x + 1)
+
+
+def chess_grid(svg):
+    grid = ET.SubElement(svg, "g")
+    for row in range(8):
+        for col in range(8):
+            color = "dark" if (row + col) % 2 else "light"
+            ET.SubElement(grid, "rect", {
+                "x": str(24 + col * 54), "y": str(24 + row * 54),
+                "width": "54", "height": "54", "class": f"fen-board-tile-{color}",
+            })
+    labels = ET.SubElement(svg, "g", {"class": "fen-board-coords"})
+    for index in range(8):
+        center = 51 + index * 54
+        ET.SubElement(labels, "text", {"x": str(center), "y": "473"}).text = chr(97 + index)
+        ET.SubElement(labels, "text", {"x": "12", "y": str(center + 5)}).text = str(8 - index)
+
+
+def xiang_fields(castling, en_passant, _turn):
+    if (castling, en_passant) != ("-", "-"):
+        raise ValueError("中国象棋的两个占位字段应为 - -")
+
+
+def chess_fields(castling, en_passant, turn):
+    if castling != "-" and not re.fullmatch(r"K?Q?k?q?", castling):
+        raise ValueError("国际象棋的易位权应为 KQkq 的子集或 -")
+    rank = "6" if turn == "w" else "3"
+    if en_passant != "-" and not re.fullmatch(f"[a-h]{rank}", en_passant):
+        raise ValueError("国际象棋的过路兵目标格与行棋方不符")
+
+
+@dataclass(frozen=True)
+class BoardType:
+    label: str
+    light: str
+    columns: int
+    rows: int
+    origin: int
+    step: int
+    height: int
+    pieces: str
+    aliases: dict
+    validate_fields: Callable
+    draw_grid: Callable
+    draw_piece: Callable
+
+
+BOARD_TYPES = {
+    "xiang": BoardType("局面图", "红", 9, 10, 40, 50, 530, "".join(XIANG_NAMES),
+                       XIANG_ALIASES, xiang_fields, xiang_grid, xiang_piece),
+    "chess": BoardType("国际象棋局面", "白", 8, 8, 51, 54, 480, "KQRBNPkqrbnp",
+                       {}, chess_fields, chess_grid, chess_piece),
+}
+
+
+def infer_game(value):
+    fields = value.split()
+    ranks = len(fields[0].split("/")) if fields else 0
+    matches = [key for key, style in BOARD_TYPES.items() if style.rows == ranks]
+    if len(matches) != 1:
+        raise ValueError("无法识别棋盘行数，请使用 chess 或 xiang 指定棋种")
+    return matches[0]
+
+
+def parse_fen(value, game=None):
+    """Validate FEN syntax while allowing illustrative, non-playable studies."""
+    style = BOARD_TYPES[game or infer_game(value)]
+    fields = value.split()
+    if len(fields) not in (2, 6) or fields[1] not in ("w", "b"):
+        raise ValueError(f"需包含棋盘和行棋方 w（{style.light}）或 b（黑）")
+    if len(fields) == 2:
+        fields.extend(["-", "-", "0", "1"])
+    style.validate_fields(fields[2], fields[3], fields[1])
+    if (
+        not re.fullmatch(r"[0-9]+", fields[4])
+        or not re.fullmatch(r"[1-9][0-9]*", fields[5])
+        or any((len(n), n) > (len(MAX_COUNTER), MAX_COUNTER)
+               for n in (value.lstrip("0") for value in fields[4:]))
+    ):
+        raise ValueError("FEN 计数字段无效")
+
+    rows = fields[0].translate(style.aliases).split("/")
+    if len(rows) != style.rows:
+        raise ValueError(f"此棋种的棋盘必须有 {style.rows} 行")
+    board = []
+    for rank, row in enumerate(rows, 1):
+        cells = []
+        for char in row:
+            if "1" <= char <= str(style.columns):
+                cells.extend([None] * int(char))
+            elif char in style.pieces:
+                cells.append(char)
+            else:
+                raise ValueError(f"第 {rank} 行包含未知棋子或字符 {char!r}")
+        if len(cells) != style.columns:
+            raise ValueError(f"第 {rank} 行必须有 {style.columns} 个位置，实际为 {len(cells)} 个")
+        board.extend(cells)
+    fields[0] = "/".join(rows)
+    return board, fields[1], " ".join(fields)
+
+
+def artwork_image(parent, uri, x, y, width, height):
+    return ET.SubElement(parent, "image", {
+        "href": f"fen-board-asset:{uri}", "x": f"{x:g}", "y": f"{y:g}",
+        "width": f"{width:g}", "height": f"{height:g}",
+    })
+
+
+def king_icons(title, style, pieces):
+    for side, king in (("w", "K"), ("b", "k")):
+        icon = ET.SubElement(title, "svg", {
+            "class": "fen-board-icon", "data-color": side, "viewBox": "-24 -24 48 48",
+            "aria-hidden": "true", "focusable": "false", "xmlns": "http://www.w3.org/2000/svg",
+        })
+        if pieces:
+            artwork_image(icon, pieces.images[king], -24, -24, 48, 48)
+        else:
+            style.draw_piece(ET.SubElement(icon, "g"), king)
+
+
+def diagram(board, position, game, prefix, label, board_image, piece_images):
+    style = BOARD_TYPES[game]
+    geometry = board_image.geometry if board_image else Geometry(
+        480, style.height, style.origin, style.origin, style.step, style.step,
+    )
+    width, height = geometry.width, geometry.height
+    x, y, dx, dy = geometry.x, geometry.y, geometry.dx, geometry.dy
+    grid = (style.columns, style.rows, x, y, dx, dy, width, height)
+    figure = ET.Element("figure", {
+        "class": "fen-board-figure", "data-fen": position, "data-game": game, "data-prefix": prefix,
+        "data-grid": " ".join(f"{n:g}" for n in grid),
+        "data-label": style.label, "data-light": style.light,
+    })
+    if board_image:
+        figure.set("data-board-art", "")
+    surface = ET.SubElement(figure, "div", {"class": "fen-board-surface"})
+    svg = ET.SubElement(surface, "svg", {
+        "xmlns": "http://www.w3.org/2000/svg", "viewBox": f"0 0 {width:g} {height:g}",
+        "role": "img", "aria-label": label, "focusable": "false",
+    })
+    ET.SubElement(svg, "desc").text = f"FEN: {position}"
+    defs = ET.SubElement(svg, "defs")
+    for piece in style.pieces:
+        shape = ET.SubElement(defs, "g", {"id": f"{prefix}-{piece}"})
+        if piece_images:
+            w, h = dx * piece_images.scale, dy * piece_images.scale
+            ox, oy = piece_images.offset
+            artwork_image(shape, piece_images.images[piece], dx * ox - w / 2, dy * oy - h / 2, w, h)
+        else:
+            if board_image:
+                ratio = min(dx, dy) / style.step
+                shape.set("transform", f"scale({ratio:g})")
+            style.draw_piece(shape, piece)
+    if board_image:
+        artwork_image(svg, board_image.uri, 0, 0, width, height)
+    else:
+        style.draw_grid(svg)
+    layer = ET.SubElement(svg, "g", {"class": "fen-board-pieces"})
+    for index, piece in enumerate(board):
+        if piece is None:
+            continue
+        row, col = divmod(index, style.columns)
+        rank = style.rows - row - (1 if game == "xiang" else 0)
+        group = ET.SubElement(layer, "g", {
+            "transform": f"translate({x + col * dx:g} {y + row * dy:g})",
+            "data-square": f"{chr(97 + col)}{rank}", "data-piece": piece,
+        })
+        ET.SubElement(group, "use", {"href": f"#{prefix}-{piece}"})
+    return figure
+
+
+class BoardTreeprocessor(Treeprocessor):
+    def __init__(self, md, catalog, sounds):
+        super().__init__(md)
+        self.catalog = catalog
+        self.sounds = sounds
+
+    def run(self, root):
+        count = 0
+        for block in list(root.iter()):
+            classes = block.get("class", "").split()
+            if block.tag == "details":
+                title_tag = "summary"
+            elif block.tag == "div" and "admonition" in classes:
+                title_tag = "p"
+            else:
+                continue
+            choices = [name for name in classes if name in BOARD_TYPES or name == "board"]
+            if not choices:
+                continue
+            if len(choices) != 1:
+                raise PluginError("Each board block must specify exactly one board type")
+            syntax = choices[0]
+            title = block[0] if len(block) and block[0].tag == title_tag else None
+            value = "" if title is None else "".join(title.itertext()).strip()
+            try:
+                game = infer_game(value) if syntax == "board" else syntax
+                board, turn, position = parse_fen(value, game)
+            except ValueError as error:
+                raise PluginError(f'{syntax} 局面图 FEN 无效（{value}）：{error}') from error
+            style = BOARD_TYPES[game]
+            board_image, piece_images = self.catalog.select(game, classes)
+            label = f"{style.label} · {style.light if turn == 'w' else '黑'}方走棋"
+            for child in list(title):
+                title.remove(child)
+            title.text = None
+            king_icons(title, style, piece_images)
+            heading = ET.SubElement(title, "span", {"class": "fen-board-title"})
+            if title_tag == "summary":
+                heading.text = "Position" if game == "chess" else "局面"
+            else:
+                heading.text = label
+            block.set("class", " ".join([*classes, "fen-board"]))
+            block.set("data-turn", turn)
+            count += 1
+            figure = diagram(board, position, game, f"fen-board-{count}", label, board_image, piece_images)
+            for event, filename in self.sounds.items():
+                figure.set(f"data-sound-{event}", filename)
+            block.insert(1, figure)
+
+
+class BoardExtension(Extension):
+    def __init__(self, catalog=None, sounds=None):
+        super().__init__()
+        self.catalog = catalog if catalog is not None else ThemeCatalog()
+        self.sounds = sounds or {}
+
+    def extendMarkdown(self, md):
+        # Process parsed admonitions. Fenced and inline examples stay literal.
+        md.treeprocessors.register(BoardTreeprocessor(md, self.catalog, self.sounds), "fen_board", 15)

mkdocs_chess_plugin/themes.py

@@ -0,0 +1,147 @@
+"""Load opt-in artwork packs from the site author's filesystem."""
+
+from dataclasses import dataclass
+import json
+import math
+from pathlib import Path
+import re
+from typing import Optional
+
+from mkdocs.exceptions import PluginError
+
+
+THEME_NAME = re.compile(r"[a-z0-9][a-z0-9-]*")
+IMAGE_NAME = re.compile(r"[A-Za-z0-9][A-Za-z0-9._-]*\.(?:svg|png|jpg|jpeg|gif|webp)", re.IGNORECASE)
+DEFAULT = "default"
+
+
+@dataclass(frozen=True)
+class Geometry:
+    width: float
+    height: float
+    x: float
+    y: float
+    dx: float
+    dy: float
+
+
+@dataclass(frozen=True)
+class BoardImage:
+    uri: str
+    geometry: Geometry
+
+
+@dataclass(frozen=True)
+class PieceImages:
+    images: dict
+    scale: float
+    offset: tuple
+
+
+@dataclass(frozen=True)
+class Theme:
+    game: str
+    board: Optional[BoardImage]
+    pieces: Optional[PieceImages]
+
+
+def number(value, field):
+    if type(value) not in (float, int) or not math.isfinite(value):
+        raise ValueError(f"{field} must be a finite number")
+    return value
+
+
+def pair(value, field):
+    if not isinstance(value, list) or len(value) != 2:
+        raise ValueError(f"{field} must have two numbers")
+    return tuple(number(n, field) for n in value)
+
+
+class ThemeCatalog:
+    def __init__(self):
+        self.themes = {}
+        self.defaults = {}
+        self.assets = {}
+
+    def load(self, base, manifests, defaults, games):
+        for name, location in manifests.items():
+            if not isinstance(name, str) or not THEME_NAME.fullmatch(name) or name == DEFAULT:
+                raise PluginError(f"chess invalid theme name: {name!r}")
+            try:
+                if not isinstance(location, str):
+                    raise ValueError("manifest path must be a string")
+                manifest = (base / location).resolve(strict=True)
+                self.themes[name] = self.read_theme(name, manifest, games)
+            except (OSError, ValueError, TypeError, KeyError, OverflowError) as error:
+                raise PluginError(f"chess theme {name!r}: {error}") from error
+        for game, options in defaults.items():
+            if game not in games or not isinstance(options, dict) or options.keys() - {"board", "pieces"}:
+                raise PluginError(f"chess invalid defaults for {game!r}")
+            for kind, name in options.items():
+                self.resolve(game, kind, name)
+        self.defaults = defaults
+
+    def read_theme(self, name, manifest, games):
+        data = json.loads(manifest.read_text(encoding="utf-8-sig"))
+        if not isinstance(data, dict) or data.get("game") not in games:
+            raise ValueError("game must be a registered chess or xiang board type")
+        game = data["game"]
+        variant = games[game]
+        root = manifest.parent
+
+        def image(filename):
+            if not isinstance(filename, str) or not IMAGE_NAME.fullmatch(filename):
+                raise ValueError(f"invalid artwork filename: {filename!r}")
+            path = (root / filename).resolve(strict=True)
+            if path.parent != root or not path.is_file():
+                raise ValueError(f"artwork must be a file next to the manifest: {filename}")
+            uri = f"themes/{name}/{filename}"
+            self.assets[uri] = path
+            return uri
+
+        board = None
+        if "board" in data:
+            spec = data["board"]
+            width, height = pair(spec["size"], "board.size")
+            x, y = pair(spec["origin"], "board.origin")
+            dx, dy = pair(spec["step"], "board.step")
+            if not (dx > 0 and dy > 0 and
+                    0 <= x < x + (variant.columns - 1) * dx < width and
+                    0 <= y < y + (variant.rows - 1) * dy < height):
+                raise ValueError("board grid must fit inside the image with positive steps")
+            board = BoardImage(image(spec["image"]), Geometry(width, height, x, y, dx, dy))
+
+        pieces = None
+        if "pieces" in data:
+            spec = data["pieces"]
+            images = spec["images"]
+            if not isinstance(images, dict) or images.keys() != set(variant.pieces):
+                raise ValueError("pieces.images must map every piece letter in this game's FEN")
+            scale = number(spec.get("scale", 1), "pieces.scale")
+            if scale <= 0:
+                raise ValueError("pieces.scale must be positive")
+            offset = pair(spec.get("offset", [0, 0]), "pieces.offset")
+            pieces = PieceImages({piece: image(file) for piece, file in images.items()}, scale, offset)
+        if board is None and pieces is None:
+            raise ValueError("expected a board or pieces entry")
+        return Theme(game, board, pieces)
+
+    def resolve(self, game, kind, name):
+        if name == DEFAULT:
+            return None
+        theme = self.themes.get(name) if isinstance(name, str) else None
+        value = getattr(theme, kind) if theme and theme.game == game else None
+        if value is None:
+            raise PluginError(f"chess {game}: {name!r} has no compatible {kind} artwork")
+        return value
+
+    def select(self, game, classes):
+        result = []
+        for kind in ("board", "pieces"):
+            prefix = kind + "-"
+            overrides = [name[len(prefix):] for name in classes if name.startswith(prefix)]
+            if len(overrides) > 1:
+                raise PluginError(f"chess {game}: choose one {kind} theme per block")
+            name = overrides[0] if overrides else self.defaults.get(game, {}).get(kind, DEFAULT)
+            result.append(self.resolve(game, kind, name))
+        return result