Improved mod overview documentation

docs/Modders/1-Mods.md

@@ -12,23 +12,12 @@ The game only knows how to recognize existing definitions, so you can't add *new
 
 There are three main kinds of mods:
 
--   **Extension mods** - these add new nations/units/buildings/resources to a base ruleset - can be either to the default ruleset, or to a base ruleset mod. Easy to do and probably the better place to get started.
+-   **Extension mods** - these add new nations/units/buildings/resources to a base ruleset - can be either to the default ruleset, or to a base ruleset mod. Easy to do and probably the better place to get started - for example, [creating a new Civilization](2-Making-a-new-Civilization.md)
 -   **Base Ruleset mods** - these replace the entire existing ruleset - tech tree, units, policies, nations etc - to give an entirely different experience than the base game. These generally require quite a bit of work, but give a whole new experience, and so are the most popular.
 -   **Ruleset-agnostic mods** - these do not contain any ruleset-related jsons, but instead contain other affects. Audiovisual mods (including tilesets, unitsets, and UI skins) and map mods are in this category.
 
 Creating and editing mods from your phone is NOT RECOMMENDED - it's *much easier* using a desktop device!
 
-## Audiovisual Mods
-
-In addition to changing the rules - or even without doing so, mods can override existing graphics or sounds, or add music tracks. The game also has the ability to display graphics that are not included in the base game at all, such as leader portrait or wonder splash images, that must be provided by mods. For details, see [Audiovisual Mods](3-Images-and-Audio.md).
-
-Custom tilesets and unitsets are a subgroup of these - see [Creating a custom tileset](4-Creating-a-custom-tileset.md) - as are UI skin mods, see [Creating a UI skin](5-Creating-a-UI-skin.md)
-
-Such mods are candidates for the "Permanent audiovisual mod" switch available on the Mod Management Screen.
-Note that this feature includes graphics or sounds from the selected mod in _all_ games, even those started before installing the mod.
-
-In case of a mod bringing both changed rules and audiovisuals, the 'permanent' feature will include only the media on all games, to use the rules you will still need to select the mod for a new game.
-
 ## Mod names
 
 Mods need to conform to github repo naming rules, but best stay simple and use only letters, digits, and dashes `-`.
@@ -42,16 +31,25 @@ Mods are located in a `/mods` directory, on Desktop that should be next to your
 
 Mods typically have 2 subfolders:
 
--   `jsons` - here you should put files that alter the data of game objects, the order of the files is as in [the base json files](https://github.com/yairm210/Unciv/tree/master/android/assets/jsons). More information on these can be found [here](Mod file structure/1-Overview.md)
+-   `jsons` - here you should put files that alter the data of game objects, the order of the files is as in [the base json files](https://github.com/yairm210/Unciv/tree/master/android/assets/jsons). More information on these can be found [here](Mod-file-structure/1-Overview.md)
--   `Images` - here you should put game images, as in [the base image files](/https://github.com/yairm210/Unciv/tree/master/android/Images). Please read [about atlases](#more-on-images-and-the-texture-atlas) for important details.
+-   `Images` - here you should put game images, as in [the base image files](/https://github.com/yairm210/Unciv/tree/master/android/Images).
-
+-
 In order to remove objects from the game, you'll need to create a ModOptions file in the `/jsons` subfolder - there's an example [here](https://github.com/yairm210/Unciv-mod-example/blob/master/Removing%20Things/jsons/ModOptions.json)
 
-In a base ruleset mod, ALL the original objects are removed - this is done by adding a `"isBaseRuleset":true` configuration to your modOptions file, [like so](https://github.com/k4zoo/Civilization-6-Mod/blob/master/jsons/ModOptions.json)
+**Base Ruleset Mods** are mods that 'start from scratch' - ALL the original objects are removed, and only the objects
 
-For an example, you can refer to [the example mod](https://github.com/yairm210/Unciv-mod-example) - just download the Example-Aliens-Mod and put it in a `/mods` folder next to the jar, run Unciv, start a new game, and you'll be able to enable the mod, which will allow to you pick Aliens as a playable civilization!
+This is done by adding a `"isBaseRuleset":true` configuration to your [modOptions file](Mod-file-structure/5-Miscellaneous-JSON-files.md#modoptionsjson), [like so](https://github.com/k4zoo/Civilization-6-Mod/blob/master/jsons/ModOptions.json)
 
-If you want to add a new civilization as a mod, you should check out [the Civ making instructions](2-Making-a-new-Civilization.md) to see what's required, or see the example Aliens mod =)
+## Audiovisual components
+
+In addition to changing the rules - or even without doing so - mods can override existing graphics or sounds, or add music tracks. For details, see [Audiovisual Mods](3-Images-and-Audio.md).
+
+Custom tilesets and unitsets are a subgroup of these - see [Creating a custom tileset](4-Creating-a-custom-tileset.md) - as are UI skin mods, see [Creating a UI skin](5-Creating-a-UI-skin.md)
+
+Such mods are candidates for the "Permanent audiovisual mod" switch available on the Mod Management Screen.
+Note that this feature includes graphics or sounds from the selected mod in _all_ games, even those started before installing the mod.
+
+In case of a mod bringing both changed rules and audiovisuals, the 'permanent' feature will include only the media on all games, to use the rules you will still need to select the mod for a new game.
 
 ### More on Images and the texture atlas
 
@@ -81,7 +79,7 @@ A mod can also be maps-only, if all you want to do is share your maps.
 
 When you've finished making your map in the Map Editor, save it, and it will be in the `/maps` folder of your game.
 
-Copy it to a `/maps` folder in your *mod*, and you're done!
+Copy it to a `/maps` folder in your mod, and you're done!
 
 ## Getting your mod out there
 
@@ -105,13 +103,13 @@ In order to do this, all you need to do is:
 
 Optionally add one or more of the following topics to mark your mod as belonging to specific categories:
 
--   unciv-mod-rulesets (for base ruleset mods)
+-   `unciv-mod-rulesets` (for base ruleset mods)
--   unciv-mod-expansions (for mods extending vanilla rulesets - please use this, **not** unciv-mod-expansion)
+-   `unciv-mod-expansions` (for mods extending vanilla rulesets - please use this, **not** unciv-mod-expansion)
--   unciv-mod-graphics (for mods altering graphics - icons, portraits, tilesets)
+-   `unciv-mod-graphics` (for mods altering graphics - icons, portraits, tilesets)
--   unciv-mod-audio (for mods supplying music or modifying sounds)
+-   `unciv-mod-audio` (for mods supplying music or modifying sounds)
--   unciv-mod-maps (for mods containing maps)
+-   `unciv-mod-maps` (for mods containing maps)
--   unciv-mod-fun (for mods mainly tweaking mechanics or other gameplay aspects)
+-   `unciv-mod-fun` (for mods mainly tweaking mechanics or other gameplay aspects)
--   unciv-mod-modsofmods (for mods extending another mod's ruleset)
+-   `unciv-mod-modsofmods` (for mods extending another mod's ruleset)
 
 When you open Unciv's Mod Manager, it will query Github's [list of repos with that topic](https://github.com/topics/unciv-mod), and now YOUR repo will appear there!
 The categories will appear als annotations on the mod buttons, and the user can filter for them. They are not required for the game to use the content - e.g. you can still load maps from mods lacking the unciv-mod-maps topic.
@@ -147,6 +145,9 @@ You can add an image that will be displayed to users in the mod management scree
 
 Existing mods can be found [here](https://github.com/topics/unciv-mod)!
 
-A list of uniques and how to use them can be found [here](Unique-parameters.md)!
+## What's next?
+
+Now you should try to create your first mod!
+
+We recommend you start off by [adding a new civilization](2-Making-a-new-Civilization.md) as a mod, to get a hang of the process :)
 
-Some images don't exist at all in the base game, but can be added in mods. For more info, see [Audiovisual Mods](3-Images-and-Audio.md).

docs/Modders/3-Images-and-Audio.md

@@ -62,12 +62,12 @@ For example, [here](https://github.com/vegeta1k95/Civ-5-Icons) is mod showing ho
 
 ### Adding icons for Unit Types
 
-The Unit Types as defined in [UnitTypes.json](Mod file structure/4-Unit-related-JSON-files.md#unittypesjson) have no icons in the base game, but Civilopedia can decorate their entries if you supply images named 'Images/UnitTypeIcons/<UnitType>.png'.
+The Unit Types as defined in [UnitTypes.json](Mod-file-structure/4-Unit-related-JSON-files.md#unittypesjson) have no icons in the base game, but Civilopedia can decorate their entries if you supply images named 'Images/UnitTypeIcons/<UnitType>.png'.
 (while you're at it, you may override the default icon for the Unit Type _category header_ - it's 'UnitTypes.png' in the same folder, or the icons used for the movement domains - 'DomainLand', 'DomainWater', 'DomainAir')
 
 ### Adding icons for Beliefs
 
-The individual Beliefs - as opposed to Belief types, as defined in [Beliefs.json](Mod file structure/2-Civilization-related-JSON-files.md#beliefsjson) have no icons in the base game, but Civilopedia can decorate their entries if you supply images named 'Images/ReligionIcons/<Belief>.png'.
+The individual Beliefs - as opposed to Belief types, as defined in [Beliefs.json](Mod-file-structure/2-Civilization-related-JSON-files.md#beliefsjson) have no icons in the base game, but Civilopedia can decorate their entries if you supply images named 'Images/ReligionIcons/<Belief>.png'.
 Civilopedia falls back to the icon for the Belief type - as you can see in the base game, but individual icons have precedence if they exist.
 
 ## Sounds

docs/Modders/Unique-parameters.md

@@ -150,7 +150,7 @@ These can be strung together with ", " between them, for example: `+2 Production
 
 ## technologyFilter
 
-At the moment only implemented for [ModOptions.techsToRemove](Mod file structure/5-Miscellaneous-JSON-files.md#modoptionsjson).
+At the moment only implemented for [ModOptions.techsToRemove](Mod-file-structure/5-Miscellaneous-JSON-files.md#modoptionsjson).
 
 Allowed values are: