Metadata-Version: 1.1
Name: ankdown
Version: 0.5.2
Summary: A utility for converting Markdown into Anki cards
Home-page: https://github.com/benwr/ankdown
Author: Ben Weinstein-Raun
Author-email: b@w-r.me
License: MIT
Description: # Ankdown
        
        A simple way to write Anki decks in Markdown.
        
        ## What This Is
        
        [Anki](https://apps.ankiweb.net) is awesome, in many ways.
        However, its card editor is... a little bit uncomfortable.
        I really wanted to write Anki cards in Markdown. So I made
        a tool to convert Markdown (+ standard MathJAX math notation)
        into Anki decks that can be easily imported. This way, it's
        possible to use any fancy markdown (and MathJAX) tools to build
        your decks.
        
        ## How to use it
        
        **NOTE** This program requires _Python 3_, along with the
        packages in requirements.txt
        
        ### Installing
        
        Ankdown can be installed by doing `pip3 install --user ankdown`.
        
        ### Writing Cards
        
        Cards are written in the following format:
        
        ```markdown
        Expected Value of \(f(x)\)
        
        %
        
        \[\mathbb{E}[f(x)] = \sum_x p(x)f(x)\]
        
        %
        
        math, probability
        
        ---
        
        Variance of \(f(x)\)
        
        %
        
        \[\text{Var}(f(x)) = \mathbb{E}[(f(x) - \mathbb{E}[f(x)])^2]\]
        
        ```
        
        Each of the solitary `%` signs is a field separator: the first
        field is the front of the card, the second field is
        the back of the card, and subsequent fields can contain whatever
        you want them to (all fields after the second are optional).
        
        `---` markers represent a card boundary.
        
        The tool needs these separators to be alone on their own lines,
        and most markdown editors will work better if you separate them from
        other text with empty lines, so that they're treated as their own
        paragraphs by the editor.
        
        ### Running Ankdown
        
        #### Method A: manually
        
        To compile your cards, put them in markdown files with `.md` extensions,
        inside of a directory that has the name of the deck you'd like to put
        the cards into. Then, run `ankdown -r [directory] -p [package filename]`.
        
        You can then import the package using the Anki import tool.
        
        #### Method B: via the add-on
        
        Once you've installed ankdown, it can be a hassle to run it on all
        of your decks over and over again. There is an [`ankdown`
        Anki add-on](https://ankiweb.net/shared/info/109255569) that you
        can use to make this process simpler: If you put all of your decks
        in one megadirectory (mine is in `~/Flashcards`), you can re-import
        your decks in one swell foop by going to `Tools > Reload Markdown
        Decks` (or using the operating-system-dependent keybinding).
        
        
        ## Gotchas
        
        Ankdown has an unusually large number of known issues; my preferred method
        of discussing them is via github ticket.
        
        ### Multiple Decks
        
        Ankdown uses Genanki as a backend, which doesn't (as of this writing) handle
        multiple decks in a single package very well. If you point ankdown at a
        directory with multiple decks in subdirectories, it will do its best, and
        your cards will all be added to the package, but they won't be assigned
        to the correct decks. The ankdown plugin solves this problem by running
        the executable on each deck individually, and then importing all the
        resulting packages.
        
        ### Intentional feature removals
        
        There used to be other ways to run ankdown, but they were slowly making
        the code worse and worse as I tried to keep them all operational. If there's
        a particular method of operating ankdown that you used and miss, let me know
        in a github issue.
        
        ### Math separators
        
        Unfortunately, `$` and `$$` as math separators were not chosen by the anki
        developers for the desktop client's MathJax display, and so in order for math
        to work in both web and desktop, it became much simpler to use `\(\)` and
        `\[\]`. These separators should be configurable in most markdown editors
        (e.g. I use the VSCode Markdown+Math plugin). Older decks that were built
        for ankdown need to be modified to use the new separators.
        
        ### Media references
        
        Ankdown should work with media references that result in `src=""` appearing
        somewhere in the generated html (mainly images). If you need it to work with
        other media types (like sounds), let me know in a github issue and I may make
        time to fix this.
        
        ### Updating Cards
        
        When you want to modify a card, just run your deck through the above
        process after changing the markdown file. Anki should notice, and update
        the card. This is done by giving the cards in your deck unique IDs based on
        their filename and index in the file.
        
        This is the most robust solution I could come up with, but it has some downsides:
        
        1. It's not possible to automatically remove cards from your anki decks, since
        the anki package importer never deletes cards.
        2. If you delete a card from a markdown file, ankdown will give all of its
        successors off-by-one ID numbers, and so if they were different in important
        ways (like how much you needed to study them), anki will get confused.
        The best way to deal with this is to give each card its own markdown file.
        
        ### General code quality
        
        Lastly, the catch-all disclaimer: this is, as they say, alpha-quality software.
        I wrote this program (and the add-on) to work for me; it's pretty likely that
        you'll hit bugs in proportion to how different your desires are from mine. That
        said, I want it to be useful for other people as well; please submit github
        tickets if you do run into problems!
        
        
Keywords: anki spaced-repetition markdown math latex
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Topic :: Education :: Computer Aided Instruction (CAI)
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.0
Classifier: Programming Language :: Python :: 3.1
Classifier: Programming Language :: Python :: 3.2
Classifier: Programming Language :: Python :: 3.3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3 :: Only
