Ankipan

Sharing decks: the .ankipan file

An Ankipan deck can be exported as one file and published anywhere — a GitHub repository, a website, a chat. Anyone with Ankipan opens the file and gets the deck. The file carries the deck's content only: its columns, card kinds and rows. Review history stays with the person who studied.

Getting a deck

  • From a link. Tap + → Add a shared deck → From a link… and paste the link to the file. A link to the file's page on GitHub works too; Ankipan finds the raw file behind it.
  • From a file. If you have the file in Files, iCloud Drive or AirDrop, tap it and choose Ankipan, or tap + → Add a shared deck → Open a file….
  • From Safari. Download the file, open it from the downloads list and choose Ankipan.

You see what's in the deck and who made it before adding it. Adding the same deck again makes a separate copy — opening a file never changes a deck you already have.

Updates

A deck added from a link is a subscribed deck: it follows its author. Ankipan checks the same address now and then (and whenever you open the deck's page), and when the file there has a higher version it shows what changed — words added, changed and removed — and updates only when you confirm. Your progress and the words you've hidden carry over; words the author removed go, unless you choose to keep them.

A followed deck's words aren't edited in Ankipan — they're the author's. Long-press it and choose View deck to see who made it, which version you have and whether a newer one is out (Check for Updates asks again). You can hide words you don't want to study (swipe a word there, or Hide This Word while studying); hidden words keep their progress and stay hidden after updates. Unsubscribe on that page makes the deck your own to edit, and no update reaches it after that.

Only a file from the very address the deck came from, with the same id and a higher version, can update it. A file from anywhere else — AirDrop, Messages, another site — is always added as a new deck.

The name, author and description in a file are simply what that file says, the way an email's "from" line is. Ankipan cannot verify them, so treat a deck file the way you would any other file someone sends you: add ones from people and places you trust.

Publishing a deck

Long-press the deck's pile on the home screen and choose Share deck…. Fill in your name and a line about the deck, then share the file. Put it on GitHub, send it by AirDrop or Messages — the file is the same. Exporting again after editing the deck produces a new version of the same package; Ankipan uses that to offer updates in the future.

The format

The file is JSON, so it can be written or edited by hand. id, name, fields, kinds and notes are required; everything else is optional.

{
  "format": 1,
  "id": "9B5D8C1E-2A4F-4E62-9C7B-1F0A3D6E8B21",
  "version": 1,
  "name": "JLPT N5 Vocabulary",
  "description": "The 60 most common N5 words with kana readings.",
  "author": "Zeyi",
  "homepage": "https://github.com/zeyi/decks",
  "tags": "n5",
  "icon": { "symbol": "character.book.closed", "tint": "orange" },
  "fields": [
    { "name": "Word", "language": "ja-JP", "options": { "pronounceWith": "Reading" } },
    { "name": "Reading", "language": "ja-JP", "options": { "script": "kana" } },
    { "name": "Meaning", "language": "en-US" }
  ],
  "kinds": [
    { "ord": 0, "name": "Recognition", "prompt": ["Word"], "answer": ["Reading", "Meaning"],
      "read": { "back": "Reading" } },
    { "ord": 1, "name": "Production", "prompt": ["Meaning"], "answer": ["Word", "Reading"],
      "check": { "field": "Reading", "mode": "typed" }, "read": { "back": "Word" } }
  ],
  "notes": [
    { "guid": "b7f3…", "values": ["私", "わたし", "I, me"] },
    { "guid": "0c91…", "values": ["犬", "いぬ", "dog"] }
  ]
}
Key Meaning
format Format version, 1 (the default). Ankipan refuses files from a newer format.
id Identifies the package across versions. Make one up once (a UUID) and never change it.
version Whole number, higher is newer. Bump it whenever you publish a change. Defaults to 1.
name Deck name.
description, author, homepage Shown before the deck is added. homepage is where people can look for updates.
tags Space-separated tags applied to every note.
icon symbol is an SF Symbols name; tint one of red, orange, yellow, green, mint, teal, blue, indigo, purple, pink, brown, gray.
fields Columns, in order. type is text (the default; speech from older files reads as text). language is a BCP‑47 tag such as ja-JP: the voice the column is read aloud in and the language a spoken answer is recognised in. options.pronounceWith names another column to read aloud instead; options.script constrains the writing system (kana, pinyin, romaji, …).
kinds Card kinds. prompt fields show on the front, answer fields are revealed on the back. read names the field read aloud on each side: front (a prompt field) when the card comes up, back (an answer field) when it flips; either may be left out. hidden lists the prompt field that is only played, never shown (listening cards); it is the front's read field, and becomes it when read.front is left out. check asks for an answer before flipping: mode is typed, spoken or choice, field the answer field it checks. A spoken check may also name a prompt field: the learner reads the front aloud before flipping. ord is the kind's identity and should not change between versions; it defaults to the position.
notes Rows. values are in field order. guid is any string unique within the file; keep it stable between versions so people's progress on that row survives an update. Without guids a later version can only match rows by their content, so give every row one.

A row identical to an earlier one in every column is skipped. Rows that only share a first column are different notes and are all kept — 生 read なま and 生 read せい are two words — so the first column should be the thing being learned, but it needn't be unique.

Limits

Ankipan reads a file defensively, since anyone can write one. A file is refused if it is larger than 16 MB, if it declares more than 64 columns, 24 card kinds, 50,000 rows or 100,000 cards in total, if a kinds entry has a negative ord, or if id is missing or longer than 128 characters. No single value may be longer than 10,000 characters and one row may hold 50,000 in total — a row past that would sync nowhere, since it travels as one iCloud record and those are capped at 1 MB. Control characters are stripped from names and values (newlines and tabs are kept), and a deck file never changes a deck you already have — see "Getting a deck" above.