From 9b421450b10d86f348a24cffe55ba67830d33203 Mon Sep 17 00:00:00 2001 From: black-sliver <59490463+black-sliver@users.noreply.github.com> Date: Wed, 28 Jan 2026 19:57:12 +0000 Subject: [PATCH] Doc: WebHost: update readme and style guide (#4853) * Doc: WebHost living standard * Docs: update style guide for HTML, CSS and JS * Unblame phar * Too many words * The better choice * More rules * Removed too much * Docs: add recommendations for script defer and async --- WebHostLib/README.md | 54 ++++++++++++-------------------------------- docs/style.md | 20 ++++++++++------ 2 files changed, 27 insertions(+), 47 deletions(-) diff --git a/WebHostLib/README.md b/WebHostLib/README.md index 52d4963aee..cc19be1fb9 100644 --- a/WebHostLib/README.md +++ b/WebHostLib/README.md @@ -1,46 +1,20 @@ # WebHost +## Asset License + +The image files used in the page design were specifically designed for archipelago.gg and are **not** covered by the top +level LICENSE. +See individual LICENSE files in `./static/static/**`. + +You are only allowed to use them for personal use, testing and development. +If the site is reachable over the internet, have a robots.txt in place (see `ASSET_RIGHTS` in `config.yaml`) +and do not promote it publicly. Alternatively replace or remove the assets. + ## Contribution Guidelines -**Thank you for your interest in contributing to the Archipelago website!** -Much of the content on the website is generated automatically, but there are some things -that need a personal touch. For those things, we rely on contributions from both the core -team and the community. The current primary maintainer of the website is Farrak Kilhn. -He may be found on Discord as `Farrak Kilhn#0418`, or on GitHub as `LegendaryLinux`. -### Small Changes -Little changes like adding a button or a couple new select elements are perfectly fine. -Tweaks to style specific to a PR's content are also probably not a problem. For example, if -you build a new page which needs two side by side tables, and you need to write a CSS file -specific to your page, that is perfectly reasonable. +Pages should preferably be rendered on the server side with Jinja. Features should work with noscript if feasible. +Design changes have to fit the overall design. -### Content Additions -Once you develop a new feature or add new content the website, make a pull request. It will -be reviewed by the community and there will probably be some discussion around it. Depending -on the size of the feature, and if new styles are required, there may be an additional step -before the PR is accepted wherein Farrak works with the designer to implement styles. +Introduction of JS dependencies should first be discussed on Discord or in a draft PR. -### Restrictions on Style Changes -A professional designer is paid to develop the styles and assets for the Archipelago website. -In an effort to maintain a consistent look and feel, pull requests which *exclusively* -change site styles are rejected. Please note this applies to code which changes the overall -look and feel of the site, not to small tweaks to CSS for your custom page. The intention -behind these restrictions is to maintain a curated feel for the design of the site. If -any PR affects the overall feel of the site but includes additive changes, there will -likely be a conversation about how to implement those changes without compromising the -curated site style. It is therefore worth noting there are a couple files which, if -changed in your pull request, will cause it to draw additional scrutiny. - -These closely guarded files are: -- `globalStyles.css` -- `islandFooter.css` -- `landing.css` -- `markdown.css` -- `tooltip.css` - -### Site Themes -There are several themes available for game pages. It is possible to request a new theme in -the `#art-and-design` channel on Discord. Because themes are created by the designer, they -are not free, and take some time to create. Farrak works closely with the designer to implement -these themes, and pays for the assets out of pocket. Therefore, only a couple themes per year -are added. If a proposed theme seems like a cool idea and the community likes it, there is a -good chance it will become a reality. +See also [docs/style.md](/docs/style.md) for the style guide. diff --git a/docs/style.md b/docs/style.md index e38be9d649..e4eeadeacf 100644 --- a/docs/style.md +++ b/docs/style.md @@ -47,21 +47,27 @@ ## HTML -* Indent with 2 spaces for new code. +* Indent with 4 spaces for new code. * kebab-case for ids and classes. +* Avoid using on* attributes (onclick, etc.). -## CSS +## CSS / SCSS -* Indent with 2 spaces for new code. +* Indent with 4 spaces for new code. * `{` on the same line as the selector. -* No space between selector and `{`. +* Space between selector and `{`. ## JS -* Indent with 2 spaces. -* Indent `case` inside `switch ` with 2 spaces. -* Use single quotes. +* Indent with 4 spaces. +* Indent `case` inside `switch ` with 4 spaces. +* Prefer double quotation marks (`"`). * Semicolons are required after every statement. +* Use [IIFEs](https://developer.mozilla.org/docs/Glossary/IIFE) to avoid polluting global scope. +* Prefer to use [defer](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/script#defer) + in script tags, which retains order of execution but does not block. +* Avoid `