AnkiIO 1.0.1

AnkiIO

Browse the API documentation →

Sample projects · Formats and safety · MIT license

AnkiIO is a stable, open-source .NET 10 library for creating, validating, importing, editing, and exporting Anki deck data. Its 1.0 API covers a format-independent deck model, practical helpers for common note types, deterministic JSON, a CrowdAnki-inspired interchange format, media, scheduling state, diagnostics, and guarded legacy APKG I/O.

AnkiIO is maintained by Julius Jacobsohn.

AnkiIO is not affiliated with, endorsed by, or sponsored by Ankitects, Anki, AnkiDroid, or CrowdAnki. “Anki” is a trademark of Ankitects Pty Ltd.

Compatibility and scope

The 1.0 compatibility target is deliberately narrow: Anki 26.05 (build e64c6b1a), collection schema 18, and the v3 scheduler. The library targets net10.0, so consumers require the .NET 10 runtime or a compatible later runtime. Repository builds use the .NET 10 SDK pinned by global.json.

APKG export writes the legacy collection.anki2 representation, which is accepted by the isolated Anki 26.05 compatibility test. Native JSON and CrowdAnki-inspired JSON support documented subsets rather than every field used by every Anki add-on. Unknown native-JSON properties are retained where the API documents preservation.

AnkiIO does not write a live Anki profile. Modern collection.anki21b generation, filtered decks, arbitrary schema-18 database mutation, and complete review-log or deck-configuration preservation are outside the 1.0 support boundary. Read formats, compatibility, and safety before processing untrusted packages or important data.

Install

The package version is defined once in Version.props. After the package is published:

dotnet add package AnkiIO

To consume a local package from this checkout:

dotnet pack src/AnkiIO/AnkiIO.csproj --configuration Release --output artifacts/packages
dotnet add package AnkiIO --source artifacts/packages

Quick start

using AnkiIO;

var deck = new AnkiDeck("German Vocabulary");
deck.AddBasicNote("Haus", "house", tags: ["german", "vocabulary"]);

await AnkiPackageWriter.WriteAsync(deck, "GermanVocabulary.apkg");

A note stores information; a card is a study prompt generated from a note template. Scheduling belongs to cards. New cards receive a safe default schedule, while explicit scheduling is validated and rejected when its queue/type combination is inconsistent.

Highlights

• Decks and nested Parent::Child hierarchies
• Notes, ordered fields, custom note types, card templates, CSS, tags, GUIDs, and cards
• Helpers for Basic, Basic-and-reversed, and Cloze notes, including safe cloze-markup construction
• Safe new-card initialization and explicit, validated scheduling state
• Streaming media ingestion with SHA-256 integrity metadata
• Deterministic, versioned native JSON and CrowdAnki-inspired JSON
• Guarded APKG import/export with configurable archive limits and path-traversal defenses
• Structured validation diagnostics and documented unknown-data preservation
• Read-only installed-Anki detection and opt-in, isolated local compatibility testing

See the samples for focused programs and the German–English showcase for a complete custom deck with note types, media, tags, and verification.

Build and verify

Install the SDK selected by global.json, then run the complete local gate:

./build/build.ps1

That script performs locked restore, formatting verification, a Release build, sample and benchmark builds, portable tests, coverage enforcement, package creation and validation, a clean package-consumer round trip, and a strict Doxygen build. The same checks run in CI on Linux, Windows, and macOS.

The local-Anki compatibility suite is intentionally opt-in because it requires an installed Anki instance:

dotnet test tests/AnkiIO.CompatibilityTests --configuration Release --filter Category=LocalAnkiCompatibility

Local-Anki tests use unique temporary workspaces and never modify the normal profile. API documentation is generated by Doxygen from source comments and source-resident guides; do not edit generated HTML.

Releasing

Versioning follows Semantic Versioning. To release, update the changelog and change <Version> in Version.props. Merging or pushing that version change to main runs the complete release gate, waits for the same commit's Linux, Windows, and macOS CI jobs, creates the matching vX.Y.Z tag and GitHub release, and publishes the package through NuGet Trusted Publishing. The workflow can still be dispatched manually with its release switch disabled to produce and validate artifacts without publishing them.

Contributions use focused pull requests and must preserve the documented 1.x compatibility contract; see CONTRIBUTING.md. Security reports follow SECURITY.md. Licensed under MIT.