{"id":18196050,"url":"https://github.com/rubenayla/anki-importer","last_synced_at":"2026-04-24T16:06:26.407Z","repository":{"id":241195706,"uuid":"804604081","full_name":"rubenayla/anki-importer","owner":"rubenayla","description":null,"archived":false,"fork":false,"pushed_at":"2024-11-03T00:03:47.000Z","size":40,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-11-03T00:22:40.596Z","etag":null,"topics":["anki","anki-cards","anki-deck","anki-flashcards","python","python3","studying"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rubenayla.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-05-22T22:58:25.000Z","updated_at":"2024-11-03T00:03:51.000Z","dependencies_parsed_at":"2024-05-22T23:47:09.624Z","dependency_job_id":"81459dac-fd12-4c4e-82db-2b0eedcfde7c","html_url":"https://github.com/rubenayla/anki-importer","commit_stats":null,"previous_names":["rubenayla/anki-md-importer","rubenayla/anki-importer"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rubenayla%2Fanki-importer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rubenayla%2Fanki-importer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rubenayla%2Fanki-importer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rubenayla%2Fanki-importer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rubenayla","download_url":"https://codeload.github.com/rubenayla/anki-importer/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247699782,"owners_count":20981611,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["anki","anki-cards","anki-deck","anki-flashcards","python","python3","studying"],"created_at":"2024-11-03T09:00:20.308Z","updated_at":"2026-04-24T16:06:26.401Z","avatar_url":"https://github.com/rubenayla.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Anki Markdown Importer\n\nThis script imports multiple-choice questions from a Markdown file into Anki, allowing you to use custom note types with shuffling options.\n\n## Features\n\n- Imports questions from a simple Markdown format.\n- Highly configurable via `config.yml` files.\n- Automatically detects available Anki card models (note types).\n- Lets you inspect the fields of any card model to configure the importer easily.\n- Supports mapping to any custom note type, including those with shuffling options like \"MCQ Ultimate V2.1 shuffling default\".\n\n## Prerequisites\n\n1.  **[Anki](https://apps.ankiweb.net/)**: Make sure Anki is installed on your system.\n2.  **[AnkiConnect](https://ankiweb.net/shared/info/2055492159)**: You need to install the AnkiConnect add-on in Anki. This allows the script to communicate with Anki.\n3.  **[Python](https://www.python.org/downloads/)**: You need Python 3 installed.\n4.  **Project Dependencies**: Managed via `pyproject.toml` and Poetry.\n\n## How to Use\n\n### 1. Prepare Your Questions\n\nCreate a Markdown file (e.g., `questions.md`) with your questions. Use the following format for each question:\n\n```markdown\n- What is the capital of France?\n    1. Berlin\n    2. Madrid\n    3. Paris\n    4. Rome\n    - Answer: 3, Paris is the capital of France.\n\n- Which planet is known as the Red Planet?\n    1. Earth\n    2. Mars\n    3. Jupiter\n    4. Venus\n    - Answer: 2, Mars is often called the Red Planet due to its reddish appearance.\n```\n\n**Important**: Each question must end with an `- Answer:` line, followed by the number of the correct option and an optional explanation.\n\n**How the Markdown is interpreted for Anki Cards:**\n\nThis Markdown format is specifically designed for multiple-choice questions. Here's how the script interprets each part to populate your Anki card fields:\n\n*   The line starting with `-` or `N.` (e.g., `- What is...` or `1. What is...`) is extracted as the **Question** text.\n*   The numbered lines (e.g., `1. Berlin`, `2. Madrid`) are treated as the **Options**.\n*   The `- Answer: N, [Explanation]` line is crucial:\n    *   `N` (the number) indicates the **correct option** among the numbered lines.\n    *   `[Explanation]` (the text after the comma) is the **Explanation** for the answer.\n\nThis information is then mapped to the fields of your chosen Anki card model, as configured in your selected `config.yml`.\n\n**Note on Basic Card Types:** If you configure a basic card model (e.g., 'Basic') in your `config.yml` (by setting `card_model: Basic` and `incorrect_answers: []`), the script will automatically combine the question and options into the 'Front' field, and the correct answer along with the explanation into the 'Back' field.\n\n### 2. Installation\n\nChoose your preferred method to install the project dependencies:\n\n#### Automated Installation (Recommended)\n\nTo get started quickly, simply run the appropriate installation script for your operating system. This will install Poetry (if you don't have it) and all project dependencies.\n\n**Linux / macOS:**\n\n```bash\nbash install.sh\n```\n\n**Windows (PowerShell):**\n\n```powershell\n.\\install.ps1\n```\n\n#### Manual Installation\n\nIf you prefer to install dependencies manually, follow these steps:\n\n1.  **Install Poetry**: If you don't have Poetry installed, follow the official instructions:\n    *   **Linux / macOS / Windows (WSL):**\n        ```bash\n        curl -sSL https://install.python-poetry.org | python3 -\n        ```\n    *   **Windows (PowerShell):**\n        ```powershell\n        (Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | python -\n        ```\n    *   For other installation methods or troubleshooting, refer to the [Poetry documentation](https://python-poetry.org/docs/#installation).\n\n2.  **Install Project Dependencies**: Navigate to the project root directory in your terminal and run:\n    ```bash\n    poetry install\n    ```\n\n### 3. Configure the Importer\n\nConfiguration is done through YAML files. The project provides a default `config.yml` for basic cards and a `configs/` directory with presets for more complex card types.\n\n**Default Configuration (for Basic Anki Cards):**\n\nThe `config.yml` file in the root directory is pre-configured to import questions as basic Anki cards (Front/Back). If you intend to use basic cards, you can proceed directly to [Step 4. Run the Importer](#4-run-the-importer) after preparing your questions and installing the dependencies. No changes to `config.yml` are needed.\n\n**Using Presets or Custom Configurations:**\n\nIf you want to use a custom multiple-choice Anki card model (like \"MCQ Ultimate V2.1 shuffling default\") or any other specific setup, you can use one of the provided presets or create your own. Presets are located in the `configs/` directory.\n\n**Step 3.1: Find Your Card Model (if using a custom model)**\n\nFirst, make sure Anki is running. Then, run the following command in your terminal to see all the card models you have installed:\n\n```bash\npoetry run python main.py --list-models\n```\n\nThis will output a list of names. Find the one you want to use (e.g., `MCQ Ultimate V2.1 shuffling default`) and copy it.\n\n**Step 3.2: Find the Fields for Your Card Model (if using a custom model)**\n\nNow, use the name you just copied to find out which fields the card model uses:\n\n```bash\nbash poetry run python main.py --list-fields \"MCQ Ultimate V2.1 shuffling default\"\n```\n\nThis will show you the exact names of the fields, for example:\n- Question\n- Correct\n- Incorrect1\n- Incorrect2\n- Incorrect3\n- Explanation\n\n**Step 3.3: Select or Edit Your Configuration File**\n\n*   **To use a preset:** Choose a file from the `configs/` directory (e.g., `configs/mcq_ultimate_v2.yml`). You can use it directly or copy it to your project root and modify it.\n*   **To create a custom configuration:** You can start by copying an existing preset or the default `config.yml` and modifying it to suit your needs.\n\nYour configuration file (whether `config.yml` or a preset) will define the `card_model`, `fields` mapping, and `questions_file`.\n\nHere is an example `configs/mcq_ultimate_v2.yml` for the \"MCQ Ultimate V2.1 shuffling default\" template:\n\n```yaml\ncard_model: MCQ Ultimate V2.1 shuffling default\nfields:\n  question: Question\n  correct_answer: Correct\n  incorrect_answers:\n    - Incorrect1\n    - Incorrect2\n    - Incorrect3\n  explanation: Explanation\nquestions_file: questions.md\n```\n\n### 4. Run the Importer\n\nOnce your configuration file is ready and Anki is running, run the script. You can specify the configuration file and the target Anki deck:\n\n```bash\npoetry run python main.py --config config.yml --deck-name \"My Custom Deck\"\n```\n\n*   Use `--config config.yml` to use the default configuration, or `--config configs/your_preset.yml` to use a preset.\n*   Use `--deck-name \"Your Anki Deck\"` to specify the target deck. If omitted, cards will be added to the \"Default\" deck in Anki.\n\nThe script will read your Markdown file, connect to Anki, and create the new cards in the specified deck with the correct card model.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frubenayla%2Fanki-importer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frubenayla%2Fanki-importer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frubenayla%2Fanki-importer/lists"}