Players' guide on GitHub Pages, built from docs/

A guide site for players (https://ayozetr.github.io/bloodborne_linux/), made with MkDocs Material
from docs/ itself, so the guide and the repository's documents never disagree. A theme of its
own, "Hunter's Dream" (moonlit blue-grey, IM Fell English headings, EB Garamond text, a moon and
mist on the home page), with no artwork or typeface from the game. New pages for players:
getting started, Steam and the Steam Deck, getting a log (Game Mode too) and a FAQ from the
questions asked in issues and on Reddit. A hook points links to files outside docs/ at GitHub.

Online play now starts with Seamless Hunt, the default server, and links read as words instead
of file names. The workflow builds the site (strict) and publishes it when docs/, mkdocs.yml or
site/ change on main. The README and the launcher's About page link to it.

.github/workflows/guide.yml

@@ -0,0 +1,47 @@
+# The players' guide on GitHub Pages: built from docs/ with MkDocs Material (mkdocs.yml) whenever
+# the documents or the site's theme change on main.
+name: Guide
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - docs/**
+      - mkdocs.yml
+      - site/**
+      - .github/workflows/guide.yml
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install -r site/requirements.txt
+      - run: mkdocs build --strict
+      - uses: actions/configure-pages@v5
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: _site
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -44,3 +44,6 @@ navigation-map*/
 atlas-tools/
 # Hunter's Atlas's own art (shipped; the launcher converts it for the game)
 !tools/hunters-atlas/art/*.png
+
+# The players' guide, built by mkdocs (mkdocs.yml)
+_site/

README.md

@@ -17,6 +17,9 @@ projects ([credits](docs/CREDITS.md)).
 > 1.09, from a retail release ([which ones](docs/COMPATIBILITY.md)). This project is not
 > affiliated with Sony Interactive Entertainment or FromSoftware.
 
+**[The players' guide](https://ayozetr.github.io/bloodborne_linux/)**: installing, playing online and
+seamless co-op, the Steam Deck, and what to do when something goes wrong.
+
 ## Features
 
 - **Multiplayer**: online messages, bloodstains, ghosts, bells and summons, on

docs/CREDITS.md

@@ -1,18 +1,18 @@
 # Credits
 
 Everyone whose work is in this fork, and every project it took something from. Everyone listed
-under *People* and *Help and testing* also appears in the launcher's **About** section. Components and their licenses: [BBPORT.md](../BBPORT.md#credits-and-licenses).
+under *People* and *Help and testing* also appears in the launcher's **About** section. Components and their licenses: [bbport's notes](../BBPORT.md#credits-and-licenses).
 
 ## Projects
 
 | Project | What this fork takes from it |
 |---|---|
-| [deadinside28/bloodborne_pc](https://github.com/deadinside28/bloodborne_pc) | **bbport**, the native Linux port everything here is built on. Its README is [BBPORT.md](../BBPORT.md). |
+| [deadinside28/bloodborne_pc](https://github.com/deadinside28/bloodborne_pc) | **bbport**, the native Linux port everything here is built on. Its README is [here](../BBPORT.md). |
 | [Supermedo/bloodborne_pc](https://github.com/Supermedo/bloodborne_pc) | The Windows port: online play, DLSS, the cheats page, Add to Steam, the icon, the direct mouse camera, ultrawide, Quit to Desktop, the keyboard sprint and many fixes. |
 | [Awakenchan/LanternEngine](https://github.com/Awakenchan/LanternEngine) (formerly BloodBorneButPc) | Lantern Engine by Awaken (https://github.com/Awakenchan/LanternEngine) (GPL-3.0-or-later): video memory on 4 GB cards, crash and freeze fixes, fewer stutters while areas load, stick options, save import and the version selector. |
 | [shadPS4](https://github.com/shadps4-emu/shadPS4) | The renderer and shader recompiler, and the online code. |
 | [Wozzardman/shadp2p](https://github.com/Wozzardman/shadp2p) | The network and PSN libraries for online play. |
-| [Wozzardman/shadnet-p2p](https://github.com/Wozzardman/shadnet-p2p) | The shadNet server for a group's own co-op server ([SERVER.md](SERVER.md)). |
+| [Wozzardman/shadnet-p2p](https://github.com/Wozzardman/shadnet-p2p) | The shadNet server for a group's own co-op server ([hosting your own server](SERVER.md)). |
 | [MaskZeus/bbbridge](https://github.com/MaskZeus/bbbridge) | Co-op on The Hunter's Dream's pool ([bbbridge/](../bbbridge/)). |
 | [Classmg22/BBSC](https://github.com/Classmg22/BBSC) | Seamless Co-op, by CLS_AMG, with Wozzardman's seamless summon ([bbsc/](../bbsc/)). |
 | [fhody125-web/NoDreamForHunter](https://github.com/fhody125-web/NoDreamForHunter) | The base of BBSC's game server. |

docs/ONLINE.md

@@ -9,6 +9,21 @@ everyone needs the game at version 1.09 and the same pool.
 > right after the login ("This shadNet server doesn't accept your shadPS4 build" in the log), and
 > the launcher says so. The pools for bbport are Seamless Hunt (the default), The Hunter's Dream's and a server of your own.
 
+## Seamless Hunt
+
+[Seamless Hunt](https://install.seamlesshunt.com) is a community server for Seamless Co-op (BBSC),
+where Windows players join with BBSC's package for the Windows port.
+
+1. In the launcher's **Multiplayer → Online** tab, turn on **Play online** and choose **Seamless Hunt**: its
+   shadNet server, WebAPI and game server come with it.
+2. Type a name and a password under **Account** and press **Create** (once). The server wants an
+   email for each account; the launcher makes one from the name, as Seamless Hunt's own tool does.
+3. Turn on BBSC in the **Seamless co-op (BBSC)** group and press **Test** in the **Status** row.
+
+Its bloodstains and death visions crash the game with "Transaction failed", on Windows too: they
+are off by default, as in Seamless Hunt's package (**Bloodstains on Seamless Hunt** brings them
+back). Messages, ghosts and summon signs are not affected.
+
 ## The Hunter's Dream (with bbhost's players)
 
 Choose **The Hunter's Dream (with bbhost players)** in the launcher's **Multiplayer → Online** tab.
@@ -28,24 +43,9 @@ show you.
 do not support bbport: report problems here ([issues](https://github.com/ayozetr/bloodborne_linux/issues)),
 not to The Hunter's Dream's support.
 
-## Seamless Hunt
-
-[Seamless Hunt](https://install.seamlesshunt.com) is a community server for Seamless Co-op (BBSC),
-where Windows players join with BBSC's package for the Windows port.
-
-1. In the launcher's **Multiplayer → Online** tab, turn on **Play online** and choose **Seamless Hunt**: its
-   shadNet server, WebAPI and game server come with it.
-2. Type a name and a password under **Account** and press **Create** (once). The server wants an
-   email for each account; the launcher makes one from the name, as Seamless Hunt's own tool does.
-3. Turn on BBSC in the **Seamless co-op (BBSC)** group and press **Test** in the **Status** row.
-
-Its bloodstains and death visions crash the game with "Transaction failed", on Windows too: they
-are off by default, as in Seamless Hunt's package (**Bloodstains on Seamless Hunt** brings them
-back). Messages, ghosts and summon signs are not affected.
-
 ## Your own server
 
-Its owner creates the account ([SERVER.md](SERVER.md)), or you make it with **Create** under
+Its owner creates the account ([hosting your own server](SERVER.md)), or you make it with **Create** under
 **Account** when the server lets anyone register.
 
 1. In the launcher's **Multiplayer → Online** tab, turn on **Play online**, choose **Your own server** with
@@ -74,7 +74,7 @@ items and echoes it gets, and enemies get stronger for every guest. It runs insi
    normal game.
 3. The server decides how much of it works:
    - **BBSC's game server** (Seamless Hunt's, which comes with it, or your group's,
-     [SERVER.md](SERVER.md#seamless-co-op-bbsc)): everything, summons across areas and 5 hunters included. Set it as the
+     [hosted with it](SERVER.md#seamless-co-op-bbsc)): everything, summons across areas and 5 hunters included. Set it as the
      **Game server** of the Online tab.
    - **The Hunter's Dream**: the session stays together (deaths, lamps, bosses), but summons are
      the normal game's: BBSC turns its own summon changes and the 5 hunters off on public servers.
@@ -114,7 +114,7 @@ the game's log has its warnings (`BBSC:` lines). Not in the Linux build: BBSC's
 ## Ports
 
 Co-op traffic is UDP, straight between the players' computers. With your own server on
-Tailscale ([SERVER.md](SERVER.md)) it goes through Tailscale: turn **UPnP** off and skip this
+Tailscale ([hosting your own server](SERVER.md)) it goes through Tailscale: turn **UPnP** off and skip this
 section. Otherwise each player has to be reachable from the Internet:
 
 1. **The router.** With **UPnP** on (the default), the game opens its port on the router itself:

docs/README.md

@@ -2,6 +2,13 @@
 
 ## For players
 
+The same documents, with a few pages written for players, make up the
+[players' guide](https://ayozetr.github.io/bloodborne_linux/) (built from this folder: `mkdocs.yml`).
+
+- [getting-started.md](getting-started.md): what you need, the first launch, saves and updates.
+- [steam-deck.md](steam-deck.md): Add to Steam, the Steam Deck's Game Mode, Steam Input and the overlay.
+- [logs.md](logs.md): getting a log, also from Game Mode, and sending it.
+- [faq.md](faq.md): the questions players ask most.
 - [COMPATIBILITY.md](COMPATIBILITY.md): which releases of Bloodborne run, and which have been
   checked.
 - [TROUBLESHOOTING.md](TROUBLESHOOTING.md): common problems and what to do.

docs/SERVER.md

@@ -203,4 +203,4 @@ settings).
   the server; `tailscale ping <player>` from each side. Everyone needs the game at version 1.09
   and the same co-op mode.
 
-See also [ONLINE.md](ONLINE.md) for the bells, passwords and log lines of a summon.
+See also [Online play and co-op](ONLINE.md) for the bells, passwords and log lines of a summon.

docs/TROUBLESHOOTING.md

@@ -12,7 +12,7 @@ The launcher checks the game folder before starting. What it says, and what to d
 | bbport needs the 1.09 update merged into the game folder | Copy everything from the dumped 1.09 update into the game folder, replacing files (`eboot.bin` and `sce_sys` too). |
 | param.sfo is from 1.09 but eboot.bin is not | Copy `eboot.bin` from the dumped 1.09 update over the old one. |
 | This eboot.bin has the 60 fps patch by Lance McDonald applied | Use a clean `eboot.bin` from the 1.09 update. bbport has its own 60 FPS. |
-| This is not a retail release of Bloodborne | Alpha tests and other games do not run. See [COMPATIBILITY.md](COMPATIBILITY.md). |
+| This is not a retail release of Bloodborne | Alpha tests and other games do not run. See [supported releases](COMPATIBILITY.md). |
 | eboot.bin could not be read as a decrypted PS4 executable | Dump the game and the update again. |
 | The game files are damaged | The extraction tool broke compressed files (LibOrbisPkg PkgTool on .NET 6 or newer); the game would hang while loading. Extract the game and the update again with a fixed tool. |
 
@@ -112,9 +112,9 @@ camera can feel heavier: the game's own *Camera speed* setting makes up for it.
 Press **Test** in the **Status** row of **Multiplayer → Online**. An error mark on the shadNet server's UDP line means
 the server never learns your address, and no summon can connect: check that the server is running
 and that its log lists the UDP listener, and that no firewall blocks UDP 31314 on its side
-([SERVER.md](SERVER.md)). shadPS4's public server does not accept bbport builds at all: use The
+([hosting your own server](SERVER.md)). shadPS4's public server does not accept bbport builds at all: use The
 Hunter's Dream, Seamless Hunt or your own server.
 
 ## Other online problems
 
-See [ONLINE.md](ONLINE.md): the account, the bells, the ports and the log lines of a summon.
+See [Online play and co-op](ONLINE.md): the account, the bells, the ports and the log lines of a summon.

docs/faq.md

@@ -0,0 +1,47 @@
+# FAQ
+
+## Is this an emulator?
+
+No. The game's own code runs directly on the CPU, and its graphics are translated to Vulkan. It is
+built on [bbport](https://github.com/deadinside28/bloodborne_pc) by deadinside28.
+
+## Where do I get the game?
+
+From your own PS4: a dump of your copy with update 1.09. No game files are included, and none can
+be shared here.
+
+## Can I play with Windows players?
+
+Yes. On Seamless Hunt or The Hunter's Dream, Linux and Windows players play together; for seamless
+co-op everyone needs the same BBSC version (0.0.2). [Online play](ONLINE.md).
+
+## Summons take a long time
+
+Some waiting is normal: the game checks for summon signs about every 35 seconds, as the PS4's
+servers had it, so a sign can take over half a minute to show up.
+
+## My friend never gets summoned with the Kin Bell
+
+It depends on the server:
+
+- On **Seamless Hunt** (or your own server with BBSC's game server), seamless co-op works fully:
+  summons across areas and up to 5 hunters.
+- On **The Hunter's Dream**, BBSC keeps the session together, but summons are the normal game's:
+  both hunters must be in the **same area**, the area's boss must still be alive in the host's world,
+  and your levels must be within range.
+
+[Seamless co-op on each server](ONLINE.md#seamless-co-op-bbsc).
+
+## Do I need to open ports on my router?
+
+No. With seamless co-op (BBSC) on, Seamless Hunt relays players who cannot reach each other
+directly, and The Hunter's Dream's bridge relays by itself. Only [your own server](SERVER.md) needs a few ports, through Tailscale.
+
+## How do I get a log on the Steam Deck?
+
+Turn on *Advanced → Developer → Save the log and statistics to a file* once in Desktop Mode; Game
+Mode sessions then save theirs too. [Getting a log](logs.md).
+
+## The game updated and my Steam shortcut stopped working
+
+Press **Add to Steam** again in the launcher: it updates the shortcut.

docs/getting-started.md

@@ -0,0 +1,41 @@
+# Getting started
+
+## What you need
+
+- **Your own dump of Bloodborne with update 1.09**, from your PS4: any retail release (US, Europe,
+  UK, Japan, Asia, and the editions with The Old Hunters). No game files are included, and other
+  versions of the game's executable start and then crash. [Which releases work](COMPATIBILITY.md).
+- **Linux x86-64** and a GPU with **Vulkan 1.3**: AMD or Intel with Mesa, or NVIDIA with NVIDIA's
+  driver. The Steam Deck works too.
+- About **6 GB of free memory**, 10 GB for 1440p or 4K.
+
+## First launch
+
+1. Download `Bloodborne-bbport-x86_64.AppImage` from the
+   [latest release](https://github.com/ayozetr/bloodborne_linux/releases/latest).
+2. Make it executable (in a file manager: *Properties → Permissions → Allow executing*, or
+   `chmod +x Bloodborne-bbport-x86_64.AppImage`) and run it.
+3. In the launcher, choose your **game folder**: the one with `eboot.bin` in it.
+4. Press **Play**.
+
+!!! tip "The first minutes"
+    The first time, the game builds its shaders as it meets them, so it can stutter for a few
+    minutes. The next sessions start with them ready.
+
+## Saves, settings and the DLC
+
+- Saves and settings go to `~/.local/share/bbport`.
+- **Setup → Saves** exports your saves into a `.zip` and imports them back, also from shadPS4.
+- The Game of the Year edition already has *The Old Hunters*. With the base game, put its DLC
+  folder in **Setup → DLC folder**.
+
+## Updating
+
+The launcher's **About** page says when a new release is out and installs it; it can also go back
+to an earlier one. Your saves and settings stay as they are.
+
+## Next steps
+
+- [Play online](ONLINE.md), alone or in seamless co-op.
+- [Add the game to Steam](steam-deck.md), or play on the Steam Deck.
+- Something wrong? [Troubleshooting](TROUBLESHOOTING.md) and [getting a log](logs.md).

docs/index.md

@@ -0,0 +1,32 @@
+---
+template: home.html
+title: Home
+hide:
+  - navigation
+  - toc
+---
+
+# Where to begin
+
+The PlayStation 4 version of *Bloodborne*, running natively on Linux and the Steam Deck: the
+game's own code runs on the CPU and its graphics are translated to Vulkan. You need your own dump
+of the game with update 1.09; no game files are included.
+
+<div class="hd-cards">
+<a class="hd-card" href="getting-started/"><strong>Getting started</strong><span>Your dump, the AppImage and the first launch.</span></a>
+<a class="hd-card" href="ONLINE/"><strong>Playing online</strong><span>Seamless Hunt, The Hunter's Dream or your own server, and seamless co-op.</span></a>
+<a class="hd-card" href="steam-deck/"><strong>Steam and the Steam Deck</strong><span>Add to Steam, Game Mode, controllers and the Steam overlay.</span></a>
+<a class="hd-card" href="TROUBLESHOOTING/"><strong>When something breaks</strong><span>Common problems, and how to send a log.</span></a>
+</div>
+
+## What you get
+
+- **Online and co-op**: messages, bloodstains, bells and summons, and **seamless co-op** that
+  lasts through deaths, lamps and areas, with Linux and Windows players together.
+- **Local co-op**: 2 to 4 players on one PC, each with their own controller.
+- **Hunter's Atlas**: a fullscreen in-game map with fast travel to the lamps you have found.
+- **Frame rate unlocked** or capped at 30, 60 or 90, from **720p to 4K**, and ultrawide screens.
+- **FSR 3.1, FSR 4 and DLSS** upscaling.
+- **Any controller**, with its own button prompts in the game, and **keyboard and mouse**.
+- **Trophies**, **Discord** status and **Add to Steam** in one click.
+- An **AppImage** for any distribution and the Steam Deck, which **updates itself**.

docs/logs.md

@@ -0,0 +1,28 @@
+# Getting a log
+
+A log is the first thing needed to fix a problem: it says what the game and the GPU were doing.
+
+## From the launcher
+
+1. Turn on *Advanced → Developer → Save the log and statistics to a file*. It stays on.
+2. Play until the problem happens, then close the game.
+3. The log is in `~/.local/share/bbport/logs`, named after the time the game started
+   (`20261026_183438.log`). The launcher's **Log** page shows the last one too.
+
+This also works when the game is started from Steam or from the Steam Deck's Game Mode: turn the
+option on once in the launcher, and every session saves its log.
+
+## Sending it
+
+Open an [issue](https://github.com/ayozetr/bloodborne_linux/issues/new/choose) and attach the
+`.log` file. It helps a lot to say:
+
+- what happened, and roughly when (an area, a boss, a menu, after a lamp travel);
+- your distribution, GPU and driver;
+- the upscaler, preset and output resolution;
+- for online problems, which server and whether seamless co-op (BBSC) was on, and the other
+  player's log too if you can.
+
+!!! note "Crashes"
+    *Advanced → Developer → Crash diagnostics* adds checks that point at what went wrong in some
+    crashes. The game runs a bit slower with it on: turn it on when asked in an issue.

docs/steam-deck.md

@@ -0,0 +1,37 @@
+# Steam and the Steam Deck
+
+## Add to Steam
+
+**Setup → Game → Add to Steam** puts *Bloodborne* in your Steam library as a non-Steam game. It
+starts the game straight away, with the launcher's settings, without opening the launcher. Steam
+has to close for it, and the launcher offers to do that.
+
+After updating from an older release, press **Add to Steam** once more so the shortcut points to
+the right place.
+
+## On the Steam Deck
+
+1. In Desktop Mode, download the AppImage and set the game up in the launcher, as in
+   [Getting started](getting-started.md). A resolution of **720p** with an upscaler (FSR) suits the
+   Deck's screen.
+2. Press **Add to Steam**.
+3. Back in Game Mode, start *Bloodborne* from your library.
+
+To change a setting later, go back to Desktop Mode and open the launcher: what you change there is
+what Game Mode uses.
+
+!!! tip "Logs in Game Mode"
+    Turn on *Advanced → Developer → Save the log and statistics to a file* once in Desktop Mode:
+    every session played from Game Mode then saves its log too. [Getting a log](logs.md).
+
+## Controllers and Steam Input
+
+With Steam Input on, the game gets Steam's virtual controller. On a Wayland desktop the game then
+opens its window through Xwayland, so Steam's input reaches it. With Steam Input off, the game reads
+the controller itself. [More](TROUBLESHOOTING.md#the-controller-does-nothing-when-the-game-is-started-from-steam).
+
+## The Steam overlay
+
+Shift+Tab, Steam's FPS counter and F12 screenshots need **Steam overlay**, under *Add to Steam* in
+the launcher (off by default), and the game started from Steam.
+[More](TROUBLESHOOTING.md#the-steam-overlay-does-not-open-in-the-game).

docs/stylesheets/hunters-dream.css

@@ -0,0 +1,148 @@
+/* The players' guide: "Hunter's Dream" theme over MkDocs Material's dark scheme. Moonlit
+   blue-grey; IM Fell English for headings and menus, EB Garamond for reading (IM Fell has only
+   old-style figures: 1 and 0 read as ı and o in versions and values). No artwork or typeface from
+   the game. */
+@import url("https://fonts.googleapis.com/css2?family=EB+Garamond:ital,wght@0,400;0,500;0,600;1,400&family=IM+Fell+English:ital@0;1&family=IM+Fell+English+SC&family=JetBrains+Mono:wght@400&display=swap");
+
+[data-md-color-scheme="slate"] {
+  --hd-bg: #0f1218;
+  --hd-bg-raised: #12161e;
+  --hd-line: #2a3140;
+  --hd-text: #d4d9e2;
+  --hd-muted: #a9b3c4;
+  --hd-bright: #f2f4f8;
+  --hd-moon: #e4eaf5;
+  --hd-blood: #e0a0a0;
+
+  --md-default-bg-color: var(--hd-bg);
+  --md-default-fg-color: var(--hd-text);
+  --md-default-fg-color--light: var(--hd-muted);
+  --md-default-fg-color--lighter: #6f7a8c;
+  --md-default-fg-color--lightest: var(--hd-line);
+  --md-primary-fg-color: #141924;
+  --md-primary-fg-color--dark: #1a2030;
+  --md-primary-fg-color--light: #2a3140;
+  --md-primary-bg-color: var(--hd-bright);
+  --md-accent-fg-color: #ffffff;
+  --md-typeset-a-color: #b9c8e6;
+  --md-code-bg-color: #0a0d12;
+  --md-code-fg-color: #c8d3e6;
+  --md-footer-bg-color: #0b0d12;
+  --md-footer-bg-color--dark: #08090d;
+  --md-text-font-family: "EB Garamond", Georgia, serif;
+  --md-code-font-family: "JetBrains Mono", monospace;
+}
+
+body, input { font-family: "EB Garamond", Georgia, serif; font-variant-numeric: lining-nums; }
+.md-typeset { font-size: .92rem; line-height: 1.65; }
+.md-typeset code, .md-typeset pre { font-family: "JetBrains Mono", monospace; }
+
+/* Headings, the header and the navigation in the small-capitals cut. */
+.md-typeset h1, .md-typeset h2, .md-typeset h3, .md-typeset h4,
+.md-header__title, .md-nav__title, .md-tabs__link, .md-nav__item--section > .md-nav__link {
+  font-family: "IM Fell English SC", Georgia, serif;
+  font-weight: 400;
+  letter-spacing: .02em;
+}
+.md-typeset h1 { color: var(--hd-bright); font-family: "IM Fell English", Georgia, serif; }
+.md-typeset h2 { color: var(--hd-bright); border-bottom: 1px solid var(--hd-line); padding-bottom: .2em; }
+.md-typeset h3 { color: #c4cfe2; }
+
+.md-header { background: rgba(15, 18, 24, .85); backdrop-filter: blur(6px); border-bottom: 1px solid var(--hd-line); box-shadow: none; }
+.md-sidebar--primary .md-nav__link--active { color: #fff; }
+/* The phone drawer: its repository strip and title in the theme's colours, not Material's blue. */
+.md-nav__source { background-color: #1a2030; }
+.md-nav--primary .md-nav__title[for="__drawer"] { background-color: #141924; }
+.md-sidebar--primary .md-nav__link--active::before { content: "✦ "; color: #9fb0d0; }
+.md-nav__link:hover, .md-typeset a:hover { color: #fff; }
+
+/* Admonitions: quiet frames instead of Material's bright ones. */
+.md-typeset .admonition, .md-typeset details {
+  background: rgba(160, 180, 215, .06);
+  border: 1px solid #2f3a4f !important;
+  border-radius: 4px;
+  box-shadow: none;
+  font-size: .85rem;
+}
+.md-typeset .admonition-title, .md-typeset summary {
+  background: transparent !important;
+  font-family: "IM Fell English SC", Georgia, serif;
+  color: #c4cfe2;
+}
+.md-typeset .admonition-title::before, .md-typeset summary::before { background-color: #9fb0d0 !important; }
+.md-typeset .warning, .md-typeset .danger { border-color: #5a3a3a !important; background: rgba(170, 80, 80, .08); }
+.md-typeset .warning > .admonition-title, .md-typeset .danger > .admonition-title { color: var(--hd-blood); }
+.md-typeset .warning > .admonition-title::before, .md-typeset .danger > .admonition-title::before { background-color: var(--hd-blood) !important; }
+
+.md-typeset table:not([class]) { border: 1px solid var(--hd-line); font-size: .8rem; }
+/* Reference tables (ENVIRONMENT.md): names whole, and every column wide enough to read. */
+.md-typeset table:not([class]) td:first-child code { white-space: nowrap; word-break: normal; }
+.md-typeset table:not([class]) td:nth-child(2) { min-width: 6rem; }
+.md-typeset table:not([class]) td:nth-child(3) { min-width: 15rem; }
+.md-typeset table:not([class]) td:nth-child(4) { min-width: 7rem; }
+/* Wider pages than Material's 61rem: the reference tables have four columns. */
+.md-grid { max-width: 90rem; }
+.md-typeset table:not([class]) td code { word-break: break-word; }
+.md-typeset table:not([class]) th { background: var(--hd-bg-raised); font-family: "IM Fell English SC", Georgia, serif; font-weight: 400; }
+
+/* Home page: the moon and the mist (overrides/home.html). */
+.hd-hero {
+  position: relative;
+  overflow: hidden;
+  text-align: center;
+  padding: 7rem 1rem 6.5rem;
+  background:
+    radial-gradient(circle at 78% 22%, #eef2f9 0 42px, rgba(220, 228, 244, .35) 43px, rgba(200, 212, 236, .10) 110px, transparent 210px),
+    radial-gradient(ellipse 70% 40% at 50% 100%, rgba(160, 175, 205, .22), transparent 70%),
+    linear-gradient(#1c2335, var(--hd-bg) 75%);
+}
+.hd-hero::after {
+  content: "";
+  position: absolute;
+  inset: auto 0 0 0;
+  height: 160px;
+  background: linear-gradient(transparent, rgba(190, 200, 220, .10) 60%, var(--hd-bg));
+}
+.hd-hero__content { position: relative; z-index: 1; }
+.hd-hero h1 { margin: 0; font: 400 clamp(2.4rem, 6vw, 4.4rem) "IM Fell English", Georgia, serif; color: var(--hd-bright); }
+.hd-hero p { margin: .9rem 0 0; color: #b8c2d3; font-style: italic; font-size: 1.3rem; }
+.hd-buttons { display: flex; gap: .9rem; justify-content: center; flex-wrap: wrap; margin-top: 2rem; }
+.hd-button {
+  padding: .75rem 1.75rem;
+  font: 1.1rem "IM Fell English SC", Georgia, serif;
+  color: #e9edf3 !important;
+  border: 1px solid rgba(220, 228, 240, .45);
+  border-radius: 2px;
+  background: rgba(15, 18, 24, .55);
+  transition: background .2s, border-color .2s;
+}
+.hd-button:hover { background: rgba(255, 255, 255, .1); border-color: rgba(240, 244, 250, .8); }
+.hd-button--primary { background: rgba(228, 234, 245, .92); color: #141822 !important; border-color: transparent; }
+.hd-button--primary:hover { background: #fff; }
+
+.hd-home { max-width: 54rem; margin: 0 auto; }
+.hd-cards { display: grid; grid-template-columns: repeat(2, 1fr); gap: 1rem; margin: 1.2rem 0 2rem; }
+.hd-card {
+  display: block;
+  border: 1px solid var(--hd-line);
+  background: rgba(160, 180, 215, .05);
+  padding: 1.1rem 1.2rem;
+  border-radius: 4px;
+  color: var(--hd-text) !important;
+  transition: border-color .2s, background .2s;
+}
+.hd-card:hover { border-color: #5b6a86; background: rgba(160, 180, 215, .09); }
+.hd-card strong { display: block; font: 1.25rem "IM Fell English SC", Georgia, serif; font-weight: 400; color: #dfe5ef; margin-bottom: .3rem; }
+.hd-card span { color: var(--hd-muted); font-size: .85rem; }
+
+@media screen and (max-width: 44.9375em) {
+  /* A smaller moon in the corner: in the middle it covered the title. */
+  .hd-hero {
+    padding: 4.5rem 1rem 4rem;
+    background:
+      radial-gradient(circle at 86% 11%, #eef2f9 0 22px, rgba(220, 228, 244, .35) 23px, rgba(200, 212, 236, .10) 60px, transparent 120px),
+      radial-gradient(ellipse 70% 40% at 50% 100%, rgba(160, 175, 205, .22), transparent 70%),
+      linear-gradient(#1c2335, var(--hd-bg) 75%);
+  }
+  .hd-cards { grid-template-columns: 1fr; }
+}

launcher/bbport_i18n.py

@@ -716,6 +716,7 @@ EN = {
         "Couldn't update: {}",
     "Сначала закройте игру":
         "Close the game first",
+    'Руководство для игроков': "Players' guide",
     "Этот проект":
         "This project",
     "Основано на bbport от deadinside28":
@@ -1635,6 +1636,7 @@ PT_BR = {
         "Não foi possível atualizar: {}",
     "Сначала закройте игру":
         "Feche o jogo primeiro",
+    'Руководство для игроков': 'Guia para jogadores',
     "Этот проект":
         "Este projeto",
     "Основано на bbport от deadinside28":
@@ -2518,6 +2520,7 @@ ES = {
         "No se pudo actualizar: {}",
     "Сначала закройте игру":
         "Cierra el juego primero",
+    'Руководство для игроков': 'Guía para jugadores',
     "Этот проект":
         "Este proyecto",
     "Основано на bbport от deadinside28":
@@ -3401,6 +3404,7 @@ IT = {
         "Impossibile aggiornare: {}",
     "Сначала закройте игру":
         "Chiudi prima il gioco",
+    'Руководство для игроков': 'Guida per i giocatori',
     "Этот проект":
         "Questo progetto",
     "Основано на bbport от deadinside28":
@@ -4284,6 +4288,7 @@ FR = {
         "Mise à jour impossible : {}",
     "Сначала закройте игру":
         "Fermez d'abord le jeu",
+    'Руководство для игроков': 'Guide des joueurs',
     "Этот проект":
         "Ce projet",
     "Основано на bbport от deadinside28":
@@ -5167,6 +5172,7 @@ DE = {
         "Aktualisierung fehlgeschlagen: {}",
     "Сначала закройте игру":
         "Schließe zuerst das Spiel",
+    'Руководство для игроков': 'Anleitung für Spieler',
     "Этот проект":
         "Dieses Projekt",
     "Основано на bbport от deadinside28":
@@ -6021,6 +6027,7 @@ ZH_CN = {
         "无法更新：{}",
     "Сначала закройте игру":
         "请先关闭游戏",
+    'Руководство для игроков': '玩家指南',
     "Этот проект":
         "本项目",
     "Основано на bbport от deadinside28":

launcher/bbport_launcher.py

@@ -3106,6 +3106,8 @@ class LauncherWindow(Adw.ApplicationWindow):
         for title, subtitle, url, icon in (
                 (tr("Этот проект"), bbport_update.REPOSITORY_URL, bbport_update.REPOSITORY_URL,
                  "github-symbolic"),
+                (tr("Руководство для игроков"), bbport_update.GUIDE_URL, bbport_update.GUIDE_URL,
+                 "help-browser-symbolic"),
                 (tr("Основано на bbport от deadinside28"), bbport_update.UPSTREAM_URL,
                  bbport_update.UPSTREAM_URL, "github-symbolic"),
                 (tr("Порт для Windows от Supermedo"), bbport_update.WINDOWS_URL,

launcher/bbport_update.py

@@ -19,6 +19,8 @@ REPOSITORY_URL = f"https://github.com/{REPOSITORY}"
 UPSTREAM_URL = "https://github.com/deadinside28/bloodborne_pc"
 WINDOWS_URL = "https://github.com/Supermedo/bloodborne_pc"
 LICENSE_URL = f"{REPOSITORY_URL}/blob/main/LICENSE"
+# The players' guide (GitHub Pages, built from docs/: mkdocs.yml).
+GUIDE_URL = "https://ayozetr.github.io/bloodborne_linux/"
 KOFI_URL = "https://ko-fi.com/ayozetr"
 RELEASES_URL = f"{REPOSITORY_URL}/releases"
 LATEST_API = f"https://api.github.com/repos/{REPOSITORY}/releases/latest"

mkdocs.yml

@@ -0,0 +1,71 @@
+# The players' guide on GitHub Pages (.github/workflows/guide.yml): built from docs/ with
+# MkDocs Material, so the guide and the repository's documents never disagree.
+site_name: Bloodborne for Linux
+site_description: How to install, play online and fix problems with the Linux port of Bloodborne.
+site_url: https://ayozetr.github.io/bloodborne_linux/
+repo_url: https://github.com/ayozetr/bloodborne_linux
+repo_name: ayozetr/bloodborne_linux
+edit_uri: edit/main/docs/
+copyright: GPL-3.0-or-later. Bloodborne is by FromSoftware and Sony Interactive Entertainment; this project is not affiliated with either. No game files are included.
+
+docs_dir: docs
+# Not MkDocs' default site/: that folder holds the theme and the hook.
+site_dir: _site
+exclude_docs: |
+  README.md
+  RELEASE_TEMPLATE.md
+
+theme:
+  name: material
+  custom_dir: site/overrides
+  font: false
+  palette:
+    scheme: slate
+  features:
+    - navigation.instant
+    - navigation.sections
+    - navigation.top
+    - navigation.footer
+    - search.suggest
+    - search.highlight
+    - content.code.copy
+    - toc.follow
+  icon:
+    repo: fontawesome/brands/github
+
+hooks:
+  - site/repo_links.py
+
+extra_css:
+  - stylesheets/hunters-dream.css
+
+markdown_extensions:
+  - admonition
+  - attr_list
+  - md_in_html
+  - pymdownx.details
+  - pymdownx.superfences
+  - toc:
+      permalink: true
+
+nav:
+  - Home: index.md
+  - Getting started: getting-started.md
+  - Steam and the Steam Deck: steam-deck.md
+  - Playing online:
+      - Online play and co-op: ONLINE.md
+      - Your own server: SERVER.md
+  - Help:
+      - Troubleshooting: TROUBLESHOOTING.md
+      - Getting a log: logs.md
+      - FAQ: faq.md
+      - Supported releases: COMPATIBILITY.md
+  - Mods: MODS.en.md
+  - Credits: CREDITS.md
+  - For developers:
+      - Environment variables: ENVIRONMENT.md
+      - Debugging a crash: DEBUGGING.md
+      - GPU commands in parallel: parallel_gpu.md
+      - Upscaling and frame generation: upscaler.md
+      - The translator: TRANSLATOR_ARCHITECTURE.md
+      - The memory module: MEMORY_MODULE_PLAN.md

site/overrides/home.html

@@ -0,0 +1,19 @@
+{% extends "main.html" %}
+
+{# The home page: the moon-and-mist hero above the page's own content (docs/index.md). #}
+{% block hero %}
+<section class="hd-hero">
+  <div class="hd-hero__content">
+    <h1>Bloodborne for Linux</h1>
+    <p>Welcome home, good hunter. Here is how to play, alone or together.</p>
+    <div class="hd-buttons">
+      <a class="hd-button hd-button--primary" href="https://github.com/ayozetr/bloodborne_linux/releases/latest">Download</a>
+      <a class="hd-button" href="{{ 'getting-started/' | url }}">Read the guide</a>
+    </div>
+  </div>
+</section>
+{% endblock %}
+
+{% block content %}
+  <div class="hd-home">{{ page.content }}</div>
+{% endblock %}

site/overrides/main.html

@@ -0,0 +1,7 @@
+{% extends "base.html" %}
+
+{# The site is dark already: Dark Reader would recolour it (the light Download button came out
+   dark), so it is told to leave it alone. #}
+{% block extrahead %}
+  <meta name="darkreader-lock">
+{% endblock %}

site/repo_links.py

@@ -0,0 +1,26 @@
+"""MkDocs hook: links in docs/ to files elsewhere in the repository (../BBPORT.md, ../bbsc/) point
+to them on GitHub, since the guide is built from docs/ alone. The documents stay as they are, so
+the same links keep working when they are read on GitHub."""
+import posixpath
+import re
+
+REPOSITORY = "https://github.com/ayozetr/bloodborne_linux"
+LINK = re.compile(r"(\]\()([^)\s]+)(\))")
+
+
+def on_page_markdown(markdown, page, **kwargs):
+    folder = posixpath.dirname(page.file.src_uri)
+
+    def outside(match):
+        target = match.group(2)
+        if "://" in target or target.startswith(("#", "mailto:")):
+            return match.group(0)
+        path, _, anchor = target.partition("#")
+        resolved = posixpath.normpath(posixpath.join("docs", folder, path))
+        if resolved == "docs" or resolved.startswith("docs/"):
+            return match.group(0)
+        kind = "tree" if path.endswith("/") or "." not in posixpath.basename(path) else "blob"
+        url = f"{REPOSITORY}/{kind}/main/{resolved.rstrip('/')}" + (f"#{anchor}" if anchor else "")
+        return match.group(1) + url + match.group(3)
+
+    return LINK.sub(outside, markdown)

site/requirements.txt

@@ -0,0 +1,2 @@
+mkdocs==1.6.1
+mkdocs-material==9.8.0