This is a rethink of Xonotic's main website. It uses hugo so it's simple and static, making administration and ongoing maintenance a good deal easier.

Install Hugo, v0.83.0 or later extended build is needed. Debian's hugo package is the extended build.

Run it in the xonotic.org repo's root: make server or hugo server --watch --gc

It will offer a localhost link to preview the site and the page(s) will be refreshed automatically when you save a change.

Note that the navigation bar is hardcoded to redirect to xonotic.org instead of a relative addres due to it being used across different sub-domains.

New posts will therefore appear on localhost link /posts.

Hugo Pipes can be used to automate asset processing.

Scaling, styling, captioning, linking, WebP compression, fingerprinting (for cache busting), layout shift elimination and native lazy loading are implemented in layouts/_default/_markup/render-image.html. This uses CommonMark syntax extended with parsing of the "title" string. In the "title" string you can specify the fraction of page width that the inline image will be scaled to (full width if not specified), then a list of custom CSS classes ("th" if not specified), and then a caption string.

Examples:

![Amazing Horse](page_bundle_horse.png "0.69 || th left m10 || Look at my caption, my caption's amazing!")
![Amazing Horse](page_bundle_horse.png "0.69 || th left m10")
![Amazing Horse](page_bundle_horse.png "0.69")
![Amazing Horse](page_bundle_horse.png "|| th left m10 || Look at my caption, my caption's amazing!")
![Amazing Horse](page_bundle_horse.png "||||Terse! Caption only.")
![Amazing Horse](/static/m/uploads/2022/09/horse.png "|| th m10 || Static assets can't be scaled but can be styled and captioned.")

See also: content/guide/index.md

Always specify the width fraction of images placed inside page elements (such as tables) that are smaller than the source image.

When a scaled down image is generated (because the source image is larger than the page width multiplied by the specified fraction) it will automatically be made a link to the full size version.

These features are available when images are pushed as page resources or global resources.

Only a single full resolution, lossless file should be pushed for each image.
Compressed and scaled versions can be generated by Hugo without bloating the repo.
Processing of a lossy file can cause washed-out colours, as well as compression artifacts.
On Linux the file utility can be used to distinguish lossy and lossless WebP files. For a lossy file it will say VP8 encoding.

Don't convert JPG files to WebP, they tend to get bigger and/or look worse so configure Xonotic to save screenshots as PNG instead. If JPG must be used it must be pushed as a static asset.

Markdown is to be preferred over handwritten HTML even for static images as it allows Hugo to determine the dimensions and apply default styling automatically. You can use a markdown image as the "text" of a markdown link.

It should be assumed that *.webp *.svg *.png *.jpg *.jpeg *.gif *.ico *.woff2 *.woff *.js files will be cached by clients forever. Cache busting is automated for markdown images pushed as Resources (the published image URLs contain hashes) but must be done manually for static assets by updating the file or directory name when updating its content. There's a date hierarchy for this in static/m/uploads/.

It's possible (but not implemented here currently) to use shortcodes to enable asset processing for handwritten HTML.