-## Download and install
+## Download and Install
Please follow the [**installation guide**](docs/INSTALL.md) to download and install fheroes2.
@@ -40,7 +40,11 @@ Initially, the project was developed on [**sourceforge**](https://sourceforge.ne
This repository is a place for everyone. If you want to contribute, please read more [**here**](https://github.com/ihhub/fheroes2/wiki/F.A.Q.#q-how-can-i-contribute-to-the-project).
-To build the project from source, please follow [**this guide**](docs/DEVELOPMENT.md).
+To build the project from source, please follow
+[**this guide**](docs/DEVELOPMENT.md).
+
+To build the website from source, please follow
+[**this guide**](docs/WEBSITE_LOCAL_DEV.md).
[](https://github.com/ihhub/fheroes2/actions)
[](https://sonarcloud.io/dashboard?id=ihhub_fheroes2)
diff --git a/docs/.gitignore b/docs/.gitignore
new file mode 100644
index 000000000..9ada8715b
--- /dev/null
+++ b/docs/.gitignore
@@ -0,0 +1,8 @@
+_site
+
+node_modules
+
+# Gemfile
+Gemfile
+Gemfile.lock
+Gemfile.dev.lock
diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.md
index 9d483447b..2b80d0e2e 100644
--- a/docs/DEVELOPMENT.md
+++ b/docs/DEVELOPMENT.md
@@ -1,6 +1,6 @@
-# [**fheroes2**](README.md) build and contribution guide
+# [fheroes2](README.md) build and contribution guide
-## Build
+## Building the fheroes2 Project
Please follow the instructions below to be able to build the project from source:
@@ -51,6 +51,12 @@ If you would like to run this project in a web browser please follow the instruc
If you would like to build the project using CMake please follow the instructions on [**this page**](README_cmake.md).
+## Building the front end website
+
+We host the website on Github pages, which is a highly customized version of the
+Jekyll static site engine. The instructions for developing the website can be
+found in the [**website local dev**](WEBSITE_LOCAL_DEV.md) guide.
+
## Contribution
We welcome and appreciate any help, even if it is a tiny text or code change. Please read our
diff --git a/docs/GRAPHICAL_ASSETS.md b/docs/GRAPHICAL_ASSETS.md
index dc33e8148..703c1102c 100644
--- a/docs/GRAPHICAL_ASSETS.md
+++ b/docs/GRAPHICAL_ASSETS.md
@@ -1,4 +1,4 @@
-# [**fheroes2**](README.md) graphical artist guide
+# [fheroes2](README.md) Graphical Artist Guide
The original game has its graphical assets stored in the `HEROES2.agg` file and potentially the `HEROES2X.agg` file if the expansion
pack The Price of Loyalty is present. These two AGG files are located in the `DATA` folder of the original Heroes 2 installation.
@@ -10,15 +10,15 @@ New assets that the fheroes2 project adds to the game are included in the `files
This guide is designed for Linux, MacOS and Windows users. The source files to these tools are available in the project's repository.
-## Where to get the tools
+## Where to Get the Tools
-You can download the precompiled tools for your operating system (OS) of choice here:
-[Windows 32-bit](https://github.com/ihhub/fheroes2/releases/download/fheroes2-windows-x86-SDL2/fheroes2_tools_windows_x86_SDL2.zip)
+You can download the precompiled tools for your operating system (OS) of choice here:
+[Windows 32-bit](https://github.com/ihhub/fheroes2/releases/download/fheroes2-windows-x86-SDL2/fheroes2_tools_windows_x86_SDL2.zip)
[Windows 64-bit](https://github.com/ihhub/fheroes2/releases/download/fheroes2-windows-x64-SDL2/fheroes2_tools_windows_x64_SDL2.zip)
[MacOS](https://github.com/ihhub/fheroes2/releases/download/fheroes2-osx-sdl2_dev/fheroes2_tools_macos_x86-64_SDL2.zip)
-[Linux Ubuntu 64-bit](https://github.com/ihhub/fheroes2/releases/download/fheroes2-linux-sdl2_dev/fheroes2_tools_ubuntu_x86-64_SDL2.zip)
+[Linux Ubuntu 64-bit](https://github.com/ihhub/fheroes2/releases/download/fheroes2-linux-sdl2_dev/fheroes2_tools_ubuntu_x86-64_SDL2.zip)
[Linux Ubuntu ARM 64-bit](https://github.com/ihhub/fheroes2/releases/download/fheroes2-linux-arm-sdl2_dev/fheroes2_tools_ubuntu_arm64_SDL2.zip)
Here is a list and short description of the various graphical artist tools:
@@ -42,7 +42,7 @@ the top-left corner on a tile. Use these colors only if the animation is a requi
* 231, 232, 233, 234, 235
* 238, 239, 240, 241
-## How to use the tools to extract the images
+## How to Use the Tools to Extract the Images
Place the `HEROES2.agg` and optionally the `HEROES2X.agg` files in the same folder as you extracted the tools to.
Then run the script called `extract_agg`. This will create two folders: `agg` and `icn`. Both of them have a subdirectory named `HEROES2`,
@@ -55,7 +55,7 @@ Meanwhile, the folder named `icn` contains the PNG-converted graphical assets. T
ICN they were stored in, e.g. the folder `apanel` came from the ICN `apanel.icn`. The `icn` folder is in other words the most relevant one for
graphical artists.
-## Where is help needed
+## Where is Help Needed
We have labelled and tracked some issues that need help from graphical artists.
Issues that require changes of the original art can be found [here](https://github.com/ihhub/fheroes2/issues?q=is%3Aopen+is%3Aissue+label%3A"original+assets").
@@ -64,7 +64,7 @@ New art tasks can be found [here](https://github.com/ihhub/fheroes2/issues?q=is%
NOTE! Before starting to work on an issue make sure to check if someone isn't already assigned to it by looking at the relevant place
within the issue. Also notify the fheroes2 team that you wish to work on the issue. This is to avoid duplicate work.
-## The work process
+## The Work Process
1. Choose the item you are going to work on and notify the fheroes2 team to avoid duplicate work.
2. Present a prototype / complete enough work in your opinion of your work.
diff --git a/docs/Gemfile.dev b/docs/Gemfile.dev
new file mode 100644
index 000000000..0c8671cde
--- /dev/null
+++ b/docs/Gemfile.dev
@@ -0,0 +1,3 @@
+source "https://rubygems.org"
+
+gem "github-pages", group: :jekyll_plugins
diff --git a/docs/INSTALL.md b/docs/INSTALL.md
index 2b45169ff..3e3208b53 100644
--- a/docs/INSTALL.md
+++ b/docs/INSTALL.md
@@ -1,4 +1,4 @@
-# [**fheroes2**](README.md) installation guide
+# [fheroes2](README.md) Installation Guide
## Requirements
@@ -33,58 +33,40 @@ Precompiled binaries of the release version are currently available for the foll
Alternatively, you can download the precompiled binaries of the latest commit (snapshot) [**here**](#snapshots-latest-builds).
-
- 
-
+
+
-
+
+
+
+
+ 
+ 
+
+
+
+
-
-
-
+
+
+
+ {{ content }}
+
+
+
+
+
diff --git a/docs/_sass/_dark-theme.scss b/docs/_sass/_dark-theme.scss
new file mode 100644
index 000000000..31666d6d6
--- /dev/null
+++ b/docs/_sass/_dark-theme.scss
@@ -0,0 +1,19 @@
+$dark: (
+ primary-color: #c0c0c0,
+ header-color: #e4c814,
+ secondary-color: #480a0a,
+ page-color: #989898,
+ text-color: #e0e0e0,
+ background-color: #383838,
+ border-color: #480a0a,
+ highlight-color: #800080,
+ code-background-color: #2a2a2a,
+ inverse-text-color: #2c1810,
+ inverse-background-color: #f5deb3,
+ inverse-border-color: #8b4513,
+ inverse-primary-color: #8b4513,
+ border-radius: 5px,
+ body-text-shadow: 2px 2px 2px #383838,
+ header-text-shadow: -2px 3px 1px darken(#a42da4, 10%),
+ table-text-color: #e0e0e0,
+);
diff --git a/docs/_sass/_layout.scss b/docs/_sass/_layout.scss
new file mode 100644
index 000000000..7b712f4cd
--- /dev/null
+++ b/docs/_sass/_layout.scss
@@ -0,0 +1,644 @@
+$mobile-width: 768px;
+$tablet-width: 1024px;
+$container-width: 1200px;
+$hero-header-font: "Jacquard 24";
+$header-font: "Lancelot";
+$body-font: "Asul";
+
+// Mixin for responsive table styles
+@mixin responsive-table($theme-map) {
+ overflow-x: auto;
+ -webkit-overflow-scrolling: touch;
+ margin: 1em auto;
+
+ &.stack {
+ thead {
+ display: none;
+ }
+
+ tr {
+ border-bottom: 0.125em solid rgba(map-get($theme-map, primary-color), 0.2);
+ margin-bottom: 1em;
+
+ &:last-child {
+ border-bottom: none;
+ margin-bottom: 0;
+ }
+ }
+
+ td {
+ text-align: right;
+ padding: 0.6em 1em;
+ border-bottom: 0.0625em solid
+ rgba(map-get($theme-map, primary-color), 0.1);
+
+ &:before {
+ content: attr(data-label);
+ float: left;
+ font-family: $header-font, cursive;
+ color: map-get($theme-map, primary-color);
+ font-weight: 400;
+ }
+
+ &:last-child {
+ border-bottom: none;
+ }
+ }
+ }
+}
+
+// Mixin for responsive image showcase styles
+@mixin responsive-image-showcase {
+ flex-direction: column;
+
+ .row {
+ flex-direction: column;
+ gap: 1em;
+ }
+
+ img.half-image {
+ width: 100%;
+ margin-bottom: 0;
+ }
+}
+
+@mixin responsive-code-highlight($theme-map) {
+ .highlighter-rouge {
+ padding: 0;
+ background: none;
+ border: none;
+
+ .highlight {
+ flex-direction: column;
+ align-items: stretch;
+ padding: 0;
+
+ pre.highlight {
+ margin: 0;
+ -webkit-overflow-scrolling: touch;
+ padding: 0.5em 0.5em 0.5em 1em;
+ scrollbar-width: none;
+ border-radius: map-get($theme-map, border-radius);
+
+ code {
+ font-size: 1em;
+ padding: 0;
+ }
+ }
+
+ .copy-btn {
+ flex-grow: 1;
+ }
+ }
+ }
+ code.highlighter-rouge {
+ font-size: 0.6em;
+ word-wrap: break-word;
+ }
+}
+
+@mixin themable($theme-name, $theme-map) {
+ [data-theme="#{$theme-name}"] {
+ // Global styles
+ body {
+ background: map-get($theme-map, background-color);
+ color: map-get($theme-map, text-color);
+ font-family: $body-font, sans-serif;
+ font-weight: 400;
+ font-style: normal;
+ line-height: 1.4;
+ margin: 0;
+ padding: 0;
+ }
+
+ a {
+ color: map-get($theme-map, highlight-color);
+ text-decoration: none;
+
+ &:hover {
+ color: lighten(map-get($theme-map, highlight-color), 5%);
+ }
+ }
+
+ h1,
+ h2,
+ h3,
+ h4,
+ h5,
+ h6 {
+ color: map-get($theme-map, header-color);
+ font-weight: 400;
+ font-style: normal;
+ position: relative;
+ margin: 0;
+ line-height: 1.2em;
+ text-shadow: map-get($theme-map, header-text-shadow);
+ &:hover {
+ color: lighten(map-get($theme-map, header-color), 10%);
+ }
+
+ .heading-link {
+ display: block;
+ position: relative;
+ -webkit-tap-highlight-color: transparent;
+
+ &:hover {
+ color: map-get($theme-map, header-color);
+
+ .heading-anchor {
+ opacity: 1;
+ }
+ }
+ }
+ }
+
+ h1 a,
+ h2 a,
+ h3 a,
+ h4 a,
+ h5 a,
+ h6 a {
+ text-shadow: map-get($theme-map, header-text-shadow);
+ }
+
+ h1 {
+ font-family: $hero-header-font, cursive;
+ margin: 0.3em 0;
+ font-size: 3em;
+ padding: 0;
+ border: none;
+ position: relative;
+
+ a {
+ color: map-get($theme-map, header-color);
+ position: relative;
+ display: inline-block;
+
+ &:hover {
+ color: lighten(map-get($theme-map, header-color), 10%);
+ }
+ }
+ }
+
+ h2,
+ h3,
+ h4,
+ h5,
+ h6 {
+ font-family: $header-font, serif;
+ }
+
+ h2 {
+ font-size: 2em;
+ }
+
+ h3 {
+ font-size: 1.5em;
+ }
+
+ h4 {
+ font-size: 1.2em;
+ }
+
+ p {
+ margin-bottom: 1.2em;
+ }
+
+ ol,
+ p,
+ table,
+ ul {
+ text-shadow: map-get($theme-map, body-text-shadow);
+ }
+ a {
+ text-shadow: none;
+ }
+
+ code {
+ font-family: monospace;
+ background: none;
+ padding: 0;
+ }
+
+ pre {
+ margin: 0;
+ padding: 0;
+ background: none;
+ }
+
+ // Header styles
+ header {
+ text-align: center;
+ margin-bottom: 0;
+ border-bottom: 0.125em solid map-get($theme-map, secondary-color);
+ // text-shadow: 0.125em 0.125em 0.25em $primary-color;
+
+ h1 {
+ font-size: 4em;
+ margin: 0;
+ padding: 0;
+ text-shadow: none;
+ border: none;
+ transform-style: preserve-3d;
+ transform: perspective(1000px) rotateX(3deg);
+ transition: transform 0.3s ease;
+
+ &:hover {
+ transform: perspective(1000px) rotateX(0deg) translateY(-3px);
+ }
+
+ a {
+ color: map-get($theme-map, header-color);
+ position: relative;
+ display: inline-block;
+ transform-style: preserve-3d;
+
+ &:before {
+ content: attr(data-text);
+ position: absolute;
+ left: 0;
+ top: 0;
+ color: rgba(255, 255, 255, 0.3);
+ transform: translateZ(-20px);
+ filter: blur(2px);
+ }
+
+ &:after {
+ content: attr(data-text);
+ position: absolute;
+ left: 0;
+ top: 0;
+ color: rgba(0, 0, 0, 0.3);
+ transform: translateZ(-10px);
+ filter: blur(1px);
+ }
+
+ &:hover {
+ color: lighten(map-get($theme-map, header-color), 10%);
+ }
+ }
+ }
+
+ h2 {
+ font-family: $body-font, sans-serif;
+ font-size: 1.5em;
+ margin: 0.625em 0;
+ border: none;
+ }
+ }
+
+ ul {
+ padding-left: 1em;
+ }
+
+ ol {
+ padding-left: 1em;
+ margin-top: revert;
+ margin-bottom: revert;
+ }
+
+ li {
+ margin-bottom: 0.5em;
+ }
+
+ // Footer styles
+ footer {
+ text-align: center;
+ margin-top: 40px;
+ padding: 20px;
+ background: rgba(map-get($theme-map, background-color), 0.3);
+ border-radius: map-get($theme-map, border-radius);
+
+ p {
+ margin: 0;
+ }
+ }
+
+ .shell {
+ max-width: $container-width;
+ padding: 0 1.25em 1.25em;
+ background: rgba(map-get($theme-map, page-color), 0.9);
+ box-shadow: 0 0 1.25em map-get($theme-map, border-color);
+ font-size: 1.6em;
+ }
+
+ .image-showcase {
+ display: flex;
+ justify-content: space-between;
+ flex-wrap: wrap;
+ gap: 1em;
+ margin: 1em 0;
+
+ .row {
+ display: flex;
+ justify-content: space-between;
+ width: 100%;
+ gap: 1em;
+ }
+
+ img.full-image {
+ width: 100%;
+ height: auto;
+ }
+
+ img.half-image {
+ width: calc(50% - 0.5em);
+ height: auto;
+ }
+ }
+
+ // Button styles
+ .btn {
+ display: inline-block;
+ padding: 0.5em;
+ font-family: $header-font, cursive;
+ font-size: 1.1em;
+ text-align: center;
+ text-decoration: none;
+ border-radius: map-get($theme-map, border-radius);
+ cursor: pointer;
+ transition: all 0.3s ease;
+ border: 0.125em solid transparent;
+ box-shadow: 0 0.25em 0.5em rgba(0, 0, 0, 0.2);
+ position: relative;
+ overflow: hidden;
+
+ &:hover {
+ transform: translateY(-2px);
+ box-shadow: 0 0.5em 1em rgba(0, 0, 0, 0.3);
+ }
+
+ &:active {
+ transform: translateY(1px);
+ box-shadow: 0 0.125em 0.25em rgba(0, 0, 0, 0.2);
+ }
+
+ // Primary button
+ &.btn-primary {
+ background: map-get($theme-map, primary-color);
+ color: map-get($theme-map, background-color);
+ border-color: map-get($theme-map, primary-color);
+
+ &:hover {
+ background: darken(map-get($theme-map, primary-color), 10%);
+ }
+ }
+
+ // Secondary button
+ &.btn-secondary {
+ background: map-get($theme-map, secondary-color);
+ color: map-get($theme-map, primary-color);
+ border-color: map-get($theme-map, secondary-color);
+
+ &:hover {
+ background: darken(map-get($theme-map, secondary-color), 10%);
+ }
+ }
+
+ // Outline button
+ &.btn-outline {
+ background: transparent;
+ color: map-get($theme-map, primary-color);
+ border-color: map-get($theme-map, primary-color);
+
+ &:hover {
+ background: rgba(map-get($theme-map, primary-color), 0.1);
+ }
+ }
+
+ // Disabled state
+ &:disabled,
+ &.disabled {
+ opacity: 0.6;
+ cursor: not-allowed;
+ pointer-events: none;
+ }
+ }
+
+ .theme-toggle-container {
+ display: flex;
+ font-size: 0.5em;
+ justify-content: end;
+ margin: 1.25em 0em;
+
+ .btn {
+ &.btn-primary {
+ color: map-get($theme-map, inverse-text-color);
+ background: map-get($theme-map, inverse-background-color);
+ border-color: map-get($theme-map, inverse-border-color);
+
+ &:hover {
+ background: map-get($theme-map, inverse-primary-color);
+ }
+ }
+ }
+ }
+
+ @media screen and (min-width: $tablet-width) {
+ .shell {
+ border: 0.125em solid map-get($theme-map, border-color);
+ border-radius: map-get($theme-map, border-radius);
+ margin: 1.25em;
+ }
+
+ #main_content {
+ padding: 1.25em;
+ }
+ }
+
+ @media screen and (min-width: $container-width) {
+ .shell {
+ margin: 1.25em auto;
+ }
+ }
+
+ .highlighter-rouge {
+ background: rgba(map-get($theme-map, primary-color), 0.05);
+ padding: 0;
+ border-radius: map-get($theme-map, border-radius);
+ position: relative;
+ border: 0.0625em solid rgba(map-get($theme-map, primary-color), 0.1);
+ margin-bottom: 1.2em;
+
+ .highlight {
+ padding: 0.7em;
+ scrollbar-width: none;
+ -webkit-overflow-scrolling: touch;
+ background: none;
+ position: relative;
+ overflow-x: auto;
+ display: flex;
+ justify-content: space-between;
+ gap: 1em;
+ align-items: center;
+
+ pre.highlight {
+ background: rgba(map-get($theme-map, code-background-color), 0.5);
+ border-radius: map-get($theme-map, border-radius);
+ flex-grow: 1;
+
+ code {
+ display: block;
+ white-space: pre;
+ padding: 0;
+ }
+ }
+ }
+ }
+
+ code.highlighter-rouge {
+ padding: 0.5em;
+ font-size: 0.8em;
+ background: rgba(map-get($theme-map, code-background-color), 0.5);
+ }
+
+ // Heading anchor links
+ .heading-anchor {
+ opacity: 0;
+ font-size: min(1em, 24px);
+ margin-left: 0.5em;
+ text-decoration: none;
+ vertical-align: middle;
+ transition: all 0.3s ease;
+ color: lighten(map-get($theme-map, header-color), 10%);
+ display: inline-block;
+ cursor: copy;
+
+ &:hover {
+ opacity: 1 !important;
+ transform: scale(1.1);
+ }
+ }
+
+ h1,
+ h2,
+ h3,
+ h4,
+ h5,
+ h6 {
+ &:hover .heading-anchor {
+ opacity: 1;
+ }
+ }
+
+ table {
+ width: 100%;
+ border-collapse: separate;
+ border-spacing: 0;
+ margin: 1.5em 0;
+ background: darken(map-get($theme-map, primary-color), 20%);
+ border: 0.1em solid rgba(map-get($theme-map, secondary-color), 0.6);
+ border-radius: map-get($theme-map, border-radius);
+ overflow: hidden;
+ box-shadow: 0 0.125em 0.25em
+ rgba(map-get($theme-map, secondary-color), 0.1);
+
+ th {
+ background: rgba(map-get($theme-map, background-color), 0.6);
+ color: map-get($theme-map, primary-color);
+ font-family: $header-font, cursive;
+ font-weight: 400;
+ padding: 1em;
+ text-align: left;
+ border-bottom: 0.125em solid
+ rgba(map-get($theme-map, secondary-color), 0.3);
+ font-size: 1.1em;
+ white-space: nowrap;
+ position: sticky;
+ top: 0;
+ z-index: 1;
+ backdrop-filter: blur(4px);
+ }
+
+ td {
+ padding: 0.8em 1em;
+ border-bottom: 0.0625em solid
+ rgba(map-get($theme-map, primary-color), 0.1);
+ vertical-align: middle;
+ line-height: 1.4;
+ }
+
+ tr {
+ color: map-get($theme-map, table-text-color);
+ }
+ tr:last-child td {
+ border-bottom: none;
+ }
+
+ tr:hover {
+ background: rgba(map-get($theme-map, secondary-color), 0.05);
+ }
+ }
+
+ // Portrait mobile styles
+ @media screen and (max-width: $mobile-width) and (orientation: portrait) {
+ @include responsive-code-highlight($theme-map);
+
+ .heading-anchor {
+ display: none !important;
+ }
+
+ .shell {
+ padding: 0.625em;
+ font-size: 2.5em;
+ }
+
+ img.game-screenshot {
+ width: 100%;
+ height: auto;
+ }
+
+ table {
+ @include responsive-table($theme-map);
+ display: block;
+
+ &.stack {
+ tr {
+ display: block;
+ }
+
+ td {
+ display: block;
+ }
+ }
+ }
+
+ .image-showcase {
+ @include responsive-image-showcase;
+ }
+ }
+
+ // Landscape mobile styles
+ @media screen and (max-width: $tablet-width) and (orientation: landscape) {
+ body {
+ font-size: 0.6em;
+ }
+ @include responsive-code-highlight($theme-map);
+
+ .heading-anchor {
+ display: none !important;
+ }
+
+ .shell {
+ padding: 0.625em;
+ font-size: 1.8em;
+ }
+
+ img.game-screenshot {
+ width: 100%;
+ height: auto;
+ }
+
+ table {
+ @include responsive-table($theme-map);
+ }
+
+ .image-showcase {
+ @include responsive-image-showcase;
+ }
+ }
+ }
+}
+
+@include themable(light, $light);
+@include themable(dark, $dark);
diff --git a/docs/_sass/_light-theme.scss b/docs/_sass/_light-theme.scss
new file mode 100644
index 000000000..4ca34fbef
--- /dev/null
+++ b/docs/_sass/_light-theme.scss
@@ -0,0 +1,19 @@
+$light: (
+ primary-color: #8b4513,
+ header-color: #8b4513,
+ secondary-color: #daa520,
+ page-color: #fff,
+ text-color: #2c1810,
+ background-color: #f5deb3,
+ border-color: #8b4513,
+ highlight-color: #cd853f,
+ code-background-color: #e6e1da,
+ inverse-text-color: #e0e0e0,
+ inverse-background-color: #383838,
+ inverse-border-color: #c0c0c0,
+ inverse-primary-color: #c0c0c0,
+ border-radius: 10px,
+ body-text-shadow: none,
+ header-text-shadow: -1px 2px 1px #cd853f,
+ table-text-color: #fff,
+);
diff --git a/docs/assets/css/style.scss b/docs/assets/css/style.scss
new file mode 100644
index 000000000..bbba2c0db
--- /dev/null
+++ b/docs/assets/css/style.scss
@@ -0,0 +1,6 @@
+---
+---
+
+@import "dark-theme";
+@import "light-theme";
+@import "layout";
diff --git a/docs/assets/js/accessibility.js b/docs/assets/js/accessibility.js
new file mode 100644
index 000000000..a819a15de
--- /dev/null
+++ b/docs/assets/js/accessibility.js
@@ -0,0 +1,178 @@
+/***************************************************************************
+ * fheroes2: https://github.com/ihhub/fheroes2 *
+ * Copyright (C) 2025 *
+ * *
+ * This program is free software; you can redistribute it and/or modify *
+ * it under the terms of the GNU General Public License as published by *
+ * the Free Software Foundation; either version 2 of the License, or *
+ * (at your option) any later version. *
+ * *
+ * This program is distributed in the hope that it will be useful, *
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of *
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the *
+ * GNU General Public License for more details. *
+ * *
+ * You should have received a copy of the GNU General Public License *
+ * along with this program; if not, write to the *
+ * Free Software Foundation, Inc., *
+ * 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. *
+ ***************************************************************************/
+
+// Utility class for handling common accessibility features
+class AccessibilityManager
+{
+ constructor()
+ {
+ this.liveRegion = this.createLiveRegion();
+ }
+
+ // Creates a live region for screen reader announcements
+ // The live region is a div element that is used to announce messages to
+ // screen readers.
+ // Returns: The live region element
+ createLiveRegion()
+ {
+ const liveRegion = document.createElement( 'div' );
+ liveRegion.setAttribute( 'aria-live', 'assertive' );
+ liveRegion.setAttribute( 'aria-atomic', 'true' );
+ // This doesn't work as a CSS property, so we need to set it manually
+ liveRegion.style.cssText
+ = 'position: absolute; width: 1px; height: 1px; padding: 0; margin: -1px; overflow: hidden; clip: rect(0, 0, 0, 0); white-space: nowrap; border: 0;';
+ document.body.appendChild( liveRegion );
+ return liveRegion;
+ }
+
+ // Announces a message to screen readers
+ // Parameters:
+ // message - The message to announce
+ announce( message )
+ {
+ // Clear the live region first
+ this.liveRegion.textContent = '';
+
+ // Force a reflow to ensure the announcement is triggered if the user
+ // triggers multiple times in a row.
+ void this.liveRegion.offsetHeight;
+
+ // Set the new message
+ this.liveRegion.textContent = message;
+
+ // Force another reflow to ensure the announcement is triggered
+ void this.liveRegion.offsetHeight;
+ }
+
+ // Creates an accessible element (button or span)
+ // Parameters:
+ // options - An object containing the following properties:
+ // text - The element text
+ // ariaLabel - The ARIA label
+ // className - Additional CSS classes
+ // elementType - The element type ('button' or 'span')
+ // Returns: The accessible element
+ createAccessibleElement( options )
+ {
+ const { text, ariaLabel, className = '', elementType = 'button' } = options;
+
+ const element = document.createElement( elementType );
+ element.textContent = text;
+ element.setAttribute( 'aria-label', ariaLabel );
+ element.setAttribute( 'role', 'button' );
+ element.setAttribute( 'tabindex', '0' );
+ if ( className ) {
+ element.className = className;
+ }
+ return element;
+ }
+
+ // Creates an accessible button element
+ // Parameters:
+ // options - An object containing the following properties:
+ // text - The button text
+ // ariaLabel - The ARIA label
+ // className - Additional CSS classes
+ // Returns: The button element
+ createAccessibleButton( options )
+ {
+ return this.createAccessibleElement( {...options, elementType : 'button' } );
+ }
+
+ // Creates an accessible span element
+ // Parameters:
+ // options - An object containing the following properties:
+ // text - The span text
+ // ariaLabel - The ARIA label
+ // className - Additional CSS classes
+ // Returns: The span element
+ createAccessibleSpan( options )
+ {
+ return this.createAccessibleElement( {...options, elementType : 'span' } );
+ }
+
+ // Updates element state with visual and screen reader feedback
+ // Parameters:
+ // options - An object containing the following properties:
+ // element - The element to update
+ // success - Whether the action was successful
+ // successMessage - Message for screen reader on success
+ // errorMessage - Message for screen reader on error
+ // successText - Text to show on element for success
+ // errorText - Text to show on element for error
+ // defaultText - Default element text
+ // resetDelay - Delay before resetting element (ms)
+ // isHtml - Whether the text contains HTML
+ updateElementState( options )
+ {
+ const { element, success, successMessage, errorMessage, successText, errorText, defaultText, resetDelay = 2000, isHtml = false } = options;
+
+ // Update visual state first
+ if ( success ) {
+ if ( isHtml ) {
+ element.innerHTML = successText;
+ }
+ else {
+ element.textContent = successText;
+ }
+ element.classList.add( 'success' );
+ }
+ else {
+ if ( isHtml ) {
+ element.innerHTML = errorText;
+ }
+ else {
+ element.textContent = errorText;
+ }
+ element.classList.add( 'error' );
+ }
+
+ // Announce to screen reader after a short delay to ensure visual update is complete
+ setTimeout( () => { this.announce( success ? successMessage : errorMessage ); }, 50 );
+
+ // Reset element after delay
+ setTimeout( () => {
+ if ( isHtml ) {
+ element.innerHTML = defaultText;
+ }
+ else {
+ element.textContent = defaultText;
+ }
+ element.classList.remove( 'success', 'error' );
+ }, resetDelay );
+ }
+
+ // Sets up keyboard event handling for an element
+ // Parameters:
+ // element - The element to add keyboard events to
+ // handler - The click handler function
+ setupKeyboardEvents( element, handler )
+ {
+ element.addEventListener( 'keydown', ( event ) => {
+ if ( event.key === 'Enter' || event.key === ' ' ) {
+ event.preventDefault();
+ handler( event );
+ }
+ } );
+ }
+}
+
+// Export the accessibility manager
+window.AccessibilityManager = AccessibilityManager;
diff --git a/docs/assets/js/code-copy.js b/docs/assets/js/code-copy.js
new file mode 100644
index 000000000..33547a57a
--- /dev/null
+++ b/docs/assets/js/code-copy.js
@@ -0,0 +1,108 @@
+/***************************************************************************
+ * fheroes2: https://github.com/ihhub/fheroes2 *
+ * Copyright (C) 2025 *
+ * *
+ * This program is free software; you can redistribute it and/or modify *
+ * it under the terms of the GNU General Public License as published by *
+ * the Free Software Foundation; either version 2 of the License, or *
+ * (at your option) any later version. *
+ * *
+ * This program is distributed in the hope that it will be useful, *
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of *
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the *
+ * GNU General Public License for more details. *
+ * *
+ * You should have received a copy of the GNU General Public License *
+ * along with this program; if not, write to the *
+ * Free Software Foundation, Inc., *
+ * 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. *
+ ***************************************************************************/
+
+// Class to handle code copy functionality
+class CodeCopyManager
+{
+ constructor()
+ {
+ this.accessibility = new AccessibilityManager();
+
+ // Apply to all code blocks
+ document.querySelectorAll( "div.highlight" ).forEach( block => this.initializeCodeBlock( block ) );
+ }
+
+ // Creates a copy button using the template
+ // Returns: The button element
+ createCopyButton()
+ {
+ return this.accessibility.createAccessibleButton( { text : 'Copy', ariaLabel : 'Copy code to clipboard', className : 'btn btn-primary copy-btn' } );
+ }
+
+ // Updates the button appearance and announces success to screen readers
+ // Parameters:
+ // button - The button element
+ // success - Whether the copy was successful
+ // code - The code content that was copied
+ updateButtonState( button, success, code )
+ {
+ // Truncate the code if it's too long
+ const truncatedCode = code.length > 50 ? `${code.substring( 0, 50 )}...` : code;
+
+ this.accessibility.updateElementState( {
+ element : button,
+ success : success,
+ successMessage : `Code copied to clipboard: ${truncatedCode}`,
+ errorMessage : 'Failed to copy code to clipboard',
+ successText : 'Copied!',
+ errorText : 'Failed to copy',
+ defaultText : 'Copy',
+ resetDelay : 2000
+ } );
+ }
+
+ // Handles the copy functionality for a code block
+ // Parameters:
+ // block - The code block element
+ // button - The copy button
+ handleCopyCode( block, button )
+ {
+ try {
+ const code = block.querySelector( "pre" ).innerText;
+ navigator.clipboard.writeText( code ).then( () => { this.updateButtonState( button, true, code ); } ).catch( err => {
+ console.error( "Failed to copy code:", err );
+ this.updateButtonState( button, false, code );
+ } );
+ }
+ catch ( err ) {
+ console.error( "Failed to copy code:", err );
+ this.updateButtonState( button, false, '' );
+ }
+ }
+
+ // Sets up event listeners for a copy button
+ // Parameters:
+ // button - The copy button
+ // block - The code block element
+ setupEventListeners( button, block )
+ {
+ // Click event handler
+ button.addEventListener( "click", () => this.handleCopyCode( block, button ) );
+
+ // Keyboard event handler
+ this.accessibility.setupKeyboardEvents( button, () => this.handleCopyCode( block, button ) );
+ }
+
+ // Initializes a code block with a copy button
+ // Parameters:
+ // block - The code block element
+ initializeCodeBlock( block )
+ {
+ const button = this.createCopyButton();
+ block.appendChild( button );
+ this.setupEventListeners( button, block );
+ }
+}
+
+// Initialize when the DOM is fully loaded
+document.addEventListener( "DOMContentLoaded", () => {
+ // Initialize the code copy manager
+ new CodeCopyManager();
+} );
diff --git a/docs/assets/js/heading-copy.js b/docs/assets/js/heading-copy.js
new file mode 100644
index 000000000..72b2d47a5
--- /dev/null
+++ b/docs/assets/js/heading-copy.js
@@ -0,0 +1,150 @@
+/***************************************************************************
+ * fheroes2: https://github.com/ihhub/fheroes2 *
+ * Copyright (C) 2025 *
+ * *
+ * This program is free software; you can redistribute it and/or modify *
+ * it under the terms of the GNU General Public License as published by *
+ * the Free Software Foundation; either version 2 of the License, or *
+ * (at your option) any later version. *
+ * *
+ * This program is distributed in the hope that it will be useful, *
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of *
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the *
+ * GNU General Public License for more details. *
+ * *
+ * You should have received a copy of the GNU General Public License *
+ * along with this program; if not, write to the *
+ * Free Software Foundation, Inc., *
+ * 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. *
+ ***************************************************************************/
+
+// Constants
+const LINK_ICON = '🔗';
+const COPIED_ICON = ' - Copied';
+const ERROR_ICON = '❌';
+const RESET_DELAY = 2000;
+const HEADING_SELECTORS = 'h2, h3, h4, h5, h6';
+
+// Class to handle heading copy functionality
+class HeadingCopyManager
+{
+ constructor( contentElement )
+ {
+ this.content = contentElement;
+ this.accessibility = new AccessibilityManager();
+
+ // Apply to all headings
+ this.content.querySelectorAll( HEADING_SELECTORS ).forEach( heading => this.createHeadingLink( heading ) );
+ }
+
+ // Creates a unique ID for a heading based on its text content
+ // Parameters:
+ // text - The heading text
+ // Returns: A unique ID
+ generateHeadingId( text )
+ {
+ return text.toLowerCase().replace( /[^a-z0-9]+/g, '-' );
+ }
+
+ // Creates a link icon element with proper accessibility attributes
+ // Returns: The icon element
+ createIconElement()
+ {
+ const icon = this.accessibility.createAccessibleSpan( { text : LINK_ICON, ariaLabel : 'Copy link to heading', className : 'heading-anchor' } );
+ return icon;
+ }
+
+ // Updates the icon appearance based on the copy result
+ // Parameters:
+ // icon - The icon element
+ // success - Whether the copy was successful
+ // headingText - The text of the heading
+ updateIconState( icon, success, headingText )
+ {
+ this.accessibility.updateElementState( {
+ element : icon,
+ success : success,
+ successMessage : `Link to ${headingText} copied to clipboard`,
+ errorMessage : `Failed to copy link to ${headingText}`,
+ successText : COPIED_ICON,
+ errorText : ERROR_ICON,
+ defaultText : LINK_ICON,
+ resetDelay : RESET_DELAY,
+ isHtml : true // Use innerHTML for the heading icon
+ } );
+ }
+
+ // Handles the copy functionality for a heading
+ // Parameters:
+ // e - The event object
+ // heading - The heading element
+ // icon - The icon element
+ handleCopy( e, heading, icon )
+ {
+ e.preventDefault();
+ e.stopPropagation();
+
+ const url = new URL( window.location.href );
+ url.hash = heading.id;
+
+ try {
+ navigator.clipboard.writeText( url.toString() )
+ .then( () => {
+ this.updateIconState( icon, true, heading.textContent );
+
+ // Update URL without scrolling
+ history.pushState( null, null, `#${heading.id}` );
+ } )
+ .catch( err => {
+ console.error( 'Failed to copy:', err );
+ this.updateIconState( icon, false, heading.textContent );
+ } );
+ }
+ catch ( err ) {
+ console.error( 'Failed to copy:', err );
+ this.updateIconState( icon, false, heading.textContent );
+ }
+ }
+
+ // Sets up event listeners for a heading icon
+ // Parameters:
+ // icon - The icon element
+ // heading - The heading element
+ setupEventListeners( icon, heading )
+ {
+ // Add click event handler
+ icon.addEventListener( 'click', ( e ) => this.handleCopy( e, heading, icon ) );
+
+ // Add keyboard event handler
+ this.accessibility.setupKeyboardEvents( icon, ( e ) => this.handleCopy( e, heading, icon ) );
+ }
+
+ // Creates a heading link with proper accessibility attributes
+ // Parameters:
+ // heading - The heading element
+ createHeadingLink( heading )
+ {
+ // Generate ID if needed
+ if ( !heading.id ) {
+ heading.id = this.generateHeadingId( heading.textContent );
+ }
+
+ // Create icon element
+ const icon = this.createIconElement();
+
+ // Add icon to the heading
+ heading.appendChild( icon );
+
+ // Set up event listeners
+ this.setupEventListeners( icon, heading );
+ }
+}
+
+// Initialize when the DOM is fully loaded
+document.addEventListener( 'DOMContentLoaded', () => {
+ const content = document.querySelector( '#main_content' );
+ if ( content ) {
+ // Initialize the heading copy manager
+ new HeadingCopyManager( content );
+ }
+} );
diff --git a/docs/assets/js/templates.js b/docs/assets/js/templates.js
new file mode 100644
index 000000000..e494beffe
--- /dev/null
+++ b/docs/assets/js/templates.js
@@ -0,0 +1,49 @@
+/***************************************************************************
+ * fheroes2: https://github.com/ihhub/fheroes2 *
+ * Copyright (C) 2025 *
+ * *
+ * This program is free software; you can redistribute it and/or modify *
+ * it under the terms of the GNU General Public License as published by *
+ * the Free Software Foundation; either version 2 of the License, or *
+ * (at your option) any later version. *
+ * *
+ * This program is distributed in the hope that it will be useful, *
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of *
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the *
+ * GNU General Public License for more details. *
+ * *
+ * You should have received a copy of the GNU General Public License *
+ * along with this program; if not, write to the *
+ * Free Software Foundation, Inc., *
+ * 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. *
+ ***************************************************************************/
+
+/**
+ * HTML templates for the heading-copy and code-copy functionality
+ */
+
+// Template for the live region
+const liveRegionTemplate = `
+
+`;
+
+// Template for the heading anchor icon
+const headingAnchorTemplate = `
+🔗
+`;
+
+// Template for the code copy button
+const codeCopyButtonTemplate = `
+
+`;
+
+// Export the templates
+window.HeadingCopyTemplates = {
+ liveRegionTemplate,
+ headingAnchorTemplate
+};
+
+window.CodeCopyTemplates = {
+ liveRegionTemplate,
+ codeCopyButtonTemplate
+};
diff --git a/docs/assets/js/theme-toggle.js b/docs/assets/js/theme-toggle.js
new file mode 100644
index 000000000..32260ce58
--- /dev/null
+++ b/docs/assets/js/theme-toggle.js
@@ -0,0 +1,121 @@
+/***************************************************************************
+ * fheroes2: https://github.com/ihhub/fheroes2 *
+ * Copyright (C) 2025 *
+ * *
+ * This program is free software; you can redistribute it and/or modify *
+ * it under the terms of the GNU General Public License as published by *
+ * the Free Software Foundation; either version 2 of the License, or *
+ * (at your option) any later version. *
+ * *
+ * This program is distributed in the hope that it will be useful, *
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of *
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the *
+ * GNU General Public License for more details. *
+ * *
+ * You should have received a copy of the GNU General Public License *
+ * along with this program; if not, write to the *
+ * Free Software Foundation, Inc., *
+ * 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. *
+ ***************************************************************************/
+
+// Theme toggle functionality
+class ThemeManager
+{
+ constructor()
+ {
+ this.themeToggle = document.getElementById( "theme-toggle" );
+ this.themeKey = "theme";
+ this.darkTheme = "dark";
+ this.lightTheme = "light";
+ this.accessibility = window.AccessibilityManager ? new window.AccessibilityManager() : null;
+
+ this.init();
+ }
+
+ init()
+ {
+ this.applySavedTheme();
+ this.setupEventListeners();
+ this.setupAccessibility();
+ }
+
+ setTheme( theme, saveToStorage = true )
+ {
+ document.documentElement.setAttribute( "data-theme", theme );
+ document.body.setAttribute( "data-theme", theme );
+
+ // Only save to localStorage if explicitly requested
+ if ( saveToStorage ) {
+ localStorage.setItem( this.themeKey, theme );
+ }
+
+ // Update button text and ARIA attributes
+ if ( this.themeToggle ) {
+ this.themeToggle.textContent = theme === this.darkTheme ? "☀️ Light Mode" : "🌙 Dark Mode";
+
+ // Update ARIA attributes
+ this.themeToggle.setAttribute( "aria-label", `Switch to ${theme === this.darkTheme ? this.lightTheme : this.darkTheme} mode` );
+ this.themeToggle.setAttribute( "aria-pressed", theme === this.darkTheme ? "true" : "false" );
+
+ // Announce theme change if accessibility manager is available
+ if ( this.accessibility ) {
+ this.accessibility.announce( `${theme === this.darkTheme ? 'Dark' : 'Light'} mode activated` );
+ }
+ }
+ }
+
+ applySavedTheme()
+ {
+ const savedTheme = localStorage.getItem( this.themeKey );
+
+ if ( savedTheme ) {
+ this.setTheme( savedTheme );
+ }
+ else {
+ // Check system preference but don't save it to localStorage
+ const prefersDark = window.matchMedia( "(prefers-color-scheme: dark)" ).matches;
+ this.setTheme( prefersDark ? this.darkTheme : this.lightTheme, false );
+ }
+ }
+
+ setupEventListeners()
+ {
+ // Add event listener to the toggle button
+ if ( this.themeToggle ) {
+ this.themeToggle.addEventListener( "click", () => {
+ const currentTheme = document.documentElement.getAttribute( "data-theme" );
+ this.setTheme( currentTheme === this.darkTheme ? this.lightTheme : this.darkTheme );
+ } );
+ }
+
+ // Listen for system theme changes
+ window.matchMedia( "(prefers-color-scheme: dark)" ).addEventListener( "change", ( e ) => {
+ // Only apply system preference if user hasn't manually set a preference
+ if ( !localStorage.getItem( this.themeKey ) ) {
+ this.setTheme( e.matches ? this.darkTheme : this.lightTheme, false );
+ }
+ } );
+ }
+
+ setupAccessibility()
+ {
+ if ( this.themeToggle ) {
+ // Set initial ARIA attributes
+ const currentTheme = document.documentElement.getAttribute( "data-theme" );
+ this.themeToggle.setAttribute( "aria-label", `Switch to ${currentTheme === this.darkTheme ? this.lightTheme : this.darkTheme} mode` );
+ this.themeToggle.setAttribute( "aria-pressed", currentTheme === this.darkTheme ? "true" : "false" );
+
+ // Add keyboard event handling
+ this.themeToggle.addEventListener( "keydown", ( event ) => {
+ if ( event.key === "Enter" || event.key === " " ) {
+ event.preventDefault();
+ const currentTheme = document.documentElement.getAttribute( "data-theme" );
+ this.setTheme( currentTheme === this.darkTheme ? this.lightTheme : this.darkTheme );
+ }
+ } );
+ }
+ }
+}
+
+// Initialize the theme manager when the DOM is loaded
+document.addEventListener( "DOMContentLoaded", () => { new ThemeManager(); } );
diff --git a/docs/images/favicon.ico b/docs/images/favicon.ico
new file mode 100644
index 0000000000000000000000000000000000000000..0e668af38c3fe4c967a1495f8f62af449da7835f
GIT binary patch
literal 4286
zcmb_f30RX?x;`W(0TReU_JoiHvIjx{*+DRZY_fw0qAWo~aNi4xFrp|_MC^c7YTc@}
zSVgU4tHru>YPEKHJAGQ)+H319owl~qJH0dd+)m$n5~efud3v9j+j~!*_s{eH|M}1R
zeeXHn_nkwCAN^^y#Cs)21%yZmA!Z8th)kpKKKC{HPQ;zW
+
+
+