Website Local Documentation Development Guide

This guide explains how to set up and run the documentation site locally for development purposes.

Prerequisites

If you're on macOS, you can install the required development tools using the provided Brewfile:

# Install the development tools using brew bundle
brew bundle --file=script/macos/Brewfile.dev_tools

This will install the necessary tools to assist with formatting and for linting source files.

Clone your fork of the repository:

git clone https://github.com/<YOUR_USERNAME>/fheroes2.git
cd fheroes2/docs

Copy the development Gemfile to enable local development:
```
cp Gemfile.dev Gemfile
```
Note While the gem in this file may eventually be deprecated, it's currently the simplest way to enable local development of the GitHub Pages site. As such, the Gemfile should not be committed into the repo.
Install the required Ruby dependencies:
```
bundle install
```
Install the npm dev packages:
```
npm install
```
Build the site locally: (Optional)
```
bundle exec jekyll build
```
To preview the site locally with live reload:
```
bundle exec jekyll serve
```
This will start a local server, typically at http://localhost:4000

Create a new branch for your documentation changes:
```
git checkout -b docs/your-feature-name
```
Make your changes to the documentation files in the docs directory.
Test your changes locally using the serve command mentioned above.
Verify your markdown file changes using the project's linting tools:

Note We use formatting/linting tools to ensure consistent formatting and quality across all markdown files.
```
cd docs
# Run the linter on all Markdown files in the docs directory
npm run lint-md "*.md"
# Or have the linter attempt to format automatically
npm run format-md "*.md"
```
This will check your Markdown files against our style rules and highlight any issues that need to be fixed.

Format HTML, CSS, and JavaScript files using the provided npm scripts:

# Format HTML and CSS files
npm run format-html-css

# Format JavaScript files
npm run format-js

Commit your changes:

git add .
git commit -m "docs: your descriptive commit message"

For the most accurate verification of your documentation changes, follow these steps:

Push your branch to your fork:
```
git push origin docs/your-feature-name
```
Set up GitHub Pages in your fork by following the official GitHub Pages documentation. Make sure to:
- Configure the source to deploy from your feature branch
- Set the folder to /docs
Wait for GitHub Pages to build and deploy your site. This may take a few minutes. You can monitor the progress in the "Actions" tab of your repository.
Once deployed, you can preview your changes at https://<YOUR_USERNAME>.github.io/fheroes2/
Review your changes in the preview environment to ensure:
- All links work correctly
- Images are displayed properly
- The layout is consistent with the main site
- No broken references or missing assets
After verifying everything looks correct in your fork's GitHub Pages, create a Pull Request (PR) from your fork's branch to the main fheroes2 repository for final review and deployment.

If you encounter Ruby version conflicts, make sure you're using a compatible version. You can use tools like rbenv or rvm to manage Ruby versions.
If the site doesn't build, check the Jekyll build logs for specific error messages.
If images aren't displaying, ensure they're placed in the correct directory (docs/images/) and referenced correctly in your markdown files.