Продолжаем писать собственные плагины для Obsidian. Первую часть статьи можете найти здесь. В ней мы:
Выяснили, что можно писать плагины даже проще, чем это предлагает делать официальная документация
Написали три маленьких плагина, которые уже вовсю используются
на продакшенелично мнойГрозились написать четвертый финальный босс-плагин
Вот и приступим.
Плагин 4. Chess Viewer. Идея
Я не шахматист, но интересуюсь :) У меня есть заметки с шахматными зарисовками. И я определенно не один такой, поскольку в данный момент в Community plugins есть три плагина, позволяющих отображать в заметке шахматную доску с фигурами.
Я в свое время пользовался Obsidian Chess, но он использовал изображения в качестве фигур на доске, и они по какой-то причине очень долго прогружались на странице. Потом картинки фигур и вовсе исчезли:
Теперь я вообще не нахожу этот плагин в списке доступных для установки.
Существует еще пара решений, например, Chesser или Chess Study, но они уже скорее похожи на комбайны — там можно передвигать фигуры, брейнштормить, рисовать интерактивные стрелки и прочее. В общем сложно — мне нужно было что-то простое, надежное и не тормозящее.
Близким по духу является плагин Chessboard Viewer: view-only, фигуры рисуются в svg, есть лаконичные возможности подсветки значимых клеток и отрисовки статичных стрелок. Но у него есть два недостатка:
Мне не нравятся его фигуры и доска на вид
Я уже придумал свой бредовый способ дешево отображать фигуры, и это не SVG
Что за способ такой? Даже не знаю, как вам сказать — это ASCII-символы :) Вот они: ♔ ♕ ♖ ♗ ♘ ♙ ♚ ♛ ♜ ♝ ♞ ♟. И если их увеличить, то можно увидеть, что они ко всему прочему очень даже неплохи на вид как по мне:
Сначала я хотел отображать доску в аскетичном текстовом ASCII-only варианте. Но после некоторых потугов понял, что у меня будут непоправимые проблемы с отображением пустых белых и черных клеток. Поэтому было принято решение углубиться в нормальную html-css верстку, а в каждой клеточке уже рисовать свои ASCII-символы. Это все еще дешево, и основная фишка — ASCII-фигуры — все еще сохраняется, но зато это не будет выглядеть как дно.
Как описывать доску в заметке
Традиционно в таких плагинах для записи используется FEN-нотация. Это простой способ и доступный способ описать состояние шахматной доски одной строчкой. В базовом варианте FEN нотация выглядит так:
rnbqkbnr/pp1ppppp/2p5/8/4P3/8/PPPP1PPP/RNBQKBNR
Ряды отделены слешами /
. Буквы означают: r — ладья, n — конь, b — слон, q — ферзь, k — король, p — пешка. Большие буквы для белых, строчные для черных. Цифры указывают количество пустых клеток в ряду, идущих подряд. Далее у FEN-строки могут быть дополнительные приписки, касающиеся порядка хода, права рокировки и прочее, но они нас в разрезе нашей задачи не интересуют.
Мы хотим чтобы наш плагин работал так: мы в заметке будем писать FEN-нотацию в блоке кода с пометкой chess
:
```chess
8/3k1P2/2N5/b7/5K2/4r3/3P4/8
```
а в режиме просмотра заметка должна вместо блока кода отрисовать шахматную доску с фигурами, примерно так:
Приступаем к написанию
Итак, мы хотим найти все chess
-блоки в заметке и перезаписать их содержимое. Хм, вам это ничего не напоминает? Если вы читали предыдущую статью, то можете вспомнить, что это один-в-один сценарий нашего первого самого простого плагина: Guitar Tabs Viewer, который подменял "все тире на точки" в погоне за читабельностью гитарной табулатуры. Т.е. как минимум мы можем оттуда подглядеть, что подменой HTML на стадии пререндеринга страницы занимается метод Plugin.registerMarkdownCodeBlockProcessor()
, а заготовка плагина должна выглядеть как-то так:
class ChessLightweightPlugin extends obsidian.Plugin {
async onload() {
this.registerMarkdownCodeBlockProcessor('chess', (source, el, ctx) => {
// Render chess board
el.innerHTML = ...???
})
}
}
Остается лишь выяснить, что нужно положить в el.innerHTML
, и плагин будет готов! Из очевидного — в el.innerHTML
определенно должна лежать HTML-разметка доски: черно-белые клеточки. А в каждую из клеток можно при необходимости текстом записать имеющуюся у нее фигуру.
HTML-скелет
Тут в дело вступает щепотка говнокода, которая еще никому не помешала. Я просто не знаю, как еще описать то, что я сделал в качестве HTML-исполнения пустой доски, крепитесь:
const boardHtml =
`<div class="board">
<div class="row" id="row8">
<div class="square white" id="a8"></div>
<div class="square black" id="b8"></div>
<div class="square white" id="c8"></div>
<div class="square black" id="d8"></div>
<div class="square white" id="e8"></div>
<div class="square black" id="f8"></div>
<div class="square white" id="g8"></div>
<div class="square black" id="h8"></div>
</div>
<div class="row" id="row7">
<div class="square black" id="a7"></div>
<div class="square white" id="b7"></div>
<div class="square black" id="c7"></div>
<div class="square white" id="d7"></div>
<div class="square black" id="e7"></div>
<div class="square white" id="f7"></div>
<div class="square black" id="g7"></div>
<div class="square white" id="h7"></div>
</div>
...
<div class="row" id="row1">
<div class="square black" id="a1"></div>
<div class="square white" id="b1"></div>
<div class="square black" id="c1"></div>
<div class="square white" id="d1"></div>
<div class="square black" id="e1"></div>
<div class="square white" id="f1"></div>
<div class="square black" id="g1"></div>
<div class="square white" id="h1"></div>
</div>
</div>`
Ну вы поняли — мне было лень генерировать это через JS, к тому же я получил какую-то необъяснимую наглядность в этих восьмидесяти с копейками строках — будто на скелет пустой доски смотрю :)
Теперь мы можем перезаписать блок chess
-кода этой доской:
async onload() {
this.registerMarkdownCodeBlockProcessor('chess', (source, el, ctx) => {
el.innerHTML = boardHtml
})
}
Вот только даже проверять не нужно, чтобы понять, что мы таким образом заменили наши блоки кода в заметках на визуальное ничего — пустоту, поскольку у наших <div>
'ов еще нет визуального воплощения.
CSS
Давайте это исправлять. У меня получился вот такой css-файл, который должен визуализировать доску:
body {
--cell-size: 50px;
}
.board {
margin: 20px 0px 20px 0px;
}
.row {
display: flex;
flex-direction: row;
}
.square {
width: var(--cell-size);
height: var(--cell-size);
display: flex;
align-items: center;
justify-content: center;
}
.white {
background-color: color(srgb 0.944 0.944 0.944);
}
.black {
background-color: color(srgb 0.81333 0.81333 0.81333);
}
Ничего примечательного: даем клеткам размеры, красим их в свои цвета, выстраиваем их в ряды.
Я по-началу проверял работоспособность этих стилей через обычную пару файлов html-css в браузере, и оно работало. Но как теперь применить этот css в плагине? Очень просто — вы создаете файл с именем styles.css
(именно таким именем!) и просто подкладываете его в папку, где лежит main.js
. Ничего дополнительного делать не нужно, стили подхватятся сами.
Делаем проверку на простой заметке:
# Two rooks mate
```chess
8/8/4k3/R7/7R/8/8/6K1
```
```chess
8/4k3/7R/R7/8/8/8/6K1
```
Получаем:
Работает! Я не даром указал в классе .board
отступы сверху и снизу: margin: 20px 0px 20px 0px;
. Без этого две доски склеиваются в единое полотно.
Доски рисуются, но содержимое chess
-блоков игнорируется, а сами доски пусты. Пока что продолжим игнорировать FEN-записи — до этого мы еще дойдем. А сейчас на скорую руку разместим фигуры прямо хардкодом в HTML:
const whitesBoardHtml =
`<div class="board">
<div class="row" id="row8">
<div class="square white" id="a8">♞</div>
<div class="square black" id="b8"></div>
<div class="square white" id="c8">♗</div>
<div class="square black" id="d8"></div>
<div class="square white" id="e8">♛</div>
<div class="square black" id="f8"></div>
<div class="square white" id="g8">♔</div>
<div class="square black" id="h8"></div>
</div>
<div class="row" id="row7">
<div class="square black" id="a7"></div>
<div class="square white" id="b7">♟</div>
<div class="square black" id="c7"></div>
<div class="square white" id="d7">♚</div>
<div class="square black" id="e7"></div>
<div class="square white" id="f7">♖</div>
<div class="square black" id="g7"></div>
<div class="square white" id="h7">♝</div>
</div>
...
Смотрим на результат:
Маловато, нужно увеличить размер шрифта. И мне уже виднеется нечто странное... Увеличиваем:
.square {
...
font-size: calc(var(--cell-size) * 0.85);
}
смотрим:
Что происходит?! Почему черная пешка такая? Как оказалось в процессе разбирательства, это баг ASCII, а точнее конкретно символа черной пешки. Зависит от того, кто рендерит шрифт, но в 90% случаев с черной пешкой есть проблемы во всех программах — она крупнее остальных и синяя. И в Obsidian тоже. Но при случайных обстоятельствах вам может повезти. Мне вот тоже как-то повезло, и банальное:
.square {
...
font-family: serif;
}
исправило ситуацию:
Пешка пришла в норму. Странно, но ладно. Возможно, это работает только в рамках Obsidian. Но работает.
Очерчиваем бизнес-логику
Прежде чем приступить к непосредственной бизнес-логике, ненадолго вернемся к самому плагину. Мы знаем HTML-структуру доски, поэтому нам уже заранее известно, как в нее "вставлять" фигуры: просто вписывая в <div>
клетки текст с фигурой. Примерно так:
async onload() {
this.registerMarkdownCodeBlockProcessor('chess', (source, el, ctx) => {
// Parse code
const data = new BoardData(source)
// Render chess board
el.innerHTML = boardHtml
// Fill chess board with pieces
for (const [addr, piece] of Object.entries(data.addresses)) {
const cell = el.querySelector('[id=' + addr + ']')
if (cell) {
cell.innerText = piece
}
}
})
}
Смотрите, мы заранее заложились на мифическую BoardData
, которой еще нет, но мы знаем, что у нее должны быть:
Конструктор, принимающий в себя source-HTML
Поле
addresses
— словарик вида{адрес; ACSII-фигура}
Осталось лишь реализовать BoardData
, и плагин должен заработать.
Парсим и отображаем FEN
Требования к парсящему классу у нас уже сформированы в предыдущем разделе: наша конечная цель — получить поле-словарь addresses
с адресами фигур. Делаем:
class BoardData {
// map of {address piece} like {'a4': '♞'}
addresses = {}
constructor(source) {
const lines = source.split('\n')
const line = lines?.[0]
this.#parseFen(line)
}
#parseFen(fen) {
const rowLines = fen.split('/')
let row = 8
let col = 1
this.addresses = {}
for (const rowLine of rowLines) {
col = 1
for (const ch of rowLine) {
if (isLetter(ch)) {
let piece = ''
if (ch == 'p') piece = '♟'
else if (ch == 'r') piece = '♜'
else if (ch == 'n') piece = '♞'
else if (ch == 'b') piece = '♝'
else if (ch == 'q') piece = '♛'
else if (ch == 'k') piece = '♚'
else if (ch == 'P') piece = '♙'
else if (ch == 'R') piece = '♖'
else if (ch == 'N') piece = '♘'
else if (ch == 'B') piece = '♗'
else if (ch == 'Q') piece = '♕'
else if (ch == 'K') piece = '♔'
this.addresses[getAddress(row, col)] = piece
col += 1
} else {
col += parseInt(ch, 10)
}
}
row -= 1
}
}
}
Этот класс использует щепотку вспомогательных функций:
function isLetter(c) {
return c.toLowerCase() != c.toUpperCase()
}
function rowToString(r) {
return r.toString()
}
function colToString(c) {
return String.fromCharCode('a'.charCodeAt() + c - 1)
}
function getAddress(r, c) {
return colToString(c) + rowToString(r)
}
Теперь плагин должен рисовать шахматные позиции в соответствии с FEN-описанием. Достаем нашу старую заготовку:
# Two rooks mate
```chess
8/8/4k3/R7/7R/8/8/6K1
```
```chess
8/4k3/7R/R7/8/8/8/6K1
```
Заметка приобретает вид:
Ура — вот мы и добились работоспособного отображения доски и фигур, я нас поздравляю.
Подсветка клеток
У нас есть базовое отображение доски, но отсутствует одна существенная для шахматных зарисовок вещь — возможность помечать клетки цветами, чтобы можно было яснее выражать мысль и развитие событий на доске. Вот как, например, это реализовано в chess.com:
Я хотел бы иметь в арсенале зеленый, красный и синий цвета. Так же есть требование, чтобы цвета ложились на клетку с некоторой прозрачностью, чтобы все еще можно было отличить белую и черную клетки, даже если они подсвечены. Так же подошел бы эффект "виньетка".
Раскрашивание клетки будем реализовывать через программное добавление подсвеченной клетке одного из трех специальных классов: .green-hihglight
, .red-hihglight
, .blue-hihglight
:
.red-hihglight {
box-shadow: 0 0 calc(var(--cell-size)*2) rgba(255, 0, 0, 0.75) inset;
}
.blue-hihglight {
box-shadow: 0 0 calc(var(--cell-size)*2) rgba(0, 0, 255, 0.4) inset;
}
.green-hihglight {
box-shadow: 0 0 calc(var(--cell-size)*2) rgba(0, 255, 0, 0.5) inset;
}
Как видите, в классе присутствует некий box-shadow
со странными вычислениями. Это результат моих исследований наложения эффекта "виньетка" на клетку разными цветами. По итогу получилась не то чтобы виньетка, но результат меня устроил — скоро увидите.
Для начала нам стоит понять, как описывать информацию о выделенных клетках в Obsidian-заметке. Я пришел к той же схеме, какой пользовались все известные мне шахматные плагины:
```chess
fen: rnbqkbnr/pp2pppp/2p5/3p4/3PP3/8/PPP2PPP/RNBQKBNR
green: d7 d5
red: e4
```
А это значит что? Что у нас усложнится парсер класса BoardData
. Так же у него прибавится полей:
class BoardData {
...
// arrays of [address] like [e2, e4]
reds = []
greens = []
blues = []
constructor(source) {
const lines = source.split('\n').map(line => line.trim())
for (const line of lines) {
if (line.startsWith('fen:')) {
const fen = removePrefix(line, 'fen:').trim()
this.#parseFen(fen)
} else if (line.startsWith('red:')) {
const redLine = removePrefix(line, 'red:').trim()
this.reds = redLine.split(' ')
} else if (line.startsWith('green:')) {
const greenLine = removePrefix(line, 'green:').trim()
this.greens = greenLine.split(' ')
} else if (line.startsWith('blue:')) {
const blueLine = removePrefix(line, 'blue:').trim()
this.blues = blueLine.split(' ')
} else {
if (line.contains(':')) {
continue
}
this.#parseFen(line)
}
}
}
...
}
А в плагин допишем использование новых распаршенных данных:
class ChessLightweightPlugin extends obsidian.Plugin {
async onload() {
this.registerMarkdownCodeBlockProcessor('chess', (source, el, ctx) => {
// Parse code
const data = new BoardData(source)
...
for (const addr of data.reds) {
el.querySelector('[id=' + addr + ']').classList.add('red-hihglight')
}
for (const addr of data.greens) {
el.querySelector('[id=' + addr + ']').classList.add('green-hihglight')
}
for (const addr of data.blues) {
el.querySelector('[id=' + addr + ']').classList.add('blue-hihglight')
}
})
}
}
Все, у нас все готово. Теперь доски в заметках могут показывать больше информации о происходящем:
Не знаю как вам, а я доволен результатом. Для полного счастья мне не хватает только одного...
Госпереворот доски
Предыдущая картинка описывает дебют Каро-Канн за черных. Его намного удобнее наблюдать со стороны черных. Хочу:
```chess
...
flipBoard: true
```
Как парсить это поле, я уж не стану показывать, это тривиальная задача. Задача чуть сложнее — как реально перевернуть доску? Применить transform
? Программно переписать адреса клеток? Тут, как водится, в дело вступает щепотка говнокода, которая еще никому не помешала:
const whitesBoardHtml =
`<div class="board">
<div class="row" id="row8">
<div class="square white" id="a8"></div>
<div class="square black" id="b8"></div>
<div class="square white" id="c8"></div>
<div class="square black" id="d8"></div>
<div class="square white" id="e8"></div>
<div class="square black" id="f8"></div>
<div class="square white" id="g8"></div>
<div class="square black" id="h8"></div>
</div>
...
<div class="row" id="row1">
<div class="square black" id="a1"></div>
<div class="square white" id="b1"></div>
<div class="square black" id="c1"></div>
<div class="square white" id="d1"></div>
<div class="square black" id="e1"></div>
<div class="square white" id="f1"></div>
<div class="square black" id="g1"></div>
<div class="square white" id="h1"></div>
</div>
</div>`
const blacksBoardHtml =
`<div class="board">
<div class="row" id="row1">
<div class="square white" id="h1"></div>
<div class="square black" id="g1"></div>
<div class="square white" id="f1"></div>
<div class="square black" id="e1"></div>
<div class="square white" id="d1"></div>
<div class="square black" id="c1"></div>
<div class="square white" id="b1"></div>
<div class="square black" id="a1"></div>
</div>
...
<div class="row" id="row8">
<div class="square black" id="h8"></div>
<div class="square white" id="g8"></div>
<div class="square black" id="f8"></div>
<div class="square white" id="e8"></div>
<div class="square black" id="d8"></div>
<div class="square white" id="c8"></div>
<div class="square black" id="b8"></div>
<div class="square white" id="a8"></div>
</div>
</div>`
Не, ну а что? Всего лишних восемьдесят строк позора, и вот вы уже пишете в плагине:
async onload() {
this.registerMarkdownCodeBlockProcessor('chess', (source, el, ctx) => {
// Parse code
const data = new BoardData(source)
...
// Render chess board
el.innerHTML = data.flipBoard ? blacksBoardHtml : whitesBoardHtml
...
})
}
И вот вы уже комфортно сидите на месте черных:
Все?
Все :)
Могли бы мы сделать плагин еще лучше? Безусловно! В данный момент на мне висит канбан-доска с вот таким списком TODO для этого плагина:
Когда-нибудь у меня доберутся руки закрыть и все эти задачи, но на сегодняшний момент я могу пользоваться плагином, как есть, а вы и так почерпнули из этой статьи ту единственную мысль, что я хотел донести:
Просто подложите styles.css в папку плагина!
Да, фактически, все остальное в статье это не про плагиностроение, а про верстку, бизнес-логику и щепотку вау-эффекта, когда ваша заметка из текста превращается в мини-веб-страничку. Так что считайте, что это моя небольшая афера.
На этом наша эпопея с написанием плагинов для Obsidian заканчивается, я желаю вам успехов в написании собственных плагинов для Obsidian, ведь теперь вы знаете, что это совершенно несложно, но очень весело, а главное — может быть полезно конкретно в ваших повседневных операциях с заметками.
Как и обещал, прикладываю ссылку на GitHub, если кто-то захочет поисследовать или использовать написанные нами здесь плагины.