Skip to content

Latest commit

 

History

History
185 lines (135 loc) · 10.3 KB

README.md

File metadata and controls

185 lines (135 loc) · 10.3 KB
Raw

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 is your GitHub username (in my case Stvad) and 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:

  • The user creates or imports an Anki deck.
  • He makes some modification to it (i.e. to notes, deck settings, deck structure or note models).
  • Then the user can export the deck in JSON format (accompanied by media directory with media files used in that deck) and share it with other users. For example by creating GitHub repository with it.
  • Other people then can either modify JSON directly or import the deck to their instance of Anki and then make some modifications to it.
  • Original JSON then can be updated the with the changes, these people made (merging several changes together if necessary).
  • After that original user (and other people) can import updated deck to integrate these new changes into their collection.

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:

  • CrowdAnki won't allow you to do export of "All decks", you should use CrowdAnki snapshot instead.
  • Export of a filtered deck is not supported, export the main deck instead and filter it again after importing. You don't have to delete existing filtered decks, as all cards are still part of the main deck. When exporting nested decks, filtered sub-decks are just ignored.

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:

  • Automatic backup would be triggered prior to the import;
  • If note model for the note has changed, or if note model itself changed in a way that it's not easy to update it automatically: you would be prompted with the window, that will ask you to specify correspondence between old and new model;
  • If the note was moved to another deck in JSON file, on import all cards from that note (except the ones, that are in dynamic decks) will be moved to the specified deck.

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:

  • Snapshot Path: location of the snapshot will be exported to
  • Snapshot Root Decks: when a snapshot is taken a git repo will be generated for each of these decks
  • Automated Snapshot: whether the snapshot happens automatically
  • Do Not Move Existing Cards on Import: whether to move already existing cards on import or not
  • Deck Sort Methods: how to sort cards on export
  • Reverse Sort Order: whether to reverse the sorting of cards on export