Kalonji Guide

1. App basics

• Open & run notebooks. Open any Jupyter .ipynb file — no conversion. Pick your interpreter (system Python, conda env, or virtualenv) in the sidebar, hit Start kernel, and run cells. Sessions persist until you restart the kernel.
• Cells. Code cells run Python with inline plots, tables, and tracebacks. Markdown cells preview rich text — press Shift+Enter to render, Enter to edit again. Save with Ctrl+S.
• AI help. The sidebar chat explains errors and answers questions; ghost completions suggest code as you type. Completions start paused — enable them with the Pause completions checkbox in AI settings, or toggle anytime with Ctrl+Shift+P.
• Share a notebook. Save ▾ → Export HTML… produces a single self-contained, print-friendly file with code highlighting and outputs embedded.

2. Rendering books: the idea

A Kalonji book is a static website built from your saved notebooks: one HTML page per chapter plus a landing page with navigation and a table of contents. Crucially, code is never executed during a build — the renderer reads the outputs already stored in each .ipynb file and publishes them as-is. No Python environment is needed to render.

Both entry points — the app and thestandalone tool — run the same renderer and produce identical output.

3. The book project file

A book is described by a Quarto-style YAML file (any name, .yml/.yaml). Chapters are notebook paths relative to the YAML file's folder:

project:
  type: book

book:
  title: "My Book"
  subtitle: "A notebook collection"
  author: "Author Name"
  chapters:
    - index.ipynb
    - chapters/introduction.ipynb
    - chapters/analysis.ipynb
    - appendix.md

format:
  html:
    toc: true
    code-fold: false
    theme: default

Only the keys above are supported. Unknown keys are ignored (reported with --verbose) — Kalonji implements a documented subset of Quarto, plus Kalonji-only features such as layout: side-by-side code/output columns (see §7), marked as such where documented.

Chapters can mix notebooks and plain Markdown: list an .md file and it renders as a chapter with the same Markdown engine (callouts, math, tables, heading anchors that feed the table of contents). Markdown chapters have no cells, so cell options (§7) don't apply to them.

4. Rendering in the app

1. Click the ▾ menu next to Save and choose Publish book… to open the book window on its Render tab.
2. Pick your book YAML file. The output folder defaults to a book folder next to it — change it if you like.
3. Optionally attach a custom CSS file, then hit Render. Progress shows per chapter; you can cancel mid-build.
4. When done, the app reports the chapter count (plus any warnings) and offers to open the book.

The site is written to <book-folder>/_site (landing page index.htmlplus one page per chapter). It works when opened straight from disk — no server needed.

5. Deploying a book

The desktop app can publish a rendered book to Kalonji Books, where readers can open it at a shareable .books.bioinfo.guru address. Render the book in the app first, or select an existing rendered site folder.

1. In the Publish book… window, open the Deploy tab.
2. Sign in with your email address. Kalonji Books emails you a one-time code to finish signing in.
3. Use the rendered site already selected, or choose its _site folder. A manually selected folder must contain index.html and .kalonji-book-manifest.json.
4. Choose a book address, such as my-book, and check that it is available. The resulting address will be my-book.books.bioinfo.guru.
5. Select Check limits and prepare ZIP, review the site and ZIP sizes, then choose Upload and publish.

Your account tier and current book-count and storage limits appear in the Deploy tab. To update a book, choose it under Your deployments and publish to the same address again. You can also open or delete published books there.

The standalone kalonji-book tool renders a site locally; publishing through Kalonji Books is currently available from the desktop app.

6. Rendering with the standalone tool

kalonji-book is distributed separately from the desktop app, so you can build books on machines without a display — CI servers included. It never opens a window.

kalonji-book render book.yml --book-dir ./book --clean --verbose
kalonji-book render book.yml --css custom.css

Exit codes tell scripts what happened:

7. Cell options reference

Control rendering per code cell with #| directives at the top of the cell (they override the same keys in cell metadata, and are hidden from the rendered output):

#| echo: false
#| fig-cap: "Observed values by category"

Cell options are book-build options: they affect rendered books, not the live notebook preview or the single-file HTML export. Unknown or mistyped options produce warnings, never silent failures.

8. Markdown & formatting

Markdown cells (and markdown outputs) support CommonMark plus:

• Tables, strikethrough, task lists, and fenced code blocks with syntax highlighting. Info strings are normalized (```Py → python).
• Math with $…$, $$…$$, \(…\), \[…\] — rendered with bundled KaTeX, fully offline, in the app and in books.
• Callout boxes (Quarto-style fenced divs):

::: {.callout-note}
Reminder text with *markdown* inside.
:::

::: {.callout-warning collapse="true"}
## Custom title
Collapsible warning body.
:::

Types are note, tip, important, warning, and caution. The title defaults to the type name, or take it from a leading heading or a title="…" attribute. Generic ::: {.class #id} … :::divs (nest with ::::) work too.

• Headings get stable anchor links and feed the per-page table of contents.
• Rich outputs: saved HTML is sanitized, ANSI colors are preserved, dataframes render as tables, and notebook attachments resolve automatically.
• Limits & safety: images over 2 MiB are externalized as files, images over 50 MiB are rejected, SVG output is skipped with a warning, and all user HTML is sanitized (no scripts, forms, or event handlers).

9. Output & troubleshooting

• The book opens from file:// — just open _site/index.html. No server required.
• Warnings don't fail a build (exit code stays 0). Read them: they flag unknown options, missing outputs, unsupported formats, and oversized pages.
• Rebuilding into a clean folder is byte-identical, and the GUI and CLI produce identical output.
• Your notebooks are never modified by a build — all processing happens in memory, and the previous site is preserved if a build fails or is cancelled.
• Stuck? Contact us with the warning text and your YAML file.