Home

Awesome

CrowdAnki

Build Status

[中文版介绍]

CrowdAnki is a plugin for http://ankisrs.net/ that allows users to import and export decks/notes and all relevant information in a JSON format. The main purpose is to facilitate crowd-sourcing for Anki decks and notes.

Starting with version 0.6 it also features a close integration with Git. Providing you with an ability to automatically maintain history of edits for your decks.
See more details below.

AnkiWeb link for the plugin: https://ankiweb.net/shared/info/1788670778


Please consider supporting the plugin development by becoming a Patron - this helps me to dedicate more time and love to the project

Become a Patron!


How to collaborate via GitHub

This section illustrates collaboration workflow using GitHub.

Suppose you have a deck named DeckX and you want to collaborate on its improvement with other people. In order to achieve this you will need to:

  1. Export the DeckX. You can do that by going to Anki: File > Export > Export format: CrowdAnki JSON Representation. Include: DeckX.
  2. Create a GitHub account for yourself and ask your collaborators to do the same (see: https://github.com/join).
  3. Create a repository for your deck by following this guide https://guides.github.com/activities/hello-world/#repository. The name of the repository has to correspond to the name of the directory that was created during the export. In our case, it would be named DeckX.
  4. Add collaborators to the repository: https://help.github.com/articles/inviting-collaborators-to-a-personal-repository/.

GUI workflow

Preface:

My goal here is to provide a user-friendly description of collaboration workflow. In order to do that, I looked through multiple GUI git clients. For our purposes here, I think GitHub Desktop is the best choice (as the most user-friendly client that works). There is one problem with GitHub Desktop, though - it doesn't have a Linux version. Which makes me particularly sad, as I use Linux as my main OS. I've considered using GitKraken for this tutorial, but it has some problems that disqualify it for our purposes (but if you're Linux user or if you don't like GitHub Desktop for some reason - you may still want to consider using it).

Initiating collaboration

  1. Install GitHub Desktop for your computer.
  2. Log in to it with you GitHub account, created earlier.
  3. Create a new repository. "Local path" should point to the place you've imported your deck, the name of the repository should be the same as the name of exported directory. Image
  4. Add the content of your directory to the repository, by selecting all of the files, adding some comment in comment field and pressing "Commit to master" Image
  5. Upload the changes you've just made to the GitHub, by pressing button "Publish" and then "Publish <RepositoryName>". In this case, you don't need to create repository in advance, GitHub Desktop will create it for you. Image

To start working on the deck your collaborators need to:

  1. Install GitHub Desktop for their computer.
  2. Clone the repository you've created. They can do that by going to the repository page on GitHub and pressing "Clone or download -> Open in Desktop". Image
  3. Import the deck.

If somebody just wants to use the deck you've uploaded to GitHub - they can import decks directly from there.

How to upload changes

When you or one of your collaborators want to upload changes you've made to the GitHub, you need to:

  1. Get the latest changes from the GitHub, by pressing "Sync" button in the top right corner. Image
  2. Import the deck to combine changes you've made with the changes other people have made.
  3. Export the deck the same directory where your repository is located so that export will overwrite media directory and JSON file in the repository. (As an alternative you can export it elsewhere and copy JSON file and media directory yourself to overwrite the ones that are in repository directory.)
  4. Add the changes you've made to the repository, by selecting all of the files, adding some comment in comment field and pressing "Commit to master" Image
  5. Upload changes you've made to the GitHub, by pressing "Sync" button in the top right corner.

If you just want to get latest changes from other people - you need to perform only steps 1 and 2.

CLI workflow

Initiating collaboration

  1. Install git on your computer.

  2. Go to the directory that resulted from export.

  3. Initialize repository with following commands:

    git init
    git remote add origin git@github.com:<username>/<repository>.git
    

    Where <username> is your GitHub username (in my case Stvad) and <repository> is the name of the repository (DeckX). So in our case the command will look like:

    git remote add origin git@github.com:Stvad/DeckX.git
    
  4. Add the content of your directory to the repository:

    git add *
    git commit -m "initial export"
    
  5. Upload changes you've made to the GitHub:

    git push origin master
    

To start working on the deck your collaborators need to:

  1. Install git on their machine.

  2. Clone the repository you've created:

    git clone https://github.com/Stvad/DeckX.git
    
  3. Import the deck.

If somebody just wants to use the deck you've uploaded to GitHub - they can import decks directly from there.

How to upload changes

When you or one of your collaborators want to upload changes you've made to the GitHub, you need to:

  1. Get the latest changes from the GitHub:

    git pull
    
  2. Import the deck to combine changes you've made with the changes other people have made.

  3. Export the deck the same directory where your repository is located so that export will overwrite media directory and JSON file in the repository. (As an alternative you can export it elsewhere and copy JSON file and media directory yourself to overwrite the ones that are in repository directory.)

  4. Add the changes to the repository:

    git add *
    git commit -m "new updates"
    
  5. Upload changes you've made to the GitHub:

    git push origin master
    

If you just want to get latest changes from other people - you need to perform only steps 1 and 2.

Generic collaboration workflow

The current workflow could be described as following:

Export

To perform the export go to menu File > Export

Select the deck and the export format "CrowdAnki JSON representation". After pressing the Export button - select directory where the result should be stored.

Limitations:

Import

To perform the import go to menu File > CrowdAnki: Import from disk and select the directory where the deck is stored.

Import from git

To get the deck from a git repository (such as GitHub) go to menu File > CrowdAnki: Import git repository and enter the repository's full URL.

So, for example, to get my git deck you would need to enter https://github.com/Stvad/Software_Engineering__git.

Things to note for the Import:

Snapshots

CrowdAnki can help you preserve the history of edits for your decks.
It does this by exporting them in a specified location and creating a git commit each time you do a snapshot.

You can take snapshots manually via File > CrowdAnki: Snapshot menu action. Or you can enable automated snapshots in add-on configuration (see below) which will take a snapshot each time you open or close anki.

Configuration Settings

You can find the add-on's config page via Tools -> Add-ons, select CrowdAnki then hit Config. In here you can set a some config options, as well as a detailed explanation on what each does, with examples and default behaviour.

Here is a general summary of the currently available config options: