Adjusted docs layout to fix table of content

docs/developers/Building_macOS.md

@@ -1,4 +1,4 @@
-# Requirements
+## Requirements
 
 1. C++ toolchain, either of:
     - Xcode Command Line Tools (aka CLT): `sudo xcode-select --install`
@@ -9,7 +9,7 @@
     * Ninja: `brew install ninja` or get it from <https://github.com/ninja-build/ninja/releases>
     * CCache to speed up recompilation: `brew install ccache`
 
-# Obtaining source code
+## Obtaining source code
 
 Clone <https://github.com/vcmi/vcmi> with submodules. Example for command line:
 
@@ -17,11 +17,11 @@ Clone <https://github.com/vcmi/vcmi> with submodules. Example for command line:
 git clone --recurse-submodules https://github.com/vcmi/vcmi.git
 ```
 
-# Obtaining dependencies
+## Obtaining dependencies
 
 There're 2 ways to get dependencies automatically.
 
-## Conan package manager
+### Conan package manager
 
 Please find detailed instructions [here](./Conan.md). Note that the link points to the state of the current branch, for the latest release check the same document in the [master branch](https://github.com/vcmi/vcmi/blob/master/docs/developers/Сonan.md).
 
@@ -32,7 +32,7 @@ On the step where you need to replace **PROFILE**, choose:
 
 Note: if you wish to build 1.0 release in non-`Release` configuration, you should define `USE_CONAN_WITH_ALL_CONFIGS=1` environment variable when executing `conan install`.
 
-## Homebrew
+### Homebrew
 
 1. [Install Homebrew](https://brew.sh/)
 2. Install dependencies: `brew install boost minizip sdl2 sdl2_image sdl2_mixer sdl2_ttf tbb`
@@ -41,7 +41,7 @@ Note: if you wish to build 1.0 release in non-`Release` configuration, you shoul
     - `brew install qt@5` for Qt 5 or `brew install qt` for Qt 6
     - using [Qt Online Installer](https://www.qt.io/download) - choose **Go open source**
 
-# Preparing build environment
+## Preparing build environment
 
 This applies only to Xcode-based toolchain. If `xcrun -f clang` prints errors, then use either of the following ways:
 
@@ -49,7 +49,7 @@ This applies only to Xcode-based toolchain. If `xcrun -f clang` prints errors, t
 - use `xcode-select` utility to set Xcode or Xcode Command Line Tools path: for example, `sudo xcode-select -s /Library/Developer/CommandLineTools`
 - set `DEVELOPER_DIR` environment variable pointing to Xcode or Xcode Command Line Tools path: for example, `export DEVELOPER_DIR=/Applications/Xcode.app`
 
-# Configuring project for building
+## Configuring project for building
 
 Note that if you wish to use Qt Creator IDE, you should skip this step and configure respective variables inside the IDE.
 
@@ -72,28 +72,28 @@ Note that if you wish to use Qt Creator IDE, you should skip this step and confi
 8. If you want to speed up the recompilation, add `-D ENABLE_CCACHE=ON`
 9. Now press Return
 
-# Building project
+## Building project
 
 You must also install game files to be able to run the built version, see [Installation on macOS](players/Installation_macOS.md).
 
-## From Xcode IDE
+### From Xcode IDE
 
 Open `VCMI.xcodeproj` from the build directory, select `vcmiclient` scheme and hit Run (Cmd+R). To build Launcher, select `vcmilauncher` scheme instead.
 
-## From command line
+### From command line
 
 `cmake --build <path to build directory>`
 
 - If using Makefiles generator, you'd want to utilize all your CPU cores by appending `-- -j$(sysctl -n hw.ncpu)` to the above
 - If using Xcode generator, you can also choose which configuration to build by appending `--config <configuration name>` to the above, for example: `--config Debug`
 
-# Packaging project into DMG file
+## Packaging project into DMG file
 
 After building, run `cpack` from the build directory. If using Xcode generator, also pass `-C `<configuration name> with the same configuration that you used to build the project.
 
 If you use Conan, it's expected that you use **conan-generated** directory at step 4 of [Conan package manager](Conan.md).
 
-# Running VCMI
+## Running VCMI
 
 You can run VCMI from DMG, but it's will also work from your IDE be it Xcode or Qt Creator.
 
@@ -105,7 +105,7 @@ Alternatively you can run binaries directly from the **bin** directory:
 
 CMake include commands to copy all needed assets from source directory into the **bin** directory on each build. They'll work when you build from Xcode too.
 
-# Some useful debugging tips
+## Some useful debugging tips
 
 Anyone who might want to debug builds, but new to macOS could find following commands useful:
 
@@ -114,6 +114,6 @@ Anyone who might want to debug builds, but new to macOS could find following com
 - To view dependency paths: `otool -L /Volumes/vcmi-1.0/VCMI.app/Contents/MacOS/vcmiclient`
 - To display load commands such as `LC_RPATH`: `otool -l /Volumes/vcmi-1.0/VCMI.app/Contents/MacOS/vcmiclient`
 
-# Troubleshooting
+## Troubleshooting
 
 In case of troubles you can always consult our CI build scripts or contact the dev team via slack.

docs/maintainers/Release_Process.md

@@ -1,15 +1,15 @@
-# Versioning
+## Versioning
 For releases VCMI uses version numbering in form "1.X.Y", where:
 - 'X' indicates major release. Different major versions are generally not compatible with each other. Save format is different, network protocol is different, mod format likely different.
 - 'Y' indicates hotfix release. Despite its name this is usually not urgent, but planned release. Different hotfixes for same major version are fully compatible with each other.
 
-# Branches
+## Branches
 Our branching strategy is very similar to GitFlow:
 - `master` branch has release commits. One commit - one release. Each release commit should be tagged with version `1.X.Y` when corresponding version is released. State of master branch represents state of latest public release.
 - `beta` branch is for stabilization of ongoing release. Beta branch is created when new major release enters stabilization stage and is used for both major release itself as well as for subsequent hotfixes. Only changes that are safe, have minimal chance of regressions and improve player experience should be targeted into this branch. Breaking changes (e.g. save format changes) are forbidden in beta.
 - `develop` branch is a main branch for ongoing development. Pull requests with new features should be targeted to this branch, `develop` version is one major release ahead of `beta`.
 
-# Release process step-by-step
+## Release process step-by-step
 
 ### Initial release setup (major releases only)
 Should be done immediately after start of stabilization stage for previous release

docs/modders/Animation_Format.md

@@ -4,7 +4,7 @@ VCMI allows overriding HoMM3 .def files with .json replacement. Compared to .def
 -   Modern graphics formats (targa, png - all formats supported by VCMI image loader)
 -   Does not requires any special tools - all you need is text editor and images.
 
-# Format description
+## Format description
 
 ``` javascript
 {
@@ -51,9 +51,9 @@ VCMI allows overriding HoMM3 .def files with .json replacement. Compared to .def
 }
 ```
 
-# Examples
+## Examples
 
-## Replacing a button
+### Replacing a button
 
 This json file will allow replacing .def file for a button with png images. Buttons require following images:
 1. Active state. Button is active and can be pressed by player
@@ -74,7 +74,7 @@ This json file will allow replacing .def file for a button with png images. Butt
 }
 ```
 
-## Replacing simple animation
+### Replacing simple animation
 
 This json file allows defining one animation sequence, for example for adventure map objects or for town buildings.
 
@@ -98,11 +98,11 @@ This json file allows defining one animation sequence, for example for adventure
 }
 ```
 
-## Replacing creature animation
+### Replacing creature animation
 
 TODO
 
-# Creature animation groups
+## Creature animation groups
 
 Animation for creatures consist from multiple groups, with each group
 representing one specific animation. VCMI uses groups as follows:

docs/modders/Bonus/Bonus_Range_Types.md

@@ -1,4 +1,4 @@
-# List of all Bonus range types
+## List of all Bonus range types
 
 - NO_LIMIT
 - ONLY_DISTANCE_FIGHT

docs/modders/Bonus/Bonus_Sources.md

@@ -1,4 +1,4 @@
-# List of all possible bonus sources
+## List of all possible bonus sources
 
 - ARTIFACT
 - ARTIFACT_INSTANCE

docs/modders/Bonus/Bonus_Types.md

@@ -1,6 +1,6 @@
 The bonuses were grouped according to their original purpose. The bonus system allows them to propagate freely betwen the nodes, however they may not be recognized properly beyond the scope of original use.
 
-# General-purpose bonuses
+## General-purpose bonuses
 
 ### NONE
 
@@ -31,7 +31,7 @@ On each turn, hides area in fog of war around affected town for all players othe
 
 - val: radius in tiles
 
-# Player bonuses
+## Player bonuses
 
 Intended to be setup as global effect, AI cheat etc.
 
@@ -49,7 +49,7 @@ Bonus that does not account for propagation and gives extra resources per day wi
 - subtype: resource identifier
 - val: - base resource amount to be multipled times number of owned towns
 
-# Hero bonuses
+## Hero bonuses
 
 ### MOVEMENT
 
@@ -287,7 +287,7 @@ Allows creature being upgraded to another creature (Gelu, Dracon)
 - subtype: identifier of creature that can being upgraded
 - addInfo: identifier of creature to which perform an upgrade
 
-# Artifact bonuses
+## Artifact bonuses
 
 ### SPELL_DURATION
 
@@ -362,7 +362,7 @@ Heroes affected by this bonus will not lose all movement points when embarking o
 
 Heroes affected by this bonus won't lose army when moving through whirlpool
 
-# Creature bonuses
+## Creature bonuses
 
 ### STACK_HEALTH
 
@@ -392,7 +392,7 @@ Increases starting amount of shots that unit has in battle
 
 - val: additional shots
 
-# Creature abilities
+## Creature abilities
 
 ## Static abilities and immunities
 
@@ -898,7 +898,7 @@ Affected unit is immune to all spells of a specified spell school
 
 Affected unit can be affected by all friendly spells even it would be normally immune to such spell.
 
-# Spell effects
+## Spell effects
 
 ### POISON
 
@@ -954,7 +954,7 @@ Affected unit is considered to be hypnotized and will be controlled by enemy pla
 
 Affected unit will never retaliate to an attack (Blind, Paralyze)
 
-# Others
+## Others
 
 ### NEGATIVE_EFFECTS_IMMUNITY
 

docs/modders/Bonus/Bonus_Updaters.md

@@ -1,7 +1,5 @@
 TODO: this page may be incorrect or outdated
 
-# List of Bonus Updaters
-
 Updaters come in two forms: simple and complex. Simple updaters take no
 parameters and are specified as strings. Complex updaters do take
 parameters (sometimes optional), and are specified as structs.

docs/modders/Bonus/Bonus_Value_Types.md

@@ -11,7 +11,7 @@ Total value of Bonus is calculated using the following:
 
 Semantics of INDEPENDENT_MAX and INDEPENDENT_MIN are wrapped, and first means than bonus total value will be at least INDEPENDENT_MAX, and second means than bonus value will be at most INDEPENDENT_MIN.
 
-# List of all bonus value types
+## List of all bonus value types
 
 -   ADDITIVE_VALUE
 -   BASE_NUMBER

docs/modders/Configurable_Widgets.md

@@ -1,15 +1,3 @@
-# Table of contents
-
-- [Introduction](#introduction)
-- [Tutorial](#tutorial)
-- [Documentation](#documentation)
-  - [Types](#types)
-  - [Configurable objects](#configurable-objects)
-  - [Basic widgets](#basic-widgets)
-  - [High-level widgets](#high-level-widgets)
-  - [Custom widgets](#custom-widgets)
-- [For developers](#for-developers)
-
 # Introduction
 
 VCMI has capabilities to change some UI elements in your mods beyond only replacing one image with another. Not all UI elements are possible to modify currently, but development team is expanding them.

docs/modders/Entities_Format/Biome_Format.md

@@ -1,4 +1,4 @@
-# General description
+## General description
 
 Biome is a new entity type added in VCMI 1.5.0. It defines a set of random map obstacles which will be generated together. For each zone different obstacle sets is randomized and then only obstacles from that set will be used to fill this zone.
 
@@ -19,13 +19,13 @@ If not enough biomes are defined for [terrain type](Terrain_Format.md), map gene
 }
 ```
 
-## List of possible types
+### List of possible types
 
 Possible object types: `mountain`, `tree`, `lake`, `crater`, `rock`, `plant`, `structure`, `animal`, `other`. Use your best judgement, ie. mushrooms are classified as plants and animal bones are classified as animals.
 
 Template Ids are keys used in [Map Objects](../Map_Object_Format.md)
 
-## Algorithm
+### Algorithm
 
 Currently algorithm picks randomly:
 

docs/modders/Entities_Format/Spell_Format.md

@@ -1,4 +1,4 @@
-# Main format
+## Main format
 
 ``` javascript
 {
@@ -144,7 +144,7 @@
 }
 ```
 
-# Animation format
+## Animation format
 
 TODO
 
@@ -163,11 +163,11 @@ TODO
 }
 ```
 
-# Spell level base format
+## Spell level base format
 
 Json object with data common for all levels can be put here. These configuration parameters will be default for all levels. All mandatory level fields become optional if they equal "base" configuration.
 
-## Example
+### Example
 
 This will make spell affect single target on all levels except expert, where it is massive spell.
 
@@ -180,7 +180,7 @@ This will make spell affect single target on all levels except expert, where it
 }
 ```
 
-# Spell level format
+## Spell level format
 
 TODO
 
@@ -242,15 +242,15 @@ TODO
 }
 ```
 
-# Configurable battle effects
+## Configurable battle effects
 
 **If spell have at least one special effect it become configurable spell and spell configuration processed different way**
 
-## Configurable spell
+### Configurable spell
 
 Configurable spells ignore *offensive* flag, *effects* and *cumulativeEffects*. For backward compatibility *offensive* flag define Damage effect, *effects* and *cumulativeEffects* define Timed effect.
 
-## Special effect common format
+### Special effect common format
 
 TODO
 
@@ -271,7 +271,7 @@ TODO
 }
 ```
 
-## catapult
+### Catapult
 
 TODO
 
@@ -290,7 +290,7 @@ TODO
 }
 ```
 
-## Clone
+### Clone
 
 TODO
 
@@ -306,7 +306,7 @@ Configurable version of Clone spell.
 }
 ```
 
-## Damage effect
+### Damage effect
 
 TODO
 
@@ -325,35 +325,35 @@ If effect is automatic, spell behave like offensive spell (uses power, levelPowe
 }
 ```
 
-## Dispel
+### Dispel
 
 TODO
 
-## Heal
+### Heal
 
 TODO
 
-## Obstacle
+### Obstacle
 
 TODO
 
-## Remove obstacle
+### Remove obstacle
 
 TODO
 
-## Sacrifice
+### Sacrifice
 
 TODO
 
-## Summon
+### Summon
 
 TODO
 
-## Teleport
+### Teleport
 
 TODO
 
-## Timed
+### Timed
 
 TODO
 
@@ -374,9 +374,9 @@ cumulativeEffects ignored)
 }
 ```
 
-# Additional documentation
+## Additional documentation
 
-## Targets, ranges, modifiers
+### Targets, ranges, modifiers
 
 TODO
 

docs/modders/Map_Objects/Market.md

@@ -1,4 +1,4 @@
-# Market schema
+## Market schema
 
 Since VCMI-1.3 it's possible to create customizable markets on adventure map.
 Markets can be added as any other object with special handler called "market".
@@ -28,7 +28,7 @@ Here is schema describing such object
 }	
 ```
 
-# Modes
+## Modes
 
 Mode parameter defines a way to exchange different entities. Multiple modes can be specified to support several types of exchange.
 Following options are supported:
@@ -73,7 +73,7 @@ Game logic prohibits using modes unavailable for faction
 "modes" : ["creature-experience", "artifact-experience"]
 ```
 
-# Offer
+## Offer
 
 This field allows to configure specific items available in the market. It can be used only for `resource-skill` mode
 

docs/modders/Map_Objects/Rewardable.md

@@ -1,34 +1,3 @@
-## Table of Contents
-- [Base object definition](#base-object-definition)
-- [Configurable object definition](#configurable-object-definition)
-- [Base object definition](#base-object-definition)
-- [Variables Parameters definition](#variables-parameters-definition)
-- [Reset Parameters definition](#reset-parameters-definition)
-- [Appear Chance definition](#appear-chance-definition)
-- [Configurable Properties](#configurable-properties)
-- - [Current Day](#current-day)
-- - [Resource](#resource)
-- - [Experience](#experience)
-- - [Hero Level](#hero-level)
-- - [Mana Points](#mana-points)
-- - [Mana Percentage](#mana-percentage)
-- - [Movement Points](#movement-points)
-- - [Movement Percentage](#movement-percentage)
-- - [Primary Skills](#primary-skills)
-- - [Secondary Skills](#secondary-skills)
-- - [Can learn skills](#can-learn-skills)
-- - [Bonus System](#bonus-system)
-- - [Artifacts](#artifacts)
-- - [Spells](#spells)
-- - [Can learn spells](#can-learn-spells)
-- - [Creatures](#creatures)
-- - [Creatures Change](#creatures-change)
-- - [Spell cast](#spell-cast)
-- - [Fog of War](#fog-of-war)
-- - [Player color](#player-color)
-- - [Hero types](#hero-types)
-- - [Hero classes](#hero-classes)
-
 ## Base object definition
 Rewardable object is defined similarly to other objects, with key difference being `handler`. This field must be set to `"handler" : "configurable"` in order for vcmi to use this mode.
 ```jsonc

docs/modders/Readme.md

@@ -1,4 +1,4 @@
-# Creating mod
+## Creating mod
 
 To make your own mod you need to create subdirectory in **<data dir>/Mods/** with name that will be used as identifier for your mod.
 Main mod is file called **mod.json** and should be placed into main folder of your mod, e.g. **Mods/myMod/mod.json**
@@ -157,16 +157,16 @@ Example: replacing single icon
 }
 ```
 
-# Publishing mods in VCMI Repository
+## Publishing mods in VCMI Repository
 
 This will allow players to install mods directly from VCMI Launcher without visiting any 3rd-party sites.
 
-## Where files are hosted
+### Where files are hosted
 
 Mods list hosted under main VCMI organization: [vcmi-mods-repository](https://github.com/vcmi/vcmi-mods-repository).
 Each mod hosted in it's own repository under separate organization [vcmi-mods](https://github.com/vcmi-mods). This way if engine become more popular in future we can create separate teams for each mod and accept as many people as needed.
 
-## Why Git / GitHub?
+### Why Git / GitHub?
 
 It's solve a lot of problems:
 
@@ -176,13 +176,13 @@ It's solve a lot of problems:
 - Tracking of changes for repository and mods. It's not big deal now, but once we have scripting it's will be important to keep control over what code included in mods.
 - GitHub also create ZIP archives for us so mods will be stored uncompressed and version can be identified by commit hash.
 
-## On backward compatibility
+### On backward compatibility
 
 Our mod list in vcmi-mods-repository had "develop" as primary branch. Daily builds of VCMI use mod list file from this branch.
 Once VCMI get stable release there will be branching into "1.0.0", "1.1.0", etc. Launcher of released version will request mod list for particular version.
 Same way we can also create special stable branch for every mod under "vcmi-mods" organization umbrella once new stable version is released. So this way it's will be easier to maintain two versions of same mod: for stable and latest version.
 
-## Getting into vcmi-mods organization
+### Getting into vcmi-mods organization
 
 Before your mod can be accepted into official mod list you need to get it into repository under "vcmi-mods" organization umbrella. To do this contact one of mod repository maintainers. If needed you can get own team within "vcmi-mods" organization.
 Link to our mod will looks like that: https://github.com/vcmi-mods/adventure-ai-trace

docs/modders/Translations.md

@@ -1,5 +1,3 @@
-# Translation system
-
 ## List of currently supported languages
 
 This is list of all languages that are currently supported by VCMI. If your languages is missing from the list and you wish to translate VCMI - please contact our team and we'll add support for your language in next release.
@@ -85,6 +83,7 @@ Translation of Map Editor is identical, except for location of translation files
 TODO: how to test translation locally
 
 ### Translation of Linux specific files
+
 #### Translation of AppStream metainfo
 
 The [AppStream](https://freedesktop.org/software/appstream/docs/chap-Metadata.html) [metainfo file](https://github.com/vcmi/vcmi/blob/develop/launcher/eu.vcmi.VCMI.metainfo.xml) is used for Linux software centers.
@@ -94,11 +93,11 @@ It can be translated using a text editor or using [jdAppStreamEdit](https://flat
 - Open `<VCMI>/launcher/eu.vcmi.VCMI.metainfo.xml`
 - Translate and save the file
   
-#### Desktop file
+##### Desktop file
 - Edit `<VCMI>/launcher/vcmilauncher.desktop` and `<VCMI>/launcher/vcmieditor.desktop`
 - Add `GenericName[xyz]` and `Comment[xyz]` with your language code and translation
 
-### Translation of Android Launcher
+##### Translation of Android Launcher
 - Copy `<VCMI>/android/vcmi-app/src/main/res/values/strings.xml` to `<VCMI>/android/vcmi-app/src/main/res/values-xyz/strings.xml` (`xyz` is your language code)
 - Translate this file
 
@@ -147,7 +146,7 @@ After you have exported translation and added mod information for your language,
 
 Use any text editor (Notepad++ is recommended for Windows) and translate all strings from this file to your language
 
-# Developers documentation
+## Developers documentation
 
 ### Adding new languages
 In order to add new language it needs to be added in multiple locations in source code:

docs/players/Bug_Reporting_Guidelines.md

@@ -1,6 +1,6 @@
 First of all, thanks for your support! If you report a bug we can fix it. But keep in mind that reporting your bugs appropriately makes our (developers') lifes easier. Here are a few guidelines that will help you write good bug reports.
 
-# Github bugtracker
+## Github bugtracker
 
 The main place for managing and reporting bugs is [our bugtracker](https://github.com/vcmi/vcmi/issues). When you are not logged in, you can only browse already reported bugs. To be able to report bugs you need to make an account there.
 

docs/players/Cheat_Codes.md

@@ -1,11 +1,9 @@
-# Cheat Codes
+## Cheat Codes
 
 Similar to H3, VCMI provides cheat codes to make testing game more convenient.
 
 To use cheat code, press `Tab` key or click/tap on status bar to open game chat and enter code. Most cheat codes have several alternative names, including name of this cheat code in H3:SoD
 
-## List of Cheat Codes
-
 ### Spells
 
 `nwcthereisnospoon` or `vcmiistari` or `vcmispells` - give a spell book, all spells and 999 mana to currently selected hero
@@ -103,7 +101,7 @@ Following commands can be used by any player in multiplayer:
 - - `!vote simturns abort` - abort simultaneous turns once this turn ends
 - - `!vote timer prolong X` - prolong base timer for all players by specified number of seconds
 
-# Client Commands
+## Client Commands
 
 Client commands are set of predefined commands that are supported by VCMI, but unlike cheats they perform utility actions that do not alter state of the gameplay. As of release 1.2 client commands can work by typing them in-game like cheats, preceded by symbol / (for example `/controlai blue`)
 

docs/players/Game_Mechanics.md

@@ -1,6 +1,6 @@
-# List of features added in VCMI
+## List of features added in VCMI
 
-## High resolutions
+### High resolutions
 
 VCMI supports resolutions higher than original game, which ran only in 800 x 600. It also allows a number of additional features:
 
@@ -10,7 +10,7 @@ VCMI supports resolutions higher than original game, which ran only in 800 x 600
 
 Assets from Heroes of Might & Magic III HD - Remake released by Ubisoft in 2015 - are **not** supported.
 
-## Extended engine limits
+### Extended engine limits
 
 Some of game features have already been extended in comparison to Shadow of Death:
 
@@ -23,9 +23,9 @@ Some of game features have already been extended in comparison to Shadow of Deat
 
 The list of implemented cheat codes and console commands is [here](Cheat_codes.md).
 
-# New mechanics (Optional)
+## New mechanics (Optional)
 
-## Stack Experience module
+### Stack Experience module
 
 VCMI natively suppoorts stack experience feature known from WoG. Any creature - old or modded - can get stack experience bonuses. However, this feature needs to be enabled as a part of WoG VCMI submod.
 
@@ -35,23 +35,23 @@ Stack experience interface has been merged with regular creature window. Among o
 - Abilities description contain information about actual values and types of bonuses received by creature - be it default ability, stack experience, artifact or other effect. These descriptions use custom text files which have not been translated.
 - [Stack Artifact](#stack-artifact-module). You can choose enabled artifact with arrow buttons. There is also additional button below to pass currently selected artifact back to hero.
 
-## Commanders module
+### Commanders module
 
 VCMI offers native support for Commanders. Commanders are part of WoG mod for VCMI and require it to be enabled. However, once this is done, any new faction can use its own Commander, too.
 
-## Mithril module
+### Mithril module
 
 VCMI natively supports Mithril resource known from WoG. However, it is not currently used by any mod.
 
-## Stack Artifact module
+### Stack Artifact module
 
 In original WoG, there is one available Stack Artifact - Warlord's Banner, which is related directly to stack experience. VCMI natively supports any number of Stack Artifacts regardless if of Stack Experience module is enabled or not. However, currently no mods make use of this feature and it hasn't been tested for many years.
 
-# List of bugs fixed in VCMI
+## List of bugs fixed in VCMI
 
 These bugs were present in original Shadow of Death game, however the team decided to fix them to bring back desired behaviour:
 
-## List of game mechanics changes
+### List of game mechanics changes
 
 Some of H3 mechanics can't be straight considered as bug, but default VCMI behaviour is different:
 
@@ -59,9 +59,7 @@ Some of H3 mechanics can't be straight considered as bug, but default VCMI behav
 - Battles. Hero that won battle, but only have temporary summoned creatures alive going to appear in tavern like if he retreated. 
 - Battles. Spells from artifacts like AOTD are autocasted on beginning of the battle, not beginning of turn.
 
-# List of extended GUI features
-
-## Adventure map
+## Adventure map features
 
 ### New Shortcuts
 
@@ -88,7 +86,7 @@ When hovering cursor over neutral stack on adventure map, you may notice additio
 
 Some windows and dialogs now display extra info and images to make game more accessible for new players. This can be turned off, if desired.
 
-## Battles
+## Battles features
 
 ### Stack Queue
 
@@ -161,15 +159,15 @@ Additional color are supported for text fields (e.g. map description). Uses HTML
 
 <span style="color:green">This is green</span>
 
-# Multiplayer
+## Multiplayer features
 
 Opening new Turn Option menu in scenario selection dialog allows detailed configuration of turn timers and simultaneous turns
 
-## Turn Timers
+### Turn Timers
 
 TODO
 
-## Simultaneous turns
+### Simultaneous turns
 
 Simultaneous turns allow multiple players to act at the same time, speeding up early game phase in multiplayer games. During this phase if different players (allies or not) attempt to interact with each other, such as capture objects owned by other players (mines, dwellings, towns) or attack their heroes, game will block such actions. Interaction with same map objects at the same time, such as attacking same wandering monster is also blocked.
 
@@ -178,8 +176,6 @@ Following options can be used to configure simultaneous turns:
 - Maximal duration (at most for): this is duration after which simultaneous turns will end unconditionally, even if players still have not contacted each other. However if contact detection discovers contact between two players, simultaneous turns between them might end before specified duration.
 - Simultaneous turns for AI: If this option is on, AI can act at the same time as human players. Note that AI shares settings for simultaneous turns with human players - if no simultaneous turns have been set up this option has no effect.
 
-### Contact detection
-
 While simultaneous turns are active, VCMI tracks contacts for each pair of player separately.
 
 Players are considered to be "in contact" if movement range of their heroes at the start of turn overlaps, or, in other words - if their heroes can meet on this turn if both walk towards each other. When calculating movement range, game uses rules similar to standard movement range calculation in vcmi, meaning that game will track movement through monoliths and subterranean gates, but will not account for any removable obstacles, such as pickable treasures that block path between heroes. Any existing wandering monsters that block path between heroes are ignored for range calculation. At the moment, game will not account for any ways to extend movement range - Dimension Door or Town Portal spells, visiting map objects such as Stables, releasing heroes from prisons, etc.
@@ -192,11 +188,11 @@ Game performs contact detection once per turn, at the very start of each in-game
 
 Once maximal duration of simultaneous turns (as specified during scenario setup) has been reached, or if all players are in contact with each other, game will return to standard turn order: red, blue, brown, green...
 
-### Differences compared to HD Mod version
+Differences compared to HD Mod version:
 
 - In VCMI, players can see actions of other players immediately (provided that they have revealed fog of war) instead of waiting for next turn
 - In VCMI, attempt to attack hero of another player during simultaneous turns will be blocked instead of reloading save from start of turn like in HD Mod
 
-# Manuals and guides
+## Manuals and guides
 
 - https://heroes.thelazy.net/index.php/Main_Page Wiki that aims to be a complete reference to Heroes of Might and Magic III. 

docs/players/Installation_Linux.md

@@ -2,9 +2,7 @@ VCMI requires data from original Heroes 3: Shadow of Death or Complete editions.
 
 # Step 1: Binaries installation
 
-## Ubuntu
-
-### Latest stable build from PPA (recommended)
+### Ubuntu - Latest stable build from PPA (recommended)
 
 Up-to-date releases can be found in our PPA here: <https://launchpad.net/~vcmi/+archive/ubuntu/ppa>
 
@@ -15,7 +13,7 @@ To install VCMI from PPA use:
     sudo apt install vcmi
 ```
 
-### Unstable testing build from PPA
+### Ubuntu - Unstable testing build from PPA
 
 We also provide latest, unstable builds mostly suitable for testing here: <https://launchpad.net/~vcmi/+archive/ubuntu/vcmi-latest>
 
@@ -25,7 +23,7 @@ In order to install from this PPA use:
     sudo apt update
     sudo apt install vcmi
 ```
-### From Ubuntu repository
+### Ubuntu - From Ubuntu repository
 
 VCMI stable builds available in "multiverse" repository. Learn how to enable it in [Ubuntu wiki](https://help.ubuntu.com/community/Repositories/Ubuntu).
 Once enabled, you can install VCMI using Ubuntu Store or in terminal using following commands:
@@ -35,7 +33,7 @@ Once enabled, you can install VCMI using Ubuntu Store or in terminal using follo
 ```
 Note that version available in Ubuntu is outdated. Install via PPA is preferred.
 
-## Debian
+### Debian
 
 Stable VCMI version is available in "contrib" repository. Learn how to enable it in [Debian wiki](https://wiki.debian.org/SourcesList).
 To install VCMI from repository:
@@ -43,14 +41,14 @@ To install VCMI from repository:
     sudo apt-get update
     sudo apt-get install vcmi
 ```
-## Flatpak (distribution-agnostic)
+### Flatpak (distribution-agnostic)
 
 Latest public release build can be installed via Flatpak.
 
 Depending on your distribution, you may need to install flatpak itself. You can find guide for your distribution here: <https://www.flatpak.org/setup/>
 Once you have flatpak, you can install VCMI package which can be found here: <https://flathub.org/apps/details/eu.vcmi.VCMI>
 
-## Other distributions
+### Other distributions
 
 For other distributions, VCMI can be installed from 3rd-party repositories listed below. Note that these repositories are not supported by vcmi team and may not be up to date.
 
@@ -59,15 +57,15 @@ For other distributions, VCMI can be installed from 3rd-party repositories liste
 
 If you are interested in providing builds for other distributions, please let us know.
 
-## Compiling from source
+### Compiling from source
 
 Please check following developer guide: [How to build VCMI (Linux)](../developers/Building_Linux.md)
 
-# Step 2: Installing Heroes III data files
+## Step 2: Installing Heroes III data files
 
 To install VCMI you will need Heroes III: Shadow of Death or Complete edition.
 
-## Install data using vcmibuilder script
+### Install data using vcmibuilder script
 
 Recommended for non-Flatpak installs.
 
@@ -91,7 +89,7 @@ On flatpak install, it's also possible to run the script, but any path seems to
 flatpak run --command=vcmibuilder eu.vcmi.VCMI --data /path/to/h3/data`
 ```
 
-## Install data using gog.com offline installer
+### Install data using gog.com offline installer
 
 Download both files for the "offline backup game installers" and extract them using innoextract tool
 
@@ -105,19 +103,19 @@ innoextract --output-dir=~/Downloads/HoMM3 "setup_heroes_of_might_and_magic_3_co
 
 Once innoextract completes, start VCMI Launcher and choose to place existing files. Select the ~/Downloads/HoMM3 directory. Once placing is complete, you can delete both offline installer files as well as ~/Downloads/HoMM3.
 
-## Install manually using existing Heroes III data
+### Install manually using existing Heroes III data
 
 Copy "Data", "Maps" and "Mp3" from Heroes III to `$HOME/.local/share/vcmi/`
 Or, in case of flatpak install to `$HOME/.var/app/eu.vcmi.VCMI/data/vcmi/`
 On some distributions $XDG_DATA_HOME could differ so instead you may need to use: `$XDG_DATA_HOME/vcmi/`
 
-# Step 3: Launching game
+## Step 3: Launching game
 
 VCMI should be available via desktop environment menu or launcher (Games/Strategy/VCMI)
 
 To start the game type in console: `vcmilauncher`
 Or, to start game directly avoiding Launcher: `vcmiclient`
 
-# Reporting bugs
+## Reporting bugs
 
 Please report any issues with packages according to [Bug Reporting Guidelines](Bug_Reporting_Guidelines.md)

docs/players/Installation_Windows.md

@@ -1,8 +1,8 @@
-# Prerequisites
+## Prerequisites
 
 As of VCMI 1.2 and newer Windows 10 or newer is required since our automated system uses elements incompatible with older Windows.
 
-# Step 1: Download and install VCMI
+## Step 1: Download and install VCMI
 
 Install one of following into new folder, same as when installing new game:
 
@@ -10,7 +10,7 @@ Install one of following into new folder, same as when installing new game:
 -   Daily builds (unstable): <https://builds.vcmi.download/branch/develop/Windows/>
 -   Please report about problems on GitHub: [Bug Tracker](https://github.com/vcmi/vcmi/issues)
 
-# Step 2: Installing Heroes III data files
+## Step 2: Installing Heroes III data files
 
 **Since VCMI 1.2 you can skip this step, just run VCMI launcher and it will help you with importing H3 data. For older releases you can follow this step.**
 
@@ -19,7 +19,7 @@ Install one of following into new folder, same as when installing new game:
 
 Create this folder if it doesnt exist yet
 
-# Step 3: connect to the mod repository
+## Step 3: connect to the mod repository
 
 - If that's your first installation, connection to the mod repository will be configured automatically, you'll see mods available to install from VCMI launcher -
 - We recommend you to install VCMI extras to support various helpful UI tweaks 

docs/players/Installation_macOS.md

@@ -1,6 +1,6 @@
-**For iOS installation look here: (Installation on iOS)[Installation_iOS.md]
+For iOS installation look here: (Installation on iOS)[Installation_iOS.md]
 
-# Step 1: Download and install VCMI
+## Step 1: Download and install VCMI
 
 - The latest release (recommended): <https://github.com/vcmi/vcmi/releases/latest>
 - Daily builds (might be unstable) 
@@ -11,7 +11,7 @@ If the app doesn't open, right-click the app bundle - select *Open* menu item -
 
 Please report about gameplay problem on forums: [Help & Bugs](https://forum.vcmi.eu/c/international-board/help-bugs) Make sure to specify what hardware and macOS version you use.
 
-# Step 2: Installing Heroes III data files
+## Step 2: Installing Heroes III data files
 
 ### Step 2.a: Installing data files with GOG offline installer