docs: manage scripts and styles (#717)

docs/develop-project.md

@@ -4,12 +4,17 @@ Read [Django CMS User Guide] for CMS user instructions.
 
 ## Table of Contents
 
+- [Add Styles & Scripts](#add-styles--scripts)
 - [Build Static Files](#build-static-files)
 - [Collect Static Files](#collect-static-files)
 - [Customize Admin UI Text](#customize-admin-ui-text)
 - [Demo UI Patterns](#demo-ui-patterns)
 - [Develop with Core Styles Simultaneously](#develop-with-core-styles-simultaneously)
 
+## Add Styles & Scripts
+
+To add styles or scripts, first read [Styles and Scripts].
+
 ## Build Static Files
 
 All CSS static files are built:
@@ -103,3 +108,5 @@ See [Locally Develop CMS and Styles](https://github.com/TACC/Core-CMS/wiki/Local
 [restart server]: https://github.com/TACC/Core-CMS/wiki/How-to-Restart-the-CMS-Server
 
 [Django CMS User Guide]: https://confluence.tacc.utexas.edu/x/FgDqCw
+
+[Styles and Scripts]: ./styles-and-scripts.md

docs/styles-and-scripts.md

@@ -0,0 +1,165 @@
+# Styles & Scripts
+
+## Table of Contents
+
+- [For **All** Pages](#for-all-pages)
+- [For **Multiple** Pages](#for-multiple-pages)
+- [For **One** Page](#for-one-page)
+
+### For All Pages
+
+1. Create asset (if not a remote asset):
+
+    | of this type | in this directory |
+    | - | - |
+    | stylesheet | `taccsite_cms/static/site_cms/css/src/` |
+    | script | `taccsite_cms/static/site_cms/js/modules/` |
+
+2. Load asset:
+
+    | of this type | in this file |
+    | - | - |
+    | stylesheet | `taccsite_cms/static/site_cms/css/src/core-cms.css` |
+    | script | `taccsite_cms/templates/assets_core_delayed.html` |
+
+### For Multiple Pages
+
+1. Create asset:
+
+    | of this type | in this directory |
+    | - | - |
+    | stylesheet | `taccsite_cms/static/site_cms/css/src/` |
+    | script | `taccsite_cms/static/site_cms/js/modules/` |
+
+2. Load asset:
+
+    - either **before** content
+
+      ```django
+      {% block assets_custom %}
+        {{ block.super }}
+        <!-- ... -->
+      {% endblock assets_custom %}
+      ```
+
+      <details><summary>for entire <strong>site</strong></summary>
+
+      ```django
+        <link rel="stylesheet" href="{% static '__PROJECT__/css/build/site.css' %}">
+        <script src="{% static '__PROJECT__/js/site.js' %}"></script>
+      ```
+
+      </details>
+
+      <details><summary>for one <strong>template</strong></summary>
+
+      ```django
+        <link rel="stylesheet" href="{% static '__PROJECT__/css/build/template.___.css' %}">
+        <script src="{% static '__PROJECT__/js/template.___.js' %}"></script>
+      ```
+
+      </details>
+
+      <details><summary>for one <strong>page</strong></summary>
+
+      > **Warning**
+      > Undesired. Create re-usable code (see [CMS UI Organization]).
+
+      </details>
+
+    - or **after** content
+
+      ```django
+      {% block assets_custom_delayed %}
+        {{ block.super }}
+        <!-- ... -->
+      {% endblock assets_custom_delayed %}
+      ```
+
+      <details><summary>for entire <strong>site</strong></summary>
+
+      ```django
+        <link rel="stylesheet" href="{% static '__PROJECT__/css/build/site.css' %}">
+        <script src="{% static '__PROJECT__/js/site.js' %}"></script>
+      ```
+
+      </details>
+
+      <details><summary>for one <strong>template</strong></summary>
+
+      ```django
+        <link rel="stylesheet" href="{% static '__PROJECT__/css/build/template.___.css' %}">
+        <script src="{% static '__PROJECT__/js/template.___.js' %}"></script>
+      ```
+
+      </details>
+
+      <details><summary>for one <strong>page</strong></summary>
+
+      > **Warning**
+      > Undesired. Create re-usable code. See [CMS UI Organization].
+
+      </details>
+
+### For One Page
+
+> **Warning**
+> Undesired. Create re-usable code. See [CMS UI Organization].
+
+- [For Markup Outside The Template](#for-markup-outside-the-template)
+- [For Markup Inside The Template](#for-markup-inside-the-template)
+
+#### For Markup Outside The Template
+
+##### Styles
+
+```django
+{% block css %}
+  {{ block.super }}
+  <style>
+  /* ... */
+  </style>
+{% endblock css %}
+```
+
+> **Note**
+> Loads **before** all markup.
+
+##### Script
+
+```django
+{% block js %}
+  {{ block.super }}
+  <script type="module">
+  /* ... */
+  </script>
+{% endblock js %}
+```
+
+> **Note**
+> Loads **after** all markup.
+
+
+#### For Markup Inside The Template
+
+##### Styles
+
+```html
+<style>
+/* ... */
+</style>
+```
+
+##### Script
+
+```html
+<script type="module">
+/* ... */
+</script>
+```
+
+<!-- Link Aliases -->
+
+[Core Styles]: https://github.com/TACC/Core-Styles
+
+[CMS UI Organization]: https://confluence.tacc.utexas.edu/x/54AZCg "CMS UI - Organization"