Resources: Add guidelines on YAML files

1 files changed, 30 insertions, 5 deletions

diff --git a/pydis_site/apps/resources/README.md b/pydis_site/apps/resources/README.md
index 6f41319a..e8229d3b 100644
--- a/pydis_site/apps/resources/README.md
+++ b/pydis_site/apps/resources/README.md
@@ -3,13 +3,38 @@
 This Django application powering the resources list [on our
 website](https://www.pythondiscord.com/resources/).
 
-## Directory structure
-
 The main point of interest here lies in the `resources` directory: every
 `.yaml` file in here represents a resource that is listed on our website. If
-you are looking for the place to suggest new resources, said directory is the
-place to create a new YAML file. In regards to the required keys and our
-values, it's best to check the other files we have for a reference.
+you are looking for the place to add new resources, said directory is the
+place to create a new YAML file.
+
+In regards to the required keys and our values, it's best to check the other
+files we have for a reference.
+
+Here are some general guidelines:
+
+- The `description` text can include HTML elements, such as a simple bullet-list
+  to further describe the resource item. Markdown is not yet supported.
+
+- If branding icons (like Goodreads or GitHub through the `icon` field under
+  `urls`) are included, set `color: dark` rather than `color: black` to ensure it
+  displays correctly in dark mode.
+
+- For books, please include a link to the Goodreads URL under `urls`.
+
+- If a logo is included, use `icon_image` rather than `title_image` to have the
+  logo display together next to the title (rather than replacing it). Unless
+  the logo includes the name of the resources that is clearly visible.
+
+- All images used must be readable in both light and dark modes. If an image does
+  not suit both themes simultaneously, please include image URLs for each mode
+  separately using the optional `*_dark` keys:
+  - `icon_image`, `icon_image_dark`
+  - `title_image`, `title_image_dark`
+  - `title_icon`, `title_icon_dark`
+
+
+## Directory structure
 
 The app has a single view in `views.py` that takes care of reading the `.yaml`
 file. This is a standard Django view, mounted in `urls.py` as usual.