Tutorial

[marquiswang]

Hello!

I've interested in using autoanki and autoanki/cli. Do you have a quick (even just a few lines?) tutorial for how you use it?

[chenlijun99]

Hi. Thanks for your interest in the project. At the current stage, I wouldn't advise anybody to use it, since it's developed to a point that is barely enough for me (with many undocumented rough edges that only I know how to avoid).

Anyway, if you just want to have a quick try, I hope that the following instructions could be enough.

Install @autoanki/cli and the relevant plugins.

$ npm install -g  @autoanki/cli @autoanki/plugin-source-markdown @autoanki/plugin-content-markdown @autoanki/plugin-content-local-media-extractor

Write a configuration file named autoanki.config.js.

An example configuration to write in autoanki.config.js could be:

module.exports = {
  noteInputsConfig: [
    {
      // common configuration for all files
      inputs: ['*'],
      '@autoanki/sync': {
        manualActionDefaultChoices: {
          // for any existing Autoanki note, if it is found only in the source,
          // then by default re-add it to Anki.
          SyncActionHandleNotesOnlyInSource: 'ADD_TO_ANKI',
        },
      },
    },
    {
      // for files that end with `.md`,
      // * Extract notes using @autoanki/plugin-source-markdown
      // * Then run the extracted notes through the transformation plugins, in the specified order
      inputs: ['*.md'],
      '@autoanki/core': {
        defaultDeck: `TestDeck`,
        pipeline: {
          source: '@autoanki/plugin-source-markdown',
          transformers: [
            /**
             * Convert markdown to HTML.
             * Also handle:
             *
             * * Highlight using highlight.js
             * * Math using KaTeX
             */
            '@autoanki/plugin-content-markdown',
            /**
             * Extract local media referenced in the source
             */
            '@autoanki/plugin-content-local-media-extractor',
          ],
        },
      },
    },
  ],
};

Then run @autoanki/cli inside the directory where autoanki.config.js resides (or a subdirectory).

# Extract, transform the Autoanki notes from the given <input files> and then sync them to the current running Anki instance, via Anki-connect.
$ autoanki sync <input files>
# E.g.
# autoanki sync a.md b.md c.md
# autoanki sync **/*.md (may not work depending on what kind of glob your shell supports)

# Extract, transform the Autoanki notes and print them as JSON
$ autoanki print <input files>

For now the only Autoanki note syntax that @autoanki/plugin-source-markdown recognizes is the following:

```autoanki
note_type: <Note type>
fields:
  # Fields based on the note type
  # All the fields of the given note type must be specified and empty strings are not allowed. 

Basically each `autoanki` block contains Autoanki notes defined using YAML, where each note in YAML must have the `note_type` property and the fields property appropriately specified.

An example markdown file could be:

````md
# Hello world

This is a note

```autoanki
note_type: Basic
fields:
  Front: Hello
  Back: World

Another note

note_type: Cloze
fields:
  Text: Hello {{c1::World}}
  Extra: do not leave empty

[marquiswang]

Thanks! And thanks for the warning. I can probably handle rough edges, and could send a PR if I find any big issues. I mostly want to avoid writing the entire same thing myself :-)

Does cli support converting existing Anki notes to markdown yet?

[chenlijun99]

Does cli support converting existing Anki notes to markdown yet?

No, it doesn't support this feature and I didn't plan to support this. I designed autoanki with the goal of creating Anki notes from source text files (mainly markdown) and then keeping the source text files and the Anki note in sync. While currently it does support bidirectional sync to some degree, which means that if a note is changed inside Anki the change is reflected in the source markdown, the anki note must still be present in the note sources (i.e. the markdown files) for this to work. Basically how it works now is that when you invoke the cli with autoanki sync <some input files>, it parses all the given input files and extracts Anki notes. All the Anki notes created by autoanki are tagged with the autoanki tag. When performing the sync, we just try to match the parsed Anki notes with the Anki notes inside the Anki profile that are tagged with autoanki. The matching is done using an uuid unique for each Anki note. So, e.g. if you run first autoanki sync a.md and then autoanki sync b.md, in the second run the Anki notes created using the first run won't be considered at all, since they don't match the Anki notes that have been parsed from b.md

What I want to say is that "source files" and "Anki profile" are not two ends that are treated equally by the syncing algorithm. The "Anki profile" is more of a second-class citizen.

Having said that, I would be interested to hear your use-case.

[marquiswang]

My use case is the same as you, I think, except I've been using Anki for years. I would like to do one dump from Anki to Markdown, and then continuing syncing as you describe.

[chenlijun99]

I've also used Anki intermittently but was always bothered by the tedious process of card creation and correction. So I just dropped all the thousands of cards I've created previously (which I haven't reviewed for a long time anyway...). For now, if you really want to try autoanki, I would suggest just leaving your previous Anki cards in Anki, since autoanki won't touch any note that is not tagged with autoanki. You can still benefit from the features of autoanki for new cards that you want to create. Obviously, backup properly your Anki notes and when first trying autoanki I suggest creating a test Anki profile and do your experimentation there!