docs: add previous database documentation

docs/Conventions.md

@@ -0,0 +1,68 @@
+# Conventions
+
+## Branch Names
+
+Branch names mostly follow [Git Flow](https://nvie.com/posts/a-successful-git-branching-model/): You have two main branches, `master` and `develop`, and then different types of branches that share common prefixes:
+
+- `feature/` branches are for new content or functionality. Example: `feature/gods-of-aventuria`
+- `fix/` branches are for fixes
+- `release/` branches are only used for releases and usually only created by @elyukai.
+- `hotfix/` branches are only used for production fixes that need to be quickly resolved.
+
+## Commit Messages
+
+Git Commit messages should follow Semantic Commit messages if possible: https://nitayneeman.com/posts/understanding-semantic-commit-messages-using-git-and-angular.
+
+### Possible scopes
+
+- *empty*: Generic
+- `t9n`: Translation content
+- `schema`: Schema content
+
+### Examples
+
+- `feat: add liturgical chants from AGÖ5`
+- `feat(t9n): add Italian liturgical chants from AGÖ2`
+- `feat(schema): add generic casting time field`
+- `fix: wrong IC of spell Odem Arcanum`
+
+## Data File Names
+
+### Form
+
+`<Id>_<Name>.yml`
+
+#### Parameters
+
+- `<Id>` is the numeric id of the entry.
+- `<Name>` is the English name (if no English name is available, its the German name). The name needs to be adjusted so no special characters and no spaces are used. The complete list of replacement rules can be found below.
+
+#### Examples
+
+- `1_Noble.yml`
+
+### Replacement Rules for Names
+
+- Always start with an uppercase letter even if the entry name itself doesn't start with an uppercase letter.
+- Spaces are replaced with `-`.
+- Modified letters (such as á) are converted to their base letter.
+- The German umlauts are converted into their diphthongs (ä &rArr; ae, …).
+- `ß` is converted into `ss`.
+- Apostrophes are removed.
+- Other special characters are replaced with `-`, but note that if there are multiple hyphens directly after another, merge them to just one hyphen.
+
+## Property Order
+
+The order of properties follows the order in which they are listed in the official publications. Exceptions are the `src` and the `translation` properties, which always occur at the end of an object. The order of properties can also be checked out in the respective schema file.
+
+Some entities also offer a template in the `/Templates` folder, which, if it's schema is called `X.schema.json`, is called `X.yml`. You can use that to create new files more easily and also automatically conform to the property order.
+
+## Schema File Names
+
+### Form
+
+`<Entity>.schema.json`
+
+#### Parameters
+
+- `<Entity>` is the entity name in pascal case. An `_` has to be prepended to the entity name if the entity does not represent an entire entity but instead is only used as a sub-schema for other schemes.

docs/Git-Workflow.md

@@ -0,0 +1,188 @@
+# Git Workflow
+
+Welcome to the introduction on how to contribute to Optolith static data using Git!
+
+You'll need a [GitHub account](https://github.com) (which you probably have if you see this), [Git](https://git-scm.com/downloads) locally installed and a code editor. I'll explain the steps you need to take using [Visual Studio Code](https://code.visualstudio.com) (VSCode), because it's a very easy-to-use and lightweight editor. I will try to avoid the command line in this tutorial.
+
+This tutorial is intended for helpers who have not yet learned about Git and programming. If you are already familiar with both, just jump to a later point or skip the tutorial altogether!
+
+## Getting started
+
+Create a new GitHub account, if don't own one already.
+
+Install *Git*. You don't need to change any installation options, just click *Next*.
+
+Let's *clone* the *repository* onto your computer.
+
+A *respository* – or simply *repo* – is kind of a special folder with explicit version control. The source repo is online on GitHub.com – which is where you are probably reading this tutorial right now – but you can create copies of it on other computers so that you can work on them like in normal folders and files.
+
+Now you can create a local copy of the repo by using a command in the command line – this is the only time you need to do this!
+
+### On Windows:
+Open the Windows explorer and go to a folder where you would like to out the copy. Open the context menu in the folder while pressing `Shift` and select *Open PowerShell here* from the list.
+
+![](./images/Tutorial-1.png)
+
+Then run
+
+```shell script
+git clone https://github.com/elyukai/optolith-data.git
+```
+
+This will create a new folder named `optolith-data`, which contains the repo.
+
+If you want to give the folder a new name, instead use
+
+```shell script
+git clone https://github.com/elyukai/optolith-data.git folder
+```
+
+`folder` is the new folder's name.
+
+If you want to copy the repo into the current folder without an extra subdirectory, instead use
+
+```shell script
+git clone https://github.com/elyukai/optolith-data.git .
+```
+
+**Warning:** Don't put this folder inside a folder synced to a cloud service, since a lot of tiny files will not work with it and may crash your service.
+
+### On Mac:
+Open the finder and go *to the parent folder* of a folder where you would like to out the copy. Open the terminal, type `cd` and then drag the folder you want the repo in into the terminal. This will insert the path to the folder. It should roughly look like
+
+```shell script
+cd ~/path/to/folder
+```
+
+The space between `cd` and the folder path is important!
+
+Then run
+
+```shell script
+git clone https://github.com/elyukai/optolith-data.git
+```
+
+This will create a new folder named `optolith-data`, which contains the repo.
+
+If you want to give the folder a new name, instead use
+
+```shell script
+git clone https://github.com/elyukai/optolith-data.git folder
+```
+
+`folder` is the new folder's name.
+
+If you want to copy the repo into the current folder without an extra subdirectory, instead use
+
+```shell script
+git clone https://github.com/elyukai/optolith-data.git .
+```
+
+## Install and configure VSCode
+
+Follow the [Setting Up an Editor guide](./Setting-Up-an-Editor).
+
+## Begin your Work
+
+To start working on a new feature you need to create a new *branch*.
+
+*Branches* are a core feature of Git. A branch represents a special development status or direction. Branches build up on each other. You can branch off from an existing branch, but you can also merge a branch into another branch. The default branch is called `develop` – usually it is called `master` but the `master` branch in this repo has a different meaning. The `develop` branch is where all contributions are merged and it is also directly reflected in the newest prereleases of Optolith.
+
+To start contributing to a specific area and thus to create a new branch, you need to click on the active branch you are currently on in the status bar of VSCode. Make sure you are currently on the `develop` branch.
+
+![](images/Tutorial-4.png)
+
+This opens a list of available branches. You can switch to an existing branch or create a new branch (online branches have the `origin/` prefix, they will be downloaded if you select them).
+
+![](images/Tutorial-5.png)
+
+We're gonna create a new branch via `Create new branch...`. The name of the branch depends on what you want to do:
+
+- If you want to fix an issues, prefix the branch name with `fix/`, e.g. `fix/moa3-source-refs`.
+- If you want to add a new feature, e.g. add a section of a new book, prefix the branch name with `feature/`, e.g. `feature/moa3-spells`
+
+Type it into the next input field and hit enter.
+
+![](images/Tutorial-11.png)
+
+Now the active branch in the status bar should be what you just typed in. You created your first branch! Next to the branch name will be the symbol for an unpublished branch. You can click it an then it will be uploaded to GitHub.
+
+**Note:** You can and should create multiple branches if you are working on multiple areas at once. You can always switch between them. They are independent from each other.
+
+Now you can start editing the files. Even though this is called *repo* just use it as a normal file system! There are just some advantages over a default file system – because you can save versions!
+
+## Check out your current work
+
+You can see all changes made in the Git tab.
+
+![](images/Tutorial-6.png)
+
+In the beginning, this tab will not list any changes – because you haven't done anything yet!
+
+Once you change something (and save it) it will be shown here.
+
+![](images/Tutorial-7.png)
+
+While you edit you can see which lines are edited on the left side.
+
+![](images/Tutorial-8.png)
+
+You can also do a detailed comparison between the old version of the file and the one you edited if you click on a file in the Git tab.
+
+![](images/Tutorial-9.png)
+
+Once you think you came to a point where it would make sense to create a new version of a file – it can be you entered the first 20 entries of the section you want to add or you've finished for the day – you can create a new *commit*.
+
+A *commit* represents a new point in history for the repository. It contains all changes made since the last point. (You can also select which files to commit but I will not cover that here.) Commits are the actual *versions* in Git.
+
+To create a new commit, you go to the Git tab an insert a *commit message*. It can also span multiple lines. Please do always write meaningful commit messages so that everyone knows roughly what you did without checking out the actual file edits. You don't need write a lot, though. If there's anyone interested in the detailed changes, it's often easier to just checkout your changes – but a short commit message can make that way easier to understand.
+
+![](images/Tutorial-10.png)
+
+Now type `Ctrl+Enter` on Windows or `Cmd+Enter` on Mac or click on the checkmark above the commit message. VSCode will probably ask you if you want to commit unstaged changes because there are no staged changes. Yes, you want that.
+
+Now your list of changes will be clean. Instead, next to the active branch in the status bar there will be a counter indicating that there is one commit to *push* and no commit to *pull*.
+
+![](images/Tutorial-12.png)
+
+With *push* and *pull* you can *push* new commits from your local repo to the online repo or you can *pull* new commits from the online repo into your local repo.
+
+Both operations does VSCode automatically if you click on the counter (the sync functionality is also available without the counter; sometimes VSCode does not update the counter so you have to click on the sync icon).
+
+Now your commit is online. Let's check it out.
+
+## Working with GitHub
+
+In the *Code* tab on the repo's page is an option to switch branches. Clicking on that will show a list of all branches that are available online. At the time of writing there are exactly two branches – the `master` and my own `test` branch.
+
+![](images/Tutorial-13.png)
+
+Switch to your branch. It will now suggest to create a pull request.
+
+![](images/Tutorial-14.png)
+
+### Create a Pull Request (PR)
+
+A *Pull Request* (PR) is a request to merge the new commits from a certain branch into another branch – which is what you want: You want to merge your changes into the main development branch.
+
+Click on *Compare & pull request*.
+
+On the next page you can configure your PR. You can see the *base branch* and the *compare branch*. The *compare branch* will me merged into the *base branch*. So the *base branch* should always be `develop` and the *compare branch* should be your own branch.
+
+![](images/Tutorial-15.png)
+
+Then you can insert a title for what you're working on and describe it. Keep the title short and write more explanation into the comment section.
+
+![](images/Tutorial-16.png)
+
+Example:
+
+![](images/Tutorial-17.png)
+
+You'll get notified per e-mail if there are any comments and once you're done and your changes are approved, I will merge your PR. You don't need to do anything else then.
+
+*Please note that pull requests update if you push more commits to GitHub, so please don't close your already created pull requests. This way we can keep track of the changes and discuss them!*
+
+## Continue your work
+
+To start on a new feature, create a new branch as explained before. But you need to make sure that you branch off from `develop` and that there are no commits to pull! If you switch to `develop` and the sync indicator says there are one or more changes to pull (incoming changes) you need to sync first! Only then you should create a new branch.

docs/Home.md

@@ -0,0 +1,23 @@
+# Optolith Database Documentation
+
+Welcome to Optolith Static Source Data Documentation!
+
+This Wiki will cover a lot of questions you may have. Let's dive in!
+
+## Tutorials
+
+- [Git Workflow](./Git-Workflow) is a tutorial for Git and how we use Git. You don't need to have any experience with Git or coding in general, but if you have, you'll get through it way faster!
+- [Setting Up an Editor](./Setting-Up-an-Editor) ... there's nothing else to say what it covers.
+- [Insertion Workflow](./Insertion-Workflow) is a guide on how to start inserting new content, what you need to know and watch out for.
+- [Translation Workflow](./Translation-Workflow) is a guide on how to start translating existing content, what you need to know and watch out for.
+- [Testing](./Testing) tells you how you can test your work.
+
+## References
+
+- [Conventions](./Conventions) is a list of "coding" conventions you should follow.
+- [Markdown](./Markdown) is a small guide for text formatting in Optolith, which uses Markdown syntax to style text. You'll get an overview as well as some do's and dont's.
+- [Index of Types](./Index-of-Types) is an overview of all available entities and subschemas, where you can check out specific ones and see what each property is used for.
+
+## External use
+
+- [Using the database in your own project](./Using-the-database-in-your-own-project) gives you some hints and recommendations on how to use the Optolith database in your own projects.

docs/Index-of-Types.md

@@ -0,0 +1,22 @@
+# Index of Types
+
+## Entities
+
+A list of all entities in the Optolith Database.
+
+- [Attribute](reference/Attribute)
+<!-- - [Close Combat Technique](reference/CloseCombatTechnique)
+- [Locale](reference/Locale)
+- [Publication](reference/Publication)
+- [Ranged Combat Technique](reference/RangedCombatTechnique) -->
+- [Experience Level](reference/ExperienceLevel)
+- [State](reference/State)
+
+## Shared Types
+
+Shared types are types that are shared between multiple entities.
+
+<!-- - [Locale Map](reference/LocaleMap)
+- [Improvement Cost](reference/ImprovementCost) -->
+- [Erratum](reference/_Erratum)
+- [Publication Reference](reference/_PublicationRef)

docs/Insertion-Workflow.md

@@ -0,0 +1,69 @@
+# Insertion Workflow
+
+This guide covers how you can get started inserting new content into Optolith as well as some best practises we discovered over the past years. (Feel free to tell us yours!)
+
+**Note:** If you want to *translate* existing content, please check out [Translation Workflow](./Translation-Workflow) instead.
+
+## Basics
+
+First, let's get into some basics.
+
+### Repository File Structure
+
+There are three folders used for static data: `/Data`, `/Templates` and `/Schema`.
+
+The `/Data` folder contains another set of folders as well as a `SupportedLanguages.yaml`, which contains all languages that *should be available* in Optolith. Each folder in `/Data` contains all entries of a specific type.
+
+While `/Data` holds all actual contents, `/Schema` contains structural definitions (schemes) for each subfolder in `/Data` about how a file should look like. Additionally `/Schema` contains some utility schema files that are used by multiple main schemes.
+
+`/Templates` comes as the bridge in between the previous two: prepared forms to fill out, matching the names of the schemes and the respective folder in `/Data`, simplify adding new content.
+
+### Editor Validation
+
+If you have a YAML validator editor plugin, use the `*.schema.json` files to validate your YAMLs. Using them will usually get you a few benefits besides inline validation such as autocompletion.
+
+The mapping is already provided for the [YAML plugin for Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml) - you don't have do do anything then besides installing the plugin. If you use a different editor, you can create your mappings based on the `.vscode/settings.json#yaml.schemes` definitions.
+
+### General structure of entries
+
+Each entry has its own file, which contains both the language-independent values (e.g. Improvement Cost or AP value) and the language-dependent values (e.g. rules text or name).
+
+## Get started
+
+Now you've got some basic knowledge. But how do you actually insert new data?
+
+I would recommend to check out existing data first to understand what is does. Take a data file and open the corresponding reference (~~either~~ the schema file ~~or the [type reference](./Entities), although the type reference is way easier to read if you are not used to JSON schema files~~) and then see if you understand what happens. If you have any problems, feel free to ask for help on the Discord server! Then you'll have less problems and I can improve the documentation!
+
+Also, don't start with complex entries! Advantages, disadvantages, special abilities and professions are the most complex entries. Try adding spells or cantrips instead!
+
+Always feel free to ask for reviews or hints on the Discord server, if you feel you need some!
+
+## What to watch out for
+
+### Duplicates
+
+It is important to always check for duplicates. They may be entries with the same name but different parameters, though. In those cases, please tell me via Discord or in the pull request on GitHub.
+
+### File Names
+
+Please see the [Conventions](https://github.com/elyukai/optolith-data/wiki/Conventions#data-file-names) for more details.
+
+### Formatting
+
+Keep in mind that there are quite a few texts that have some kind of text formatting (bold, italic, lists, etc) – you need to apply that to the texts in the YAMLs, too – but only for those where Markdown will be transformed into actual formatting. You can see which fields support Markdown syntax in the reference. Check out the [Markdown Guide for Optolith](./Markdown) to get more info about Markdown.
+
+### Multi-page entries
+
+Entries might span multiple pages. In those cases, use `firstPage` **as well as** `lastPage`.
+
+### New Applications and Uses
+
+Skills may get *New Applications* and *Uses* from advantages or special abilities. Those need to be registered at the advantage or special ability or one of its select options using the `skillApplications` and `skillUses` properties, otherwise it will not be available in the library entry as well as for other entries like Skill Specialization.
+
+### Missing Punctuation
+
+From time to time, the source you are transferring into the database has small formating errors or missing punctuation. [Here](https://github.com/elyukai/optolith-client/issues/335) is an issue where we keep track of them. In the meantime, please add the corrected version (e.g. sentences with punctuation) to the database.
+
+## Recommendations
+
+If you need to search for entry ids, I highly recommend global search (in VSCode: the search icon in the left bar or `Ctrl+Shift+F`). If you start the beginning of the entry names with a `"`, you'll get more accurate search results. If you know the English name of an entry or you are searching for an id of a specific group, you can press `Ctrl+P` (in VSCode) and type in the id as well as the group, separated by a space. Since the entries always have their id and their English name as the filename and the group as the folder name, you can find them pretty easy that way.

docs/Markdown.md

@@ -0,0 +1,121 @@
+# Markdown
+
+You might notice that some field descriptions say *Markdown is available*. But what is Markdown?
+
+Markdown is an easy-to-use formatting language. You can do basic text formatting with Markdown, like you can do with HTMl, for example – but it is waay easier to use, as you don't need to learn a lot of syntax and tags. You're probably familiar with text formatting in chat apps. You can surround phrases with `_` or `*` or something else to make them appear italic or bold. Markdown is also that easy.
+
+I will give a basic overview about the features you'll need, but you can check out [markdownguide.org](https://www.markdownguide.org/cheat-sheet) to see what you can do with Markdown. If you need a complete introduction, there are further helpful pages on the site.
+
+Please always style texts *exactly* as they are in the books.
+
+## Common Features
+
+### Paragraphs
+
+If there are multiple paragraphs, you can separate them with two line breaks.
+
+Example:
+
+```md
+This is the first paragraph.
+
+This is the second paragraph.
+```
+
+⇒
+
+This is the first paragraph.
+
+This is the second paragraph.
+
+### Bold
+
+Surround the text with `**`.
+
+Example: `This text is **bold**.` ⇒ This text is **bold**.
+
+### Italic
+
+Surround the text with `*`.
+
+Example: `This text is *italic*.` ⇒ This text is *italic*.
+
+### Strike-through
+
+Surround the text with `~~`.
+
+Example: `This text is ~~strike-through~~.` ⇒ This text is ~~strike-through~~.
+
+**Note:** "Negative" prerequisites use ~~strike-through~~ instead of pronouns. This might need to be used if you have to manually write down prerequisites as text.
+
+### Unordered lists
+
+```md
+- First item
+- Second item
+- Third item
+```
+
+⇒
+
+- First item
+- Second item
+- Third item
+
+### Spell names
+
+Surround the spell's name with an HTML tag and write the name in ‘sentence case’ instead of ‘uppercase’.
+
+Example: FLIM FLAM will be
+
+```md
+<span class="name--spell">Flim Flam</span>
+```
+
+### Liturgical Chant names
+
+Surround the chant's name with an HTML tag and write the name in &lsquo;sentence case&rsquo; instead of &lsquo;small caps&rsquo;.
+
+Example: <span style="font-variant: small-caps;">Banish Light</span> will be
+
+```md
+<span class="name--chant">Banish Light</span>
+```
+
+## Limitations
+
+- Do not use HTML tags other than the two mentioned above!
+- Currently, you have to use unordered lists to display e.g. spell effect texts with different effects per QL.
+
+## YAML tips & tricks
+
+### Paragraphs
+
+```yaml
+key: "This is the first paragraph.\n\nThis is the second paragraph."
+```
+
+Instead of a plain string, use a [literal style block](https://yaml.org/spec/1.2/spec.html#id2795688) (I also call them *block texts*), which looks like the following:
+
+```yaml
+key: |
+  This is the first paragraph.
+
+  This is the second paragraph.
+```
+
+This way, you can insert line breaks as they are (instead of using `\n` as the line break character), which makes the text way more readable. Just keep in mind, that you need to take care of the **indentation**: It must always be **two spaces more** than the key.
+
+You can still use double-quoted strings for Markdown text without line breaks.
+
+### C&P walls of text
+
+Additionally if you copy-paste from PDFs, you will get several lines instead of one. Getting all the text in one line including spaces can be quite time consuming. The feature *Join Lines* allows to merge selected multiple lines into one line, separating the lines with a space.
+
+If it does not have a keybinding already, use **Ctrl+Shift+P**, search for "Join Lines" and click on the gear icon. You get to a view where you can add a new keybinding. A good idea would be **Ctrl+J**, with J like join. It is already in use, but for something you don't need anyways (and has a second keybinding).
+
+### Advanced Search
+
+You can open a better search if you press **Ctrl+Shift+P** and type "Search Editor" in the Pop-Up to create a new Search Editor. In this new tab you can click on the three dots on the right side to open two lines for files to (not) search in.
+
+If you are for example adding Liturgical Chants and have to frequently look up Churches, Aspects and if the chant already exists, you could add `./Data/Aspects, ./Data/BlessedTraditions, ./Data/LiturgicalChants` to the first line to easily filter the available and fastly find the necessary information.

docs/Setting-Up-an-Editor.md

@@ -0,0 +1,37 @@
+# Setting Up an Editor
+
+Editing the YAML files with a proper editor will make it much easier to work with. You don't need any coding knowledge or editor knowledge, but it will help you a lot.
+
+I recommend [Visual Studio Code](https://code.visualstudio.com) (VSCode), since it's lightweight and very easy to use. I will use it for all tutorials here. Bonus: I also use it to work on Optolith, so the configuration you need is already present.
+
+## 1. Install an editor
+
+Install *Visual Studio Code* from the page linked above. (or another editor of your choice). I'd recommend to check *Add "Open with Code" to file context menu* and *Add "Open with Code" to directory context menu*.
+
+## 2. Open the Project
+
+*This step assumes you either cloned the repo by following the [Git Workflow](./Git-Workflow) or got the project folder from me.*
+
+If you checked the context menu additions during the installation process, you can open the context menu of the project folder and select *Open with Code*. Otherwise you can open VSCode and select the repo folder via `File > Open Folder...`. *It is important to open the project folder!*
+
+![](images/Setting-Up-an-Editor-1.png)
+
+This should be the initial folder structure you can check out. `Data` contains all data, while `Schema` contains the schemes for the data files.
+
+## 3. Activate Schema validation
+
+*Schemes* validate files and the editor can highlight errors so you can easily fix them. To get schema validation in VSCode, you need to install the YAML extension from RedHat.
+
+![](images/Setting-Up-an-Editor-2.png)
+
+The configuration for the VSCode YAML extension is already present, so you don't need to configure the schemes yourself.
+
+## 4. Done!
+
+Now you should see explanations of fields if you hover over them:
+
+![](images/Setting-Up-an-Editor-3.png)
+
+You'll also get autocompletion if you start typing or press `Ctrl+Space` (Windows, Linux) or `Cmd+Space` (macOS):
+
+![](images/Setting-Up-an-Editor-4.png)

docs/Testing.md

@@ -0,0 +1,9 @@
+# Testing
+
+This small guide covers how to test changes to the data with Optolith.
+
+You can (and probably should) check if what you worked on, first of all, is valid and, second, does what you expect.
+
+To do that, you'll need a prerelease version. You'll get a link either on the Discord server or in an e-mail. If you don't have a prerelease installed yet, install it now. It will be installed separately from your stable installation and it will also not affect your characters in your stable, so you're pretty safe to do that.
+
+Go to the installation folder and then in the `resources/app.asar.unpacked/app/Database`. You'll notice there are a lot of folders that are in the `Data` folder of the project as well. Copy the files and folders from the `Data` folder into `resources/app.asar.unpacked/app/Database` so they match the existing folder structure. Then, (re)start the Optolith prerelease. You should now see your changes and can try them out. If the source files are invalid, there'll be an alert and you won't see the characters list.

docs/Translation-Workflow.md

@@ -0,0 +1,65 @@
+# Translation Workflow
+
+This page aims at people who want to translate existing content into another, possible new, language.
+
+**Note:** If you want to *add* new content, please check out [Insertion Workflow](./Insertion-Workflow) instead.
+
+***Disclaimer:** It is not as complicated as it may sound, it also does not require any coding! Feel free to ask me any questions!*
+
+*This tutorial assumes you got the project folder (either as a plain folder or by following the [Git Workflow](./Git-Workflow)) and an [editor set-up](./Setting-Up-an-Editor).*
+
+## 0. Register a new language
+
+*This only applies if you want to add a new language.*
+
+Open the `Data/SupportedLanguages.yaml` file and add a new entry. The new entry consists of:
+
+- An *IETF BCP 47 language tag*. Such a language tag is formatted so that in `xx-YY` the `xx` are the language code (e.g. `de` for German or `nl` for Dutch) and the `YY` are the region code (e.g. `DE` for Germany and `BE` for Belgium). If you're not sure what to use, please ask.
+- The name of the language and associated region in the respective language.
+
+Now Optolith knows of that addional language and will be able to automatically infer it from you system (if you chose *System language*) and it will provide it as an option in the settings as well.
+
+Also, create a new folder in `Data` which name is the language tag of the new language.
+
+## 1. Copy files/entries
+
+Copy the files you want to translate if they are not present in your language's folder from the folder of the language you want to translate from. Otherwise go into the files where you want to translate entries from and copy/paste those entries into the files in your language folder.
+
+## 2. Update entries
+
+The follwing two parts should be followed at the same time, so you only need to go through every list of entries once.
+
+### 2.1 Replace texts
+
+Replace *all* text values (those to the right of the colons) with the translated strings.
+
+You may notice some special characters, usually in *block texts*. These are *Markdown syntax*. You can find more information about that on the [Markdown page](./Markdown).
+
+If your texts include formatting like italic or bold text, please also apply that to the texts in Optolith via Markdown.
+
+### 2.2. Update books and book references
+
+Optolith checks if an entry can be used by their occurrences in publications. First, you need to have the new books available in the `Books.yaml`, so you know which `id`s they have (for the currently available languages, the publisher's own publication id was used, like `US25001` for the German Core Rules or `LDR1` for French Core Rules). Then, you can update the references in the `src` attribute. Please remove the old ones, since they reference books from a different language.
+
+If an entry spans a range of pages, please add a `lastPage` in addition to the `firstPage`. If there are multiple, not consecutive pages, you can just add a second `src` entry. Why adding mutliple entries? The publication references will be available to the Optolith users as well. If you provide all pages, they can check out the publications more easily.
+
+## 3. Test your work
+
+See the [Testing guide](./testing) for more information.
+
+## 4. Commit
+
+You can now follow the [Git Workflow](./Git-Workflow) to commit and push the changes (if you're familiar with Git, you won't need that, of course).
+
+## Notes
+
+- **New Applications/Uses:** If you add advantages or special abilities that add *new applications* or *uses* to skills, make sure to check for the correct `id` of that application/use in more complete languages and then add the new application or use to the skill entry.
+- `UI.yaml`: This is the only files that’s kind of that “key=value” schema often used for translation files. Every key is required, but if there are terms you don’t have translations for currently, you can leave them in English, they will not be shown (since they probably won’t be used by any entry then). Also, you may notice some numbers in curly braces like “{0}”. These are placeholders for values that will be inserted by Optolith; what each value represents should be written in a comment above that text.
+- **Comments:** Feel free to add comments to any YAML file if you need them, you just need to write a `#` and the part of the line after that can be used as a comment.
+
+  Example:
+
+  ```yaml
+  key: "This is a text" # This is a comment
+  # This is another comment
+  ```

docs/Types.md

@@ -0,0 +1,118 @@
+# Types
+
+The documentation uses specific data types to explain how the entered data should look like. This structure is enforced by the used JSON schema (that verifies your input in the editor) as well as by Optolith. Below you'll find a list of standard types that are used across all entry types. There will also be other types specific to some entries, which are defined in files other than this one. You can always click on the special type to check out its definition. The standard types are not linked to, since you can find all of them here.
+
+## Records and fields
+
+The base structure used in entry types for Optolith is the *record*, which is an object with a fixed set of *fields*, each storing another value of a specific type. This can be another record or a different type. A record is always given a name and if a record is used as a type somewhere else, its name is used.
+
+```yaml
+property1: "A string."
+pro
+```
+
+## Standard Types
+
+Name | Description | Examples
+:-- | :-- | :--
+`String` | A text. | `"Courage"`, `"Seduction"`
+`Markdown` | A text that can be enhanced using Markdown syntax. | See [String definition vs. Markdown definition](#Markdown)
+`Bool` | A boolean value. | `true`, `false`
+`Int` | An integer. | `1`, `-2`
+`Float` | A floating-point number. | `1.0`, `1.25`
+`Date` | RFC 2822 or ISO 8601 date string. | `2021-07-10`
+`[…]` | Brackets mean that the type specified within (e.g. `[String]`) is in a list. | See [Lists](#Lists)
+`…?` | A question mark at the end of a property type means that this property can be left out, if a set value is not applicable to a specific entry. | See [Options](#Options)
+`"…" \| "…" of …` | Records with different cases. | See [Variants](#Variants)
+`(…,…)` | Parenthesis with at least one comma represent a tuple, which is represented as a list of a specific length, e.g. `(String, Int)` or `(Int, Int, Int)`. | See [Lists](#Lists)
+
+## <a name="Markdown"></a>String definition vs. Markdown definition
+
+A YAML string should be defined with double quotes.
+
+```yaml
+property_with_a_string: "A string."
+```
+
+A Markdown string should be defined using the YAML block syntax to make text editing with paragraphs more natural.
+
+```yaml
+property_with_a_markdown_string: |
+  First paragraph in Markdown.
+
+  Second paragraph with a **bold** text.
+```
+
+Notice the bar after the property name and the indented text. A paragraph is made using a blank line.
+
+## <a name="Lists"></a>Lists
+
+A list is made using hyphens and should be indented.
+
+```yaml
+property_with_an_int_list:
+  - 1
+  - 2
+  - 3
+```
+
+## <a name="Options"></a>Options
+
+An optional property can be left out.
+
+Given the following record definition:
+
+Name | Type
+:-- | :--
+`id` | `integer`
+`name` | `string?`
+
+This record is valid:
+
+```yaml
+id: 1
+name: "Fancy record"
+```
+
+But this record is valid, too:
+
+```yaml
+id: 1
+```
+
+## <a name="Variants"></a>Variants
+
+There can be records that have different shape between use cases (*cases*) of that record. Such records are called *variants*, also known as *tagged unions* or *discriminated unions*. They have one specific field, the *tag* or *discriminator*, which indicates the *case* and thus, which other fields and corresponding types the record features. In this database, this field is called `tag` and this name is solely used for this purpose. So anytime you see a field called `tag`, you know there is a variant.
+
+Variants don't *need* to have a different shape for each case. Variants for entry identifiers often consist of just a `tag` and a `value`, where the `value` is the identifier of the entry in the category specified by the `tag`.
+
+```yaml
+skill_id:
+  tag: Skill
+  value: 1 # -> Flying
+
+attribute_id:
+  tag: Attribute
+  value: 8 # -> Strength
+```
+
+There can be *constant* and *non-constant* variant cases. Constant cases just consist of a *tag*, which makes it the only possible value for that case, which makes it *constant*. Non-constant cases feature additional record fields.
+
+A constant case's type definition is marked with double quotes, for example `"CoreRules" | "ExpansionRules" | "Sourcebook" | "RegionalSourcebook"` is used as the type of the respective publication.
+
+```yaml
+type:
+  tag: CoreRules
+```
+
+A non-constant case's type definition has the form `"tag" of Record`, where `"tag"` is the used tag name and `Record` is a reference to the additional fields of that variant case, defined as a normal record.
+
+```yaml
+type:
+  tag: Attribute
+  value: 2
+```
+
+Note that in the YAML files, a variant tag is **not** wrapped in double quotes, as opposed to a normal string.
+
+In very rare cases you may see a plain type instead of tag, e.g. `Int | …`. In those cases it can be an integer *or* something else. This is typically bad for parsing, so it is usually not used. In certain edge cases, where a proper variant would be too much to handle for manual input, as well as for backwards compatibility reasons, you may encounter such type of variant.

docs/Using-the-database-in-your-own-project.md

@@ -0,0 +1,10 @@
+# Using the database in your own project
+
+If you're using the Optolith database for your own project, this page is for you. Here you'll find some best practices for working with the database.
+
+Also, if you've worked with the database previously, feel free to share your insights here as well!
+
+- **Do not** rely on the entries' file names. They are meant as a help for database editors and thus may change, which will *not* be considered a breaking change. Instead, only rely on the numeric identifier of each entry, which you can usually find at the `id` property in each file. It is reflected in the file name and tests ensure the match, but it is safer to rely on the file contents only.
+- **Do not** rely on the consistence of magical tradition placeholder identifiers, they may be replaced with a proper magical tradition special ability at any time, which is *not* considered a breaking change.
+
+Lastly, please don't forget to credit The Optolith Project, since a lot of work and ❤ went into this database. Thank you! 🥰