AnkiIO.AnkiDeck Class Reference

Builds one named deck hierarchy and acts as the root for validation and export. More...

Public Member Functions
	AnkiDeck (string name, long? id=null)
	Initializes a top-level deck with an empty note and subdeck collection.
AnkiDeck	AddSubdeck (string name, long? id=null)
	Creates and adds a direct child deck.
AnkiNote	AddNote (AnkiNoteType noteType, IReadOnlyDictionary< string, string > fields, IEnumerable< string >? tags=null, string? guid=null, long? id=null)
	Adds a note and generates its cards using safe new-card scheduling.
bool	RemoveNote (AnkiNote note)
	Removes a note and its generated cards from this deck.
IEnumerable< AnkiDeck >	Traverse ()
	Enumerates the complete hierarchy in the same deterministic order used by writers.
AnkiNote	AddBasicNote (string front, string back, IEnumerable< string >? tags=null, string? guid=null, long? id=null)
	Adds a conventional Basic note that generates one front-to-back card.
AnkiNote	AddBasicAndReversedNote (string front, string back, IEnumerable< string >? tags=null, string? guid=null, long? id=null)
	Adds a conventional Basic (and reversed) note that generates front-to-back and back-to-front cards.
AnkiNote	AddClozeNote (string text, string extra="", IEnumerable< string >? tags=null, string? guid=null, long? id=null)
	Adds a conventional Cloze note and generates one card for each distinct positive cloze index.

Properties
long	Id [get]
	Gets the persisted identity used by cards and package metadata to refer to this deck.
string	Name [get]
	Gets this deck's local display-name segment, not its full hierarchy path.
string	Description = string.Empty [get, set]
	Gets or sets the description Anki may show on the deck overview screen.
IDictionary< string, string >	Metadata = new Dictionary<string, string>(StringComparer.Ordinal) [get]
	Gets application-defined string metadata for AnkiIO native-JSON round trips.
IDictionary< string, JsonElement >	UnknownData = new Dictionary<string, JsonElement>(StringComparer.Ordinal) [get]
	Gets unknown native-JSON deck properties retained without interpretation.
AnkiMediaCollection	Media [get]
	Gets media filenames and payloads contributed by this deck during package export.
IReadOnlyList< AnkiDeck >	Subdecks [get]
	Gets only the direct children created below this deck.
IReadOnlyList< AnkiNote >	Notes [get]
	Gets notes assigned directly to this deck.

Detailed Description

Builds one named deck hierarchy and acts as the root for validation and export.

AnkiIO stores each hierarchy segment separately: create Languages::German by constructing Languages and calling AddSubdeck with German. Notes belong to the deck on which they were added, while individual cards may reference another deck through AnkiCard.DeckId. Package and validation operations starting at a root include all descendants.

The object graph is intentionally mutable for build/import workflows but is not thread-safe. Complete custom note types before adding notes, register every referenced media filename, and validate before export. AnkiIO creates package files; it never needs to write a live Anki profile.

var languages = new AnkiDeck("Languages");
var german = languages.AddSubdeck("German");
german.AddBasicNote("Haus", "house", tags: ["noun"]);
german.Media.AddBytes("house.svg", svgBytes);
 
await AnkiPackageWriter.WriteAsync(languages, "Languages.apkg");

Definition at line 30 of file AnkiDeck.cs.

Constructor & Destructor Documentation

AnkiDeck()

AnkiIO.AnkiDeck.AnkiDeck ( string name, long? id = null )

inline

Initializes a top-level deck with an empty note and subdeck collection.

Parameters

name	A non-empty local deck segment; use AddSubdeck to build hierarchy.
id	An optional stable numeric deck ID for repeatable imports; when omitted, AnkiId.New generates one.

The deck starts with no notes, subdecks, or media. The public constructor creates a hierarchy root; child decks created with AddSubdeck share the root's conventional-note-type cache so helper-created notes reuse one Basic, reversed, or Cloze model instead of duplicating models in Anki.

Exceptions

ArgumentException	name is blank or contains Anki's :: hierarchy separator.
ArgumentNullException	name is null.

Definition at line 50 of file AnkiDeck.cs.

Member Function Documentation

AddBasicAndReversedNote()

AnkiNote AnkiIO.AnkiDeck.AddBasicAndReversedNote ( string front, string back, IEnumerable< string >? tags = null, string? guid = null, long? id = null )

inline

Adds a conventional Basic (and reversed) note that generates front-to-back and back-to-front cards.

Parameters

front	The first side of the note. Anki HTML and media references are preserved as supplied.
back	The second side of the note. Anki HTML and media references are preserved as supplied.
tags	Optional case-sensitive note tags without whitespace. Exact duplicates are collapsed using ordinal comparison.
guid	An optional stable Anki GUID for repeatable imports; when omitted, a new GUID is generated.
id	An optional stable numeric note ID; when omitted, a new ID is generated.

Returns

The added note, including its two newly generated cards in front-to-back then back-to-front order.

Unless an exact conventional definition has already been observed, the first call in a deck hierarchy creates a Basic (and reversed card) note type. Later calls on the root or any subdeck reuse the same frozen definition. This helper always creates both directions; for a reverse card controlled by an extra field, use AddNote(AnkiNoteType, IReadOnlyDictionary<string, string>, IEnumerable<string>?, string?, long?) for custom templates or conditional reverse-card generation.

var deck = new AnkiDeck("Vocabulary");
deck.AddBasicAndReversedNote("gehen", "to go");

Exceptions

ArgumentNullException	front or back is null.
ArgumentException	tags contains a blank or whitespace-containing tag.

Definition at line 307 of file AnkiDeck.cs.

AddBasicNote()

AnkiNote AnkiIO.AnkiDeck.AddBasicNote ( string front, string back, IEnumerable< string >? tags = null, string? guid = null, long? id = null )

inline

Adds a conventional Basic note that generates one front-to-back card.

Parameters

front	The card question. Anki HTML and media references are preserved as supplied.
back	The card answer. Anki HTML and media references are preserved as supplied.
tags	Optional case-sensitive note tags without whitespace. Exact duplicates are collapsed using ordinal comparison.
guid	An optional stable Anki GUID for repeatable imports; when omitted, a new GUID is generated.
id	An optional stable numeric note ID; when omitted, a new ID is generated.

Returns

The added note, including its single newly generated card.

Unless an exact conventional definition has already been observed, the first call in a deck hierarchy creates a Basic note type. Later calls on the root or any subdeck reuse it, including after a supported import round trip. Creating the first note freezes the cached type. Use the low-level overload when custom fields/templates/CSS are required; a conventional helper type cannot be modified after use.

var deck = new AnkiDeck("German");
deck.AddBasicNote("Haus", "house", tags: ["noun"]);
await AnkiPackageWriter.WriteAsync(deck, "German.apkg");

Exceptions

ArgumentNullException	front or back is null.
ArgumentException	tags contains a blank or whitespace-containing tag.

Definition at line 261 of file AnkiDeck.cs.

AddClozeNote()

AnkiNote AnkiIO.AnkiDeck.AddClozeNote ( string text, string extra = "", IEnumerable< string >? tags = null, string? guid = null, long? id = null )

inline

Adds a conventional Cloze note and generates one card for each distinct positive cloze index.

Parameters

text	The cloze-formatted main text, for example "The capital is {{c1::Berlin}}.". Use AnkiCloze.Wrap(string, int, string?) to construct individual deletions safely.
extra	Optional supporting HTML shown on the answer side.
tags	Optional case-sensitive note tags without whitespace. Exact duplicates are collapsed using ordinal comparison.
guid	An optional stable Anki GUID for repeatable imports; when omitted, a new GUID is generated.
id	An optional stable numeric note ID; when omitted, a new ID is generated.

Returns

The added note and its newly generated cloze cards, ordered by cloze index.

Repeating the same cloze index produces one card containing all deletions with that index. Different indexes produce separate cards. The conventional frozen Cloze note type is shared by all helper calls in this deck hierarchy, including when an exact conventional definition was reconstructed by a supported importer. This convenience method accepts balanced, non-nested deletions with an optional single hint. It rejects empty answers, non-positive or unrepresentable indexes, nested braces, and additional :: separators. Prefer AnkiCloze.Wrap(string, int, string?) when constructing deletions programmatically. Use AddNote(AnkiNoteType, IReadOnlyDictionary<string, string>, IEnumerable<string>?, string?, long?) to create an initially empty cloze note or to use advanced nested syntax, custom fields, templates, or CSS.

var deck = new AnkiDeck("Geography");
var answer = AnkiCloze.Wrap("Berlin", hint: "city");
deck.AddClozeNote($"Germany's capital is {answer}.");

Exceptions

ArgumentNullException	text or extra is null.
ArgumentException	text contains no valid deletion, or its simple cloze markup is empty, unbalanced, nested, ambiguous, non-positive, or outside the range supported by int; or tags contains a blank or whitespace-containing tag.

Definition at line 364 of file AnkiDeck.cs.

AddNote()

AnkiNote AnkiIO.AnkiDeck.AddNote ( AnkiNoteType noteType, IReadOnlyDictionary< string, string > fields, IEnumerable< string >? tags = null, string? guid = null, long? id = null )

inline

Adds a note and generates its cards using safe new-card scheduling.

Parameters

noteType	The fully configured definition whose fields/templates will be frozen by this operation.
fields	Values keyed by exact, case-sensitive field name. Omitted defined fields become empty strings; unknown keys fail. Values may contain Anki HTML/template text and are not sanitized.
tags	Optional case-sensitive note tags. Tags cannot be blank or contain whitespace.
guid	An optional stable Anki import GUID used to recognize the note across imports.
id	An optional persisted numeric note ID; omit it for newly authored content.

Returns

The attached note with cards generated immediately for its templates or current cloze indexes.

The note retains noteType by reference and freezes it after argument validation, preventing later field/template/CSS changes from invalidating existing notes. Standard types produce one card per template. Cloze types produce one card per distinct positive marker in the Text field. An exact conventional Basic, reversed, or Cloze definition is reused by later helper calls in this hierarchy.

Exceptions

ArgumentNullException	noteType or fields is null.
ArgumentException	fields contains a name not defined by noteType , tags contains a blank or whitespace-containing tag, or a Cloze Text value contains a numeric index outside the range supported by int.

Definition at line 171 of file AnkiDeck.cs.

AddSubdeck()

AnkiDeck AnkiIO.AnkiDeck.AddSubdeck ( string name, long? id = null )

inline

Creates and adds a direct child deck.

Parameters

name	A non-empty local name segment without Anki's :: hierarchy separator.
id	An optional stable numeric deck ID for repeatable imports; when omitted, AnkiId.New generates one.

Returns

The newly created child deck, ready for notes or further nested decks.

Sibling names are compared without regard to case, matching Anki's practical hierarchy behavior. The returned child shares conventional Basic/reversed/Cloze definitions with the root. Supplying German::Verbs is invalid; call AddSubdeck("German").AddSubdeck("Verbs") instead.

Exceptions

ArgumentException	name is blank, contains ::, or duplicates an existing direct child name ignoring case.
ArgumentNullException	name is null.

Definition at line 137 of file AnkiDeck.cs.

RemoveNote()

bool AnkiIO.AnkiDeck.RemoveNote ( AnkiNote note )

inline

Removes a note and its generated cards from this deck.

Parameters

note	The note to remove.

Returns

true when the same note instance was directly owned by this deck; otherwise, false.

Removal is by object identity/equality from this direct list only; subdecks are not searched. The detached note and cards remain usable in memory, and media registrations or note-type definitions are not removed automatically.

Definition at line 189 of file AnkiDeck.cs.

Traverse()

IEnumerable< AnkiDeck > AnkiIO.AnkiDeck.Traverse ( )

inline

Enumerates the complete hierarchy in the same deterministic order used by writers.

Returns

A lazy depth-first sequence: this deck, then each child subtree in insertion order.

The sequence is live, not a snapshot. Do not add subdecks while enumerating it. Use it when aggregating notes or media across a hierarchy; Notes and Subdecks deliberately expose only direct ownership.

Definition at line 225 of file AnkiDeck.cs.

Property Documentation

Description

string AnkiIO.AnkiDeck.Description = string.Empty

getset

Gets or sets the description Anki may show on the deck overview screen.

HTML stored verbatim; the default is an empty string.

AnkiIO does not sanitize, render, or execute this content. Do not insert untrusted HTML without applying the content policy appropriate to your application. Legacy APKG and native JSON preserve the modeled value; other adapters may omit it.

Definition at line 90 of file AnkiDeck.cs.

Id

long AnkiIO.AnkiDeck.Id

get

Gets the persisted identity used by cards and package metadata to refer to this deck.

The caller-supplied ID, or a process-generated positive ID.

Preserve an imported ID when updating the same logical deck. Explicit IDs must be unique across the entire exported hierarchy; use AnkiId.FromStableValue for deterministic external mappings.

Definition at line 77 of file AnkiDeck.cs.

Media

AnkiMediaCollection AnkiIO.AnkiDeck.Media

get

Gets media filenames and payloads contributed by this deck during package export.

A mutable media collection created with the deck. Package writing aggregates media from this deck and every descendant. A field such as <img src="house.png"> is only text until a payload named house.png is registered. Registrations are not copied between parent and child decks.

Definition at line 111 of file AnkiDeck.cs.

Metadata

IDictionary<string, string> AnkiIO.AnkiDeck.Metadata = new Dictionary<string, string>(StringComparer.Ordinal)

get

Gets application-defined string metadata for AnkiIO native-JSON round trips.

A live, mutable, case-sensitive dictionary. Legacy APKG and CrowdAnki-inspired writers do not preserve these values.

Definition at line 96 of file AnkiDeck.cs.

Name

string AnkiIO.AnkiDeck.Name

get

Gets this deck's local display-name segment, not its full hierarchy path.

A non-empty segment that never contains Anki's :: hierarchy separator.

Definition at line 81 of file AnkiDeck.cs.

Notes

IReadOnlyList<AnkiNote> AnkiIO.AnkiDeck.Notes

get

Gets notes assigned directly to this deck.

A live, non-castable read-only view in insertion order. Descendant notes are not included.

Add through a convenience method or AddNote so note-type freezing and card generation occur.

Definition at line 120 of file AnkiDeck.cs.

Subdecks

IReadOnlyList<AnkiDeck> AnkiIO.AnkiDeck.Subdecks

get

Gets only the direct children created below this deck.

A live, non-castable read-only view in insertion order; use Traverse for all descendants.

Definition at line 115 of file AnkiDeck.cs.

UnknownData

IDictionary<string, JsonElement> AnkiIO.AnkiDeck.UnknownData = new Dictionary<string, JsonElement>(StringComparer.Ordinal)

get

Gets unknown native-JSON deck properties retained without interpretation.

A live, mutable, case-sensitive dictionary of cloned JSON values. Preservation is limited to unknown properties on deck objects in the native AnkiIO JSON format; it is not a general APKG/protobuf preservation mechanism.

Definition at line 103 of file AnkiDeck.cs.

---

The documentation for this class was generated from the following file:

• src/AnkiIO/AnkiDeck.cs