Merge pull request #1226 from python-discord/docs/suggest-resources

Document how to add new resources

2 files changed, 36 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.
diff --git a/pydis_site/templates/resources/resources.html b/pydis_site/templates/resources/resources.html
index a4fa551e..c7fe2e89 100644
--- a/pydis_site/templates/resources/resources.html
+++ b/pydis_site/templates/resources/resources.html
@@ -156,6 +156,9 @@
                         {% endfor %}
                     </nav>
                 </div>
+                <div class="content has-text-grey is-hidden-mobile">
+                    <p>Want to suggest more resources? <a href="https://github.com/python-discord/meta/issues/new?assignees=&labels=area%3A+resources&projects=&template=resource-request.yaml">Open an issue on GitHub</a>.</p>
+                </div>
             </div>
 
             <div class="column is-two-thirds">
@@ -174,6 +177,9 @@
                         {% endfor %}
                     </div>
                 </div>
+                <div class="content has-text-grey is-hidden-tablet">
+                    <p>Want to suggest more resources? <a href="https://github.com/python-discord/meta/issues/new?assignees=&labels=area%3A+resources&projects=&template=resource-request.yaml">Open an issue on GitHub</a>.</p>
+                </div>
             </div>
         </div>
     </section>