==============
Chat directory
==============

The chat directory is static. It is read once, during website startup, and is
currently baked into the container at build time.

Format
======

``chats.toml`` describes the chat directory as a set of `regions` that contain
`chats`. Regions and chats have this structure, where ``Region`` is replaced
with the name of the region:

.. code-block:: toml

    [Region]
    heading = 'expanded region name for headers (optional)'
    emoji = 'an emoji for the table of contents (optional)'
    text = 'message underneath header; HTML is allowed (optional)'

    [[Region.chat]]
    name = 'name of the chatroom'
    minage = 0 # minimum age of members (optional)
    image = 'filename in the `static/chats/` directory'
    link = 'invite link'
    members = 0 # approximate count of members (optional; empty -> sorted last)
    text = 'description; HTML is allowed'
    lang = 'IETF language tag (optional; default `en`)'
    website = 'dedicated website URL (optional)'
    localsonly = false # true or false (optional; default false)

There can be any number of regions, and any number of chats in those regions,
so long as each region is defined.

Display
=======

While chat directory entries can have both invite links and websites, the focus
is on furries joining chatrooms to find community, so the invite link is more
prominent. Clicking on the chat name will bring them to the invite link.
The website is displayed as a clickable badge next to the chat name, along with
(if set) its minimum age, language (if not English), and locals-only warning.

Regions are listed in ``chats.toml`` order. Chats within each region are sorted
first by member count descending, then by name ascending. Emoji and 'short'
region names are used to generate links for the table of contents.

To keep page load times reasonable as the chat directory expands, please shrink
large images, such as Telegram-sourced images (640x640), down to 160x160:

.. code-block:: sh

    cd sewifurs/website/static/chats/
    magick mogrify -resize 160x160 *.jpg

Link checker
============

Independent of :mod:`sewifurs.website` serving the chat directory,
:mod:`sewifurs.linkchecker` reads ``chats.toml`` and periodically makes web
requests to defined invite links and websites for each chat.

On startup and every eight hours after, it will check the validity of all
chat directory links and will send a message in the `ADMIN_CHAT_ID` chat if
a broken link is found, as well as log the details to the console.