ESO Website

Install the requirements

mise install

Alternatively, install node lts + hugo-extended + go manually.

Build the website locally

npm install
npm run _build

This will:

• build the hugo website
• build the search index
• publish content in public/ folder
• chmod such folder.

See all the actions happening in package.json

Contributing: Preview the website before your first change

After your first install/build (see above), you can build a site preview server by running.

hugo server

This starts a webserver on port 1313 which will reload the website upon a content file change. The search index will NOT be recreated with hugo server (see below).

Contributing: Test the search

Local search is using an index that is built using the following command:

npm run build:search

Run this command everytime you want to rebuild the search indexes. This setp is mandatory at every release. This command is included in the build process but does not run on the hugo server command.

Explanation: How does the search work?

To avoid reliance on server based solutions, we are leveraging solr, included in the docsy template.

However, docsy is not meant for multiple software multiple versions by default, and we had specific requirements in mind for search.

With the amount of content we have, the performance was subpar.

We had to change the default behaviour for docsy as following:

• Generate json containing indexed content
• Ensure the json is not too large to avoid processing large json in DOM
• Use only the right subset of versions for each search, meanign more splitting and merging.

This is how search operates:

At build time: 0. hugo generates offline-search-index.json

1. script build-search-indexes.js reads offline-search-index.json and computes buildFingerprint (MD5 of its content)
2. script writes public/offline-search-fingerprint.json for cache invalidation { fingerprint: "" }
3. script builds per-version search-index.json via buildIndex(docs, buildFingerprint). each file contains { buildFingerprint: "", index: ..., details: ... }

At browse time (offline-search.js):

1. User searches and tries to hit IndexedDB cache for /eso-docs/v{version}/search-index.json
2. fetch /offline-search-fingerprint.json from the server
3. client compares cached.buildFingerprint (stamped into the IndexedDB entry when it was saved) against currentFingerprint (from the server file)
4. Mismatch: treat as cache miss, re-fetch from network. Else cache hit.

Contributing: Prepare for a new release

Ensure you can run scripts/new-version by adding it into your go.work:

go 1.25.7

use (
    .
    ./scripts/release
)

Run the release script

export PROJECT="eso" # can be eso or reloader
export TAG="v3.0.7" # this is an example for a fictive version 3.0.7. Do not forget the 'v'. Do not forget the patch version either.
go run ./scripts/release --project ${PROJECT} --tag ${TAG}

This will update the matrix of known versions in data/ , which is used to generate the releases page. It will also copy the docs in the project's "unreleased" folder into its stable "major.minor" version form, and update its front matter with version major.minor.

You can then test the website like any other contribution.

Check a version X for project Y (eso, relaoder) is properly documented

1. Ensure data/${Y}_versions.toml contains X
2. Ensure the folder content/en/${Y}-docs/${X} exists and contains an _index.md

Import old release (BETA!)

Read and adapt the code in scripts/converter/convert_mkdocs_to_hugo.py based on your needs.