Add-On Structure

Development
1

I want to publish an add-on and wonder what is the best structure of my git repository. Is there anything like a best practice or a starter project?

I have looked at existing add-ons. Some of them are named like “my-addon” (with a hyphen) and have the actual source code in “my-addon/my_addon” (with an underscore), some in “my-addon/src”, others in the top-level directory. Then I found repos with a “manifest.json”, others with an “addon.json”.

Are these files documented somewhere?

And where do I get the numerical id for my add-on from?

2

Different developers use different methods and the structure doesn’t matter most of the time, but some structures will prove more flexible depending on the add-on.

If you only have a basic add-on then just putting all files in a flat repo will work and is the simplest option. But it doesn’t hurt to be a bit more organized and put sources in a separate subdirectory. This will come useful when your add-on gets more complex and you start making use of code generation (most common case being building Qt forms using Qt Designer).

The “my-addon/my-addon” is a common way to structure Python projects and used by popular add-ons (e.g. add-ons of Glutanimate and the AnKing). I believe it’s the structure expected by Glutanimate’s add-on builder so it’s used by any add-on using that.

I personally use the “my-addon/src” structure where sources (and generated files) go to a src subdirectory. This directory can then be zipped and distributed as the add-on’s installation file.
I learned to use this structure from the LPCG add-on (LPG is an exemplary add-on) and used it for all my add-ons ever since and built tools around it.

Then I found repos with a “manifest.json”, others with an “addon.json”.

manifest.json defines some add-on metadata like add-on name and minimum/maximum supported Anki version. There are some docs about it here:
https://addon-docs.ankiweb.net/sharing.html#sharing-outside-ankiweb

addon.json is used by Glutanimate’s add-on builder to define build metadata and is used to generate manifest.json.

And where do I get the numerical id for my add-on from?

You get the ID when you upload an add-on to AnkiWeb.

Is there anything like a best practice or a starter project?

Check out the AnKing add-on template, which uses Glutanimate’s add-on builder:

I spent a lot of time this year working on my own add-on template:

I use it for all my new add-ons and it’s a great time saver and time sink at the same time.

2 Likes
3

Thanks, @abdo! That was a lot of information. I will try to modify my structure according to your template.

4

This topic was automatically closed 30 days after the last reply. New replies are no longer allowed.