Any documentation for custom layouts?


I’m new here, came from Memrise :slight_smile:
Just started working on my personal Spanish deck and have several questions. Hopefully more experienced users would be able to give me some clues. Thanks in advance.

  1. Is there any documentation for template variables available for custom layouts? I’m pretty familiar with HTML/CSS stuff, just looking to find out any Kitsun specifics.
  2. Is there any documentation about how to make multi-choice cards?
  3. Is it possible to use several layouts for one deck at the same time? Not sure if I explain correctly, but I’m trying to partly mimic Memrise where in one deck you have different type of cards: foreign to native, native to foreign, multi-choice etc., and all of them get mixed up randomly. What is the best way to achieve something similar at Kitsun?
  4. Is there any API for bulk import (I see import option on the UI but API would be better)? Any documentation/sdk for that?



Hey @rtd! Welcome!

Sadly, the technical documentation is currently in a rewrite and the previous version was taken down along with the old help section of the website.

I’d recommend taking a look at the default layouts (on the edit layouts page) to figure out the kitsun specific syntax. Most of them are like {{type:fieldname}} where fieldname is the name of your template field.

If you just want to know specific things, feel free to ask here or message me directly (here or on the kitsun discord channel) and I’ll gladly help you out!

This is not yet supported, although it is on my to-do list.

Yes! Your cards each have individual layouts (can be multiple) so your deck can consist of however many layouts you wish. This is managed on the card level (say Card A has layouts X, Y & Z and Card B has H, K & L, this means that your deck now has 6 layouts). Every layout becomes a “sibling card” during reviews, so it will quiz you on the purpose of your layout just like memrise. By default these cards will be shuffled randomly during reviews.

You can also re-order the reviews in your current review session to your liking by clicking on the cog icon at the top-right during reviews.

There is no public API yet, so imports are better done through the import options available at the moment (anki or csv/tsv/txt files)

You mentioned coming from Memrise, so you might be interested in exporting your content to csv files with this chrome extension, which you can then import into Kitsun. It’s a rather easy process that way :smile:

1 Like

Thanks a lot for your answers! Since documentation isn’t ready yet, I’ll have to ask few more questions if you don’t mind :slight_smile:

  1. How tags are different from regular fields? Could you please provide any use cases where tags work better than regular fields?
  2. When I import from CSV in a Manual mode, it offers optional Index Column. What is it for? How it’s used?
  3. And few questions regarding layout syntax:
  • What does “{{type:Meanings[Meaning]}}” mean? I see that some fields are directly referred to by name in template like “{{Russian Sentence}}” but in some cases prefix “type” is used and square brackets.
  • What is “{{usernotes}}”?
  • What does such construction “{{#Part of Speech}}{{tags:Part of Speech}}{{/Part of Speech}}” mean (why there is # sign in front and why we repeat “Part of Speech” 3 times)?
  • What do “first:” and “rest:” prefixes mean?
  • Some default layouts include Frequency field like this “{{#Frequency}}{{tags:Frequency}}{{/Frequency}}”? What is it for, frequency of what?
  • In Russian layout there is also such field “{{type-ru:Vocabulary[Russian]}}”. What is “type-ru” and how many such types are supported? What’s the difference between “type” and “type-ru”?
  • Same question about “spellcheck” prefix like this “{{spellcheck:Foreign[Foreign]}}”.

I guess I’ll also have some questions about particular CSS classes, but I haven’t gotten too deep into CSS yet.


1 Like

Tags are just used to categorize your cards and make it easier to search through your cards (advanced search on the cards management page lets you select tags).

You can order your lessons for a deck through a few ways (date of card creation, reversed, random, index-based). Index-based will order your cards from 1-XXXXX. This can be useful if you need to study material in a certain order and the you added a card later on that is supposed to be near the front of the queue.

{{type:fieldname}] creates an input field. {{type:fieldname[blabla]}} would create a “regular” input with “blabla” as the input placeholder text (so can be used as a hint to say what to enter (e.g. “English”). Just {{fieldname}} will render the content of the field as text in your layout.

This is used to render personal notes. Only handy when your deck gets published as it lets other users of your deck put their own notes on the cards.

This creates an IF statement. If the field exists and has a value, it will render whatever is inside. In this case it would render the {{tags:Part of Speech}} part, but could also be a block of HTML.

{{first:fieldname}} splits the value of the field and renders the first split value only. Rest takes everything besides the first split value. So say you have “a, b, c” or “a; b; c” as possible answers, it would only render “a” and “b, c”. In the default layouts it’s used to show a primary answer larger than the rest.

Whatever might be entered in the field. Could be the frequency of a word according to dictionaries (e.g. common) or through parsing tools (e.g. “Hello” was found 10 times in this text).

  • type: regular input
  • type-ru: russian keyboard input (automatically inputs Russian characters as if you are typing with an IME)
  • type-ja: Japanese autoconversion input. Converts romaji to hiragana automatically (e.g. ka -> か)
  • type-kr: Korean keyboard input. (automatically inputs Korean characters as if you are typing with an IME)
  • spellcheck: Makes the answer checking strict (no typos allowed)
  • katakana: Autoconverts to katakana (Japanese script).
  • kanji: Does the same as type-ja but visually converts to kanji after input (uses furigana syntax to check the answer).

For Spanish you probably just want to use {{spellcheck:Spanish}} (if your field is named Spanish), and {{type:English}}.

Hope that helps!

Once this is added, I’m totally going to incorporate it into my Keigo set :eyes:

Nice, ¡buena suerte con estudiar con Kitsun!

Here’s a link to the template I made for Spanish to help other learners. It includes support for images, audio, definitions, and En→Es, Es→En. Hope it helps out!

1 Like

Thanks a lot for help!
Hopefully, I’ll open my Spanish course for public soon :slight_smile: So far so good.

Having few more questions, hopefully someone will help to clarify.

  1. Is it possible to choose layout for a specific review session? Say, when I’m on the go, I’d like to use only “Non Input” layouts but when I’m over my laptop I’d prefer to use both “Input” and “Non Input” layouts.
  2. Could someone please explain deck’s SRS settings tab?
  3. What does “Delay card siblings” deck setting do?

And few enhancements/recommendations I’d like to propose:

  1. When import CSV manually, it would be great if Kitsun matches template fields with CSV fields automatically if they have the same name.
  2. Support for multi-choice layouts.
  3. Support for layouts when you don’t type the answer, but click on separate letters on the screen instead. Memrise has it. Don’t know exact name for this but kind of virtual keyboard but just with randomly mixed letters from the word.
  4. If p.1 from above isn’t there yet, would be great to have an option to choose layouts per review session.
  5. Consider subscription discounts for active contributors who create popular decks :slight_smile:

Appreciate your help!


Awesome! Thanks for sharing :smiley:

It is not possible to choose specific layouts for review sessions, but you could force the deck to always show the flip buttons (next/flip/know/don’t know) and enable swiping gestures on mobile through the associated deck setting.

Scatter: entering a percentage here will scatter your reviews. So say your next interval is 10 days and your percentage is 10%, this means that the next review would come anywhere in between 9 days and 11 days from now. It can help unbatch cards that you learned at the same time. In general I’d advice to not enable it as it also does not round up to the hour.
SRS Intervals: These values indicate how long it takes until a card returns. If you answer all “sibling cards” correctly it will go to the next interval and take X hours to come back for reviews. If you answer wrong it will go down a level.

For each layout on a card, you get a review card during reviews, these are what we refer to as “sibling cards” here. Enabling this option lets you set up a delay between layouts. So if for example you have two layouts on a card, and your sibling delay is at 12 hours. Starting a review session will give you only one sibling card out of the two. After you answer the card, it will now schedule the other sibling card 12 hours later.

This setting can help prevent spoiling answers during reviews. Say you do English -> Spanish and Spanish -> English layouts, answering both in the same session could be easy because you already did one of the layouts in that same session. Delaying the siblings helps with this.

Agreed, it’s on my Quality of Life changes to-do list, but so far other things have taken priority. Hope to get to it some time soon though!

On the prio list :slight_smile:

Might consider adding this in the future. I don’t mind adding additional review types :kithappy:

We are always looking to support creators of quality community decks (there are some criteria though), so feel free to contact me if you have something in mind :slight_smile:

1 Like

@Neicudi Thanks a lot as usual. Appreciate your help.

One more thing I’d found useful.
When importing words from file, it would be useful to have a choice: update existing words if some (configurable) fields match or always create new records.
I think currently it just always creates new cards. So currently there is no way to update multiple fields of multiple words through CSV import.

  1. Is it possible to completely reset the progress for the deck? Like I’m currently testing my deck but eventually when I’ll consider it ready, I’d like to reset my progress and start learning properly from scratch. I didn’t notice that option.

  2. And what are spoilers? What does “Blur spoilers” settings do?


That’d be a nice addition, but also a pretty dangerous one I think. We used to have export -> reimport functionality which basically did what you mentioned (export -> edit in excel/google sheets -> reimport and overwrite where needed), but it was very error prone. I do have actual spreadsheet editing inside Kitsun on my to-do list (and made a promising prototype before) which would probably work better for these situations :smiley:

You can go into the cards management table, select all cards (checkbox in the table header) and demote them through the actions dropdown. Demoting to 0 will delete the progress on the cards :slight_smile:

Sometimes seeing the back on a card will “spoil” you for your next sibling review. Here’s an example:

On this layout I was tested on the “reading” of a Japanese word. In this case I don’t want to see the “meaning” of the word yet as that is a different layout/review.

If I do want to see it, I can click/tap on the blurred text and it will be shown normally.

The deck setting blurs the spoiler text (and sometimes disables audio autoplay) if enabled.

If you wish to make use of this in your custom layouts, you will have to add a blur class to whatever you wish to mark as a spoiler. And add css similar to this to your card styling:

.blur {
    text-shadow: 0px 0px 10px var(--dark-text);
    color: transparent;
    cursor: pointer;

You can change var(--dark-text) to the color of your liking if you wish (it’s a theme color variable, adjusting to light and dark themes accordingly). The rest of the functionality is taken care of by Kitsun.

If in doubt you can check how the default layouts use it :slight_smile:

I think my use case is slightly different, I don’t need export feature at all.
My source of truth is a Google Sheet.
I have several scripts which add content to that sheet automatically (they scrape dictionaries, generate URLs for audio/images etc.). Occasionally I export it to CSV and import to Kitsun.
Sometimes there’re cases when some fields of existing words get updated in my sheet (add new synonyms / example sentences / notes or change audio/image URL etc.). Since it happens semi-automatically I don’t really track what exactly words have been updated. And usually it happens with several words even though I have only 150 words in my deck at this point.
So the ideal scenario for me is when I just export full sheet to CSV, say weekly and import to Kitsun. And then if word already exists, Kitsun will just update fields and if it doesn’t exist it will create a new card.

BTW, it would be nice to have some API at least for import feature. Because based on my experience, everything else can be covered by Google Docs easily. They offer SDKs for many languages.

Though I agree that for most people export feature will make perfect sense too. I’m just too lazy to do changes manually, so have tried to automate the process as much as possible. I used same approach with Memrise too :slight_smile:

This seems to work as expected but in “Manage cards” menu cards still have “Known” sign. It doesn’t really bother me, hopefully that sign won’t affect anything.

Thanks for what you’re doing!

@Neicudi There is one a bit weird thing that I noticed in review sessions.
When I forget a word, I click “Flip” > “Don’t know” and I expect that Kitsun will just mark that word somehow and will start adding in to review sessions a bit more frequently. But instead when I click “Don’t know” it just keeps testing me against that same card over and over until I click “Know”.
Is that “by design” or I’m doing something wrong?


The idea to my understanding is that you want to keep on reviewing it in the same session until you remember it. So, if you say “Don’t know” once, next time only select “Don’t know” if you still cannot remember the answer. It will only take the card out of the current review when you select “Know.” This doesn’t mean it will raise the level of the card.

1 Like

As @Buscadon mentioned, this is by design. It’s there to make sure you know the card info right now, so that next time you won’t rank down as fast. Pressing “know” won’t actually rank it up if it’s already been marked as “don’t know” before, it’s just there to help you study it a bit more before it ranks down.

1 Like

@Buscadon and @Neicudi thanks a lot. That makes perfect sense.

Is there a standard way of dealing with synonyms? If user types a synonym instead of the exact word, is there a way to accept this answer (make card green, not red)?


You can add synonyms to your list of accepted answers by separating your answers with commas. Users are also able to propose changes to make this easier for you (they propose the change and them you either approve or reject it).


@VegasVed Thanks! Where is that list of accepted answers configured? I don’t see anything relevant in “Manage cards” section. Or is this a feature which needs to be implemented by layout first?

1 Like

When you make your cards, you put all the synonyms in the answer field (whichever one that is for you), separated by commas.

For example if the front is “girl”, then in your answer field would be “女の子, 女子, 少女” and in your layout you would use “first” to show the main word as “女の子”.

In your layout, using “first” would display 女の子 and using “rest” would display the other two words. For all cards you need to set the multiple options in each card’s edit screen.


Awesome! Works just fine, thanks @VegasVed.


One more question.

I’m trying to use shortcuts to flip cards, mark card as know/don’t know etc. Basically I’m not using mouse in sessions at all.
There is a minor problem with input fields. When card with input field shows up, I can’t start typing the answer right away, because type field isn’t in focus. I have to press TAB button 1-2 times to make field focused first. This is a minor thing but annoys and slows down the process quite a lot.
I guess it can be caused by some issues with my html/css in layouts.

Does anyone have any clues?

1 Like

Ah, sorry, no clue about that. @ThBigBoss @Neicudi

1 Like