Skip to content

Set Repositories

Jump to bottom
Bodhi Mulders edited this page Apr 6, 2021 · 12 revisions

ShiraKamiSRS uses a repository system for users to discover new card sets to add. By default, every ShiraKamiSRS instance is loaded up with the main public repository. Users can add third-party repositories to ShiraKamiSRS to gain access to more sets hosted within these repositories.

Table of Contents:

Hosting a repository

Anyone can host a custom set repository to share around. A repository in its most basic form is just a webserver that hosts some set export json files, with an index file for ShiraKamiSRS to read.

In the future it might be made possible to host public repositories from ShiraKamiSRS itself, removing the need for users to host the repository themselves, and lowering the barrier to entry.

Hosting on GitHub: Repository Template

The easiest way to host your own repository, is by forking the repository template and hosting the files from GitHub using GitHub Pages.

As a prerequisite, make sure you have a recent version of NodeJS (and npm) installed on your local machine.

Initial setup

  1. Start by forking the repository template.

  2. Clone it to your local machine with git clone <git_url>.

  3. Export any sets you want your repository to host from ShiraKamiSRS

  4. Place all your exported set json files into repository/sets/.

  5. Run npm install in the root of the repository.

  6. Run npm run build to generate the repository index file.

  7. Make some changes in the now generated repository/index.json file.

    1. Change the name property to what you want your repository to be named when loaded within ShiraKamiSRS.
    2. (Optionally) fill the imageUrl property with the url for an image you would like to display as your repository icon within ShiraKamiSRS.
    3. (Optionally) fill the homePageUrl property with a url to the homepage of your set.
    4. (Optionally) fill the description property for each set.

  8. Commit your changes and push them to the GitHub repository.

  9. Go to your GitHub repository settings, scroll down and enable GitHub Pages for your repository on the root level.

Your repository should now be available to use with any ShiraKamiSRS instance using the url:

https://<GITHUB_USERNAME>.github.io/<GITHUB_REPOSITORY_NAME>/repository/

Updating the repository

To update the repository:

  1. Start by adding, removing, or changing any sets.
  2. Run npm run build again in the root of your repository to update your existing repository index file. Old customizations will persist.
  3. Optionally make your desired changes in repository/index.json.
  4. Commit your changes and push them to the GitHub repository.

You're done! It can take a few minutes before ShiraKamiSRS instances stop caching the old index of your repository.

Manually hosting a repository

You do not have to host your set repository on GitHub, or even use the template if you do not want to. If you have your own webserver, you can simply host the files yourself. The publicly accessible url to access the index file is your repository URL.

Even when hosting the repository yourself, the simplest option is still to use the repository template: Simply follow the instructions in the section above, and host the files within the repository folder on your own webserver.

Writing the repository index file

In case you want to manually write the repository index file rather than use the repository template to generate it, the format is described below.

Repository Index Specification (v1)

A good idea could be to look at an example index file.

Model

RepositoryIndex

Key Value type Required Description
version "v1" Yes Describes the version of the repository index specification used.
publicId String Yes A unique identifier for your repository. Usually a UUID. It is recommended to randomly generate this property to avoid any overlap with other repositories.
name String Yes The name for your repository, as shown in ShiraKamiSRS.
imageUrl String No The url for the image to be shown as the icon for your repository.
homePageUrl String No The home page url for your set.
sets RepositoryIndexSet[] Yes An array of set references

RepositoryIndexSet

Key Value type Required Description
name String Yes The name of the set. Should match the name specified in the set export.
exportVersion String Yes The version of the set export. Should match the version specified in the set export.
description String No A description for the set to be shown in the repository listing in ShiraKamiSRS.
modes ReviewMode[] Yes An array of the supported/default set modes. Should match the modes specified in the set export.
cardCount Number Yes The amount of cards in the set. Should match the amount of cards specified in the set export.
file String Yes A relative path to the set export file.

ReviewMode

ReviewMode is a string enum, and should be one of the following values:

  • enToJp
  • jpToEn
  • kanjiToKana

TypeScript Definitions

export interface RepositoryIndex {
    version: 'v1';
    publicId: string;
    name: string;
    imageUrl?: string;
    homePageUrl?: string;
    sets: RepositoryIndexSet[];
}

export interface RepositoryIndexSet {
    name: string;
    exportVersion: string;
    description?: string;
    modes: ReviewMode[];
    cardCount: number;
    file: string;
}

export type ReviewMode = 'enToJp' | 'jpToEn' | 'kanjiToKana';
Clone this wiki locally