Consider using a more `git`-friendly note source format?

[langfield]

Disclaimer. This is a shameless plug for my own tool.

This is a super neat project! I'm so thrilled more people are working on collaborative decks on GitHub. I think git is definitely the right way to manage a large number of user-contributions to source files, and that's exactly the problem deck maintainers face when they get a lot of users.

I was wondering if you'd consider moving from json to a more git-friendly format like markdown for your note sources?

I've downloaded your deck with CrowdAnki and generated a markdown version just so you can see what the notes would look like. Here is an example:

## Note                                                                                                                                                                                                                               
nid: 1660561322789                                                                                                 
model: Cloze-chrisc-ff04e                                
tags: GSSE::!Contributor::Victor_Liu                                                                                                                                                                                                  
markdown: false                                                                                                                                                                                                                       

### Text                                                                                                                                                                                                                              
The {{c3::deep}} part of abductor pollicus longus has a tendon that is mainly inserted into the {{c1::trapezium}}, with a slip joining {{c2::abductor pollicis brevis}}.                                                              

### Extra                                                                                                          
<img src="paste-10440c5a40c5bdcc290c9b09683514084c40cc15.jpg">                                                     
## Note                                                                                                            
nid: 1660561322782                                                                                                                                                                                                                    
model: Cloze-chrisc-ff04e                                                                                          
tags: GSSE::!Contributor::Victor_Liu                                                                                                                                                                                                  
markdown: false                                                                                                                                                                                                                       

### Text                                                                                                           
The <b>deep</b> part of the supinator consists of fibres that arise                                                
from the {{c1::<u>supinator crest}}</u> and {{c5::<u>supinator                                                                                                                                                                        
fossa</u>}} of the ulna and wrap {{c2::horizontally::horizontally                                                  
or obliquely}} around the radius to be inserted into the area                                                      
between the {{c4::anterior}} and {{c4::posterior oblique}} lines on
the {{c3::radius}}.                                      

### Extra                                                
The ulnar head of the superficial part of supinator arises                                                                                                                                                                            
<b>behind</b> the supinator crest (i.e. superficial to the deep                                                                                                                                                                       
head) <img src=                                                                                                                                                                                                                       
"paste-9eb3b6e5e8c875aabc220f83ad2048ca7c8523ea.jpg"><img src=                                                                                                                                                                        
"1090a4300814a52902e41d405c230861.png">                                                                                                                                                                                               
<div><img src=                                                                                                     
"paste-98a66abc7edec155bb4081634755f477c48f90fb.jpg"></div>

And here is an idea of what the repository structure would look like!

(anki) user@computer:~/gsse-ki-repo$ tree --filelimit 10
.
├── _media
├── !MEDICINE
│   ├── Anki for GSSE
│   │   ├── Anatomy
│   │   │   ├── 1. Introduction to regional anatomy
│   │   │   │   ├── 1. Tissues and structures  [416 entries exceeds filelimit, not opening dir]
│   │   │   │   ├── 2. Nervous System  [394 entries exceeds filelimit, not opening dir]
│   │   │   │   ├── _media
│   │   │   │   ├── models.json
│   │   │   │   ├── rule-of-9s-parkland-formula_1.md
│   │   │   │   ├── rule-of-9s-parkland-formula_2.md
│   │   │   │   ├── rule-of-9s-parkland-formula_3.md
│   │   │   │   ├── rule-of-9s-parkland-formula_4.md
│   │   │   │   └── rule-of-9s-parkland-formula.md
│   │   │   ├── 2. Upper limb  [14 entries exceeds filelimit, not opening dir]
│   │   │   ├── 3. Lower limb  [18 entries exceeds filelimit, not opening dir]
│   │   │   ├── 4. Thorax  [12 entries exceeds filelimit, not opening dir]
│   │   │   ├── 5. Abdomen  [12 entries exceeds filelimit, not opening dir]
│   │   │   ├── 6. Head, neck and spine  [16 entries exceeds filelimit, not opening dir]
│   │   │   ├── 7. Central nervous system
│   │   │   │   ├── 1. Cerebral hemispheres  [75 entries exceeds filelimit, not opening dir]
│   │   │   │   ├── 2. Brainstem  [227 entries exceeds filelimit, not opening dir]
│   │   │   │   ├── 3. Ventricles  [62 entries exceeds filelimit, not opening dir]
│   │   │   │   ├── 4. Spinal Cord  [111 entries exceeds filelimit, not opening dir]
│   │   │   │   ├── Kaplan Neuroscience  [910 entries exceeds filelimit, not opening dir]
│   │   │   │   ├── _media
│   │   │   │   ├── models.json
│   │   │   │   └── Neuroanatomy (Basic)  [114 entries exceeds filelimit, not opening dir]
│   │   │   ├── 8. Skull osteology
│   │   │   │   ├── 1. Intact Skull  [390 entries exceeds filelimit, not opening dir]
│   │   │   │   ├── 2. Skull Bones  [161 entries exceeds filelimit, not opening dir]
│   │   │   │   ├── _media
│   │   │   │   └── models.json
│   │   │   ├── _media
│   │   │   └── models.json
│   │   ├── _media
│   │   └── models.json
│   ├── _media
│   └── models.json
└── models.json

28 directories, 12 files

If you have any interest in trying this out, please check out the Anki deck version control tool I've built. I am on a desperate search for users, and maintainers of large decks are the very best kind!

Edit: Documentation.

Note. This would have the distinct advantage of not needing users to know how to download addons or use CrowdAnki, since you could build your .apkg files in GitHub actions on each commit, and publish tagged releases instead. Or have both!

[newageoflight]

Very interesting project, I'll definitely consider moving towards using it. I especially like the CI/CD pipeline for APKG releases.

It should be said that most of our contributors aren't technical so much of the action won't happen via Git; I'm looking for a way to facilitate a Wiki contribution model in a way that's more accessible to them. Nonetheless, using Markdown seems like it'd be a step in the right direction.

[langfield]

@newageoflight Thanks! I can start working on a PR within a fork if you'd like. That way you'd be able to see how the CI pipeline would work.

I wholeheartedly agree it is a bit much to expect contributors to be fluent in git. The disadvantage of both binary releases and the CrowdAnki model is that you can't get small, granular diffs back from your users/deck subscribers, and they have to have some way of getting the patch back to you, the maintainer.

One naive solution is a GitHub actions workflow that builds a Jekyll site for each deck, rendering the markdown note sources. During the build process, we embed a link to the New issue page for the deck repository, so the user can just write a short note to the maintainer describing the suggested edit. This is already in the works. See https://github.com/langfield/ki/issues/41.

So the workflow for a user would be:

1. User is studying your deck.
2. User sees something wrong with a note.
3. User goes to gsse-anki.github.io, scrolls or Ctrl-Fs to the relevant note, and clicks Suggest edit.
4. User writes their suggested edit and submits it on GitHub.

Alternatively, you could embed the New issue link into your card template(s).

---

There is of course the possibility of keeping a local copy of the repository on-disk for each user, and adding a Suggest edit button within the deck browser and note editor within Anki. These buttons could programmatically create PRs of exactly what was changed via the GitHub API. But of course, that would require an addon. This is on the long-term to-do list for the project.

[langfield]

See #3. It is now possible to automatically build and publish this deck in the form of a .apkg binary! The release assets will live on a page that looks like this one.

---

The GitHub actions workflow file used to build the deck looks like this:

name: Publish Anki .apkg deck binaries

on: 
  push:
    tags:
      - "v*.*.*"
  workflow_dispatch:

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout
        uses: actions/checkout@v3

      - name: Set up Python 3.10
        uses: actions/setup-python@v4
        with:
          python-version: "3.10"

      - name: Install tidy
        run: |
          sudo apt-get install tidy

      - name: Configure git
        run: |
          git config --global user.email "ki@example.com"
          git config --global user.name "Ki GithubActions"

      - name: Install ki
        run: |
          pip install wheel
          pip install git+https://github.com/langfield/ki.git@main

      - name: Clone ki
        run: |
          git clone https://github.com/langfield/ki.git ../ki/

      - name: Clone empty collection
        run: |
          ki clone collection.anki2 ../collection
          ls

      - name: Copy deck repository into newly-cloned empty ki repository
        run: |
          cp -r ./ ../collection/
          ls -l ../collection/

      - name: Add and commit changes in ki repository
        working-directory: ../collection/
        run: |
          git add .
          git commit -m "Add deck."

      - name: Push changes back to database file
        working-directory: ../collection/
        run: |
          ki push

      - name: Compile deck
        run: |
          python3 ../ki/compile.py --collection collection.anki2 --deck 'GSSE'
          ls .
          ls ../ki/

      - name: Release
        uses: softprops/action-gh-release@v1
        if: startsWith(github.ref, 'refs/tags/')
        with:
          files: |
            GSSE.apkg