Notetype

A note type is the shape of a note: which fields it holds, and which cards those fields produce. Every note points at one.

Settle that shape before you publish. Renaming a field, or the note type itself, makes your next release arrive as a second note type with all of its notes skipped.

Stock note types

Four, and between them they cover most decks:

Each accepts an optional { name?, css? }. Renaming is the usual reason to pass name, so your note type sits alongside a recipient's own Basic rather than colliding with it.

A stock note type records which of Anki's own it came from, so Restore to Default knows which one it means without asking.

When none of those fit

The constructor takes NotetypeOptions, and needs a name, at least one field and at least one template:

import { Notetype } from "ankipack";const my_notetype = new Notetype({  name: "Vocab (Spanish)",  fields: [{ name: "Spanish" }, { name: "English" }, { name: "Note" }],  templates: [    {      name: "Card 1",      questionFormat: "{{Spanish}}",      answerFormat: '{{FrontSide}}<hr id="answer">{{English}}<br>{{Note}}',    },  ],});

The template bodies are Anki's own syntax, documented in field replacements. The css option is ordinary card styling, documented in styling and HTML. Neither is restated here.

sortFieldIndex must be an integer within the field count. Anki clamps an out-of-range value into bounds, so shipping one silently sorts on a field you did not choose.

FieldDef

Everything except name affects the editor rather than the finished card, and Customizing Fields describes them, apart from sticky and description. The exception is Notetype.basicTyping(), where fontName and fontSize also style the type-in-the-answer box on the card itself.

plainText is the checkbox Anki labels "Use HTML editor by default", set directly rather than inverted. Anki's name for editing raw HTML is the plain text editor, which is why the option and its label read as opposites.

Field name rules

Anki rewrites or refuses several kinds of field name on import and does not rewrite the {{Field}} references in the templates shipped alongside, so the two stop matching. ankipack refuses them at construction instead.

Whitespace here is Rust's definition, not JavaScript's. The two differ in both directions: U+0085 is whitespace to Rust but not to \s, and U+FEFF is the reverse.

Anki's manual advises against naming a field Tags, Type, Deck, Card or FrontSide, because those are special names in templates. ankipack does not refuse them. A field that shadows a special name wins: card generation and rendering both read your field, and the special value becomes unreachable from that note type's templates.

TemplateDef

Template names carry the same rules as note type names: not empty, no ", NFC only, no NUL or lone surrogate, and no two differing only in case.

Why renaming anything is expensive

Field and template ids are derived, not stored. Each is a hash of the note type's name, the member's own name, and its index. All three go into it, so renaming the note type changes every field and template id at once, and inserting a field anywhere but the end changes the id of everything after it.

Those ids are how Anki decides whether your note type is the one it saw last time, and pinning the note type's id does not protect them.

Card generation

How many cards a note produces is Anki's rule, and the manual explains it in Card Generation: a card exists for each template whose question side would not be blank. ankipack implements the same rule so that a package it builds already contains the cards Anki would have generated.

Three things decide what counts as blank, and each of them surprises somebody:

Empty is narrower and wider than it looks. A field counts as empty when it holds nothing but ASCII whitespace and <br> or <div> tags, which is what a WYSIWYG editor leaves behind in a field the user cleared. It does not count as empty when it holds a non-breaking or ideographic space, so a field of those still generates a card.

HTML comments do not count. Text inside <!-- ... --> is not content for this purpose.

{{{Field}}} resolves to Field. Leading braces are stripped before the name is read, so a triple-braced reference is the field, not a literal.

Separately from all of that, a template that fails to parse counts as generating nothing, rather than producing a card that renders an error.

A note is never left cardless. When nothing above generates a card, Anki gives the note one anyway, on the first template, so an incomplete note can be added and finished later.

Cloze

A cloze note type ignores template count and generates one card per distinct cloze number found in the fields.

Nesting is tracked ten deep.

The last three rows do not leave the note cardless either. The same fallback applies: one card, on the first template.