add hugo document

2024-05-23 20:41:41 -06:00
parent 59d27dffcb
commit cd2a000781
1 changed files with 254 additions and 0 deletions
--- a/tech_docs/webdev/hugo.md
+++ b/tech_docs/webdev/hugo.md
@@ -0,0 +1,254 @@
+Integrating HTMX into your Hugo project can enhance the interactivity of your site without requiring a full-fledged JavaScript framework. HTMX allows you to make your static site more dynamic by enabling AJAX, CSS Transitions, WebSockets, and Server Sent Events (SSE) directly in HTML. This can be particularly useful for enhancing user experience without the complexity of traditional JavaScript frameworks.
+
+### When to Use HTMX
+
+HTMX is useful for:
+- **Enhancing Interactivity:** Adding dynamic features like in-place content updates, form submissions, and interactive elements without a full JavaScript framework.
+- **AJAX Requests:** Making asynchronous requests to the server to update parts of your page without reloading.
+- **Progressive Enhancement:** Gradually enhancing your static site with more interactive features.
+
+### Integrating HTMX into Hugo
+
+Here's how you can integrate HTMX into your Hugo site, especially for data visualization and client reports.
+
+### Step-by-Step Integration
+
+#### 1. Install Hugo and Create a New Site
+
+If you haven't already, install Hugo and create a new site:
+
+```sh
+hugo new site smma-telemetry
+cd smma-telemetry
+```
+
+#### 2. Initialize Git and Add a Bootstrap Theme
+
+```sh
+git init
+git submodule add https://github.com/razonyang/hugo-theme-bootstrap themes/hugo-theme-bootstrap
+```
+
+Update your `config.toml` to use the theme:
+
+```toml
+baseURL = 'https://example.org/'
+languageCode = 'en-us'
+title = 'SMMA Telemetry'
+theme = 'hugo-theme-bootstrap'
+```
+
+#### 3. Set Up Project Structure
+
+```sh
+mkdir -p content/clients
+mkdir -p data/clients
+mkdir -p static/css
+mkdir -p static/js
+```
+
+#### 4. Add HTMX to Your Project
+
+Add HTMX via a CDN in your base layout file.
+
+**layouts/_default/baseof.html:**
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>{{ .Title }}</title>
+    <meta name="description" content="{{ .Description }}">
+    <link rel="stylesheet" href="https://stackpath.bootstrapcdn.com/bootstrap/4.5.2/css/bootstrap.min.css">
+    <link rel="stylesheet" href="{{ "css/styles.css" | relURL }}">
+    <script src="https://unpkg.com/htmx.org@1.5.0"></script>
+</head>
+<body>
+    <nav class="navbar navbar-expand-lg navbar-light bg-light">
+        <a class="navbar-brand" href="{{ "/" | relURL }}">{{ .Site.Title }}</a>
+        <button class="navbar-toggler" type="button" data-toggle="collapse" data-target="#navbarNav" aria-controls="navbarNav" aria-expanded="false" aria-label="Toggle navigation">
+            <span class="navbar-toggler-icon"></span>
+        </button>
+        <div class="collapse navbar-collapse" id="navbarNav">
+            <ul class="navbar-nav">
+                <li class="nav-item">
+                    <a class="nav-link" href="{{ "/" | relURL }}">Home</a>
+                </li>
+                <li class="nav-item">
+                    <a class="nav-link" href="{{ "/clients/" | relURL }}">Clients</a>
+                </li>
+            </ul>
+        </div>
+    </nav>
+    <main class="container mt-4">
+        {{ block "main" . }}{{ end }}
+    </main>
+    <footer class="footer bg-light text-center py-3">
+        <p>&copy; {{ now.Format "2006" }} {{ .Site.Title }}</p>
+    </footer>
+    <script src="https://code.jquery.com/jquery-3.5.1.slim.min.js"></script>
+    <script src="https://cdn.jsdelivr.net/npm/@popperjs/core@2.9.2/dist/umd/popper.min.js"></script>
+    <script src="https://stackpath.bootstrapcdn.com/bootstrap/4.5.2/js/bootstrap.min.js"></script>
+    <script src="https://cdn.jsdelivr.net/npm/chart.js"></script>
+    <script src="{{ "js/scripts.js" | relURL }}"></script>
+</body>
+</html>
+```
+
+#### 5. Create Data Files
+
+Store ads telemetry data for each client in JSON format. For example:
+
+**data/clients/client1.json:**
+
+```json
+{
+  "name": "Client 1",
+  "ads_data": [
+    { "date": "2024-05-01", "google_ads": 500, "meta_ads": 300 },
+    { "date": "2024-05-02", "google_ads": 700, "meta_ads": 400 },
+    { "date": "2024-05-03", "google_ads": 600, "meta_ads": 350 }
+  ]
+}
+```
+
+#### 6. Create Content Files
+
+Create a content file for each client. For example:
+
+**content/clients/client1.md:**
+
+```markdown
+---
+title: "Client 1"
+date: 2024-05-23
+---
+
+# Client 1 Ads Telemetry
+
+<div class="card mb-3">
+  <div class="card-body">
+    <h5 class="card-title">Ads Data Visualization</h5>
+    <canvas id="adsChart" width="400" height="200"></canvas>
+  </div>
+</div>
+
+<button hx-get="/clients/client1-data" hx-target="#adsChart" hx-trigger="load">Load Data</button>
+
+<script>
+  document.addEventListener('DOMContentLoaded', function () {
+    const data = {{ .Site.Data.clients.client1.ads_data | jsonify }};
+    const ctx = document.getElementById('adsChart').getContext('2d');
+    const labels = data.map(item => item.date);
+    const googleAds = data.map(item => item.google_ads);
+    const metaAds = data.map(item => item.meta_ads);
+    new Chart(ctx, {
+      type: 'line',
+      data: {
+        labels: labels,
+        datasets: [
+          {
+            label: 'Google Ads',
+            data: googleAds,
+            borderColor: 'rgba(75, 192, 192, 1)',
+            backgroundColor: 'rgba(75, 192, 192, 0.2)',
+            fill: false
+          },
+          {
+            label: 'Meta Ads',
+            data: metaAds,
+            borderColor: 'rgba(153, 102, 255, 1)',
+            backgroundColor: 'rgba(153, 102, 255, 0.2)',
+            fill: false
+          }
+        ]
+      },
+      options: {
+        scales: {
+          y: {
+            beginAtZero: true
+          }
+        }
+      }
+    });
+  });
+</script>
+```
+
+#### 7. Add Custom JavaScript and CSS
+
+**static/js/scripts.js:**
+
+```js
+document.addEventListener('DOMContentLoaded', function () {
+    console.log('Custom JS Loaded');
+});
+```
+
+**static/css/styles.css:**
+
+```css
+body {
+    font-family: Arial, sans-serif;
+    line-height: 1.6;
+    margin: 0;
+    padding: 0;
+    background: #f4f4f4;
+}
+
+#adsChart {
+    max-width: 600px;
+    margin: 50px auto;
+}
+```
+
+#### 8. Create a Server-side Endpoint
+
+To handle HTMX requests, create a server-side script (e.g., in Python or another language of your choice) to serve the data dynamically.
+
+**Example Python Flask Endpoint (app.py):**
+
+```python
+from flask import Flask, jsonify
+import json
+
+app = Flask(__name__)
+
+@app.route('/clients/client1-data')
+def client1_data():
+    with open('data/clients/client1.json') as f:
+        data = json.load(f)
+    return jsonify(data['ads_data'])
+
+if __name__ == '__main__':
+    app.run(debug=True)
+```
+
+#### 9. Run the Hugo Server
+
+```sh
+hugo server -D
+```
+
+Visit `http://localhost:1313` to see your site in action.
+
+### Summary
+
+**Tech Stack:**
+- **Hugo**: For building and deploying your static site.
+- **Markdown**: For writing content and reports.
+- **Bootstrap**: For responsive design and consistent styling.
+- **Chart.js**: For creating interactive data visualizations.
+- **HTMX**: For enhancing interactivity with minimal JavaScript.
+- **Python/Flask**: For server-side data processing and handling HTMX requests.
+
+**Implementation:**
+- Set up Hugo and configure your project structure.
+- Create data files and content files for each client.
+- Use Bootstrap for styling and Chart.js for visualizations.
+- Enhance interactivity with HTMX for dynamic data loading.
+- Use Python/Flask for server-side data handling.
+
+This approach ensures you have a robust, scalable, and interactive solution for SMMA data reporting, leveraging your data analysis skills while keeping the setup and maintenance straightforward. If you have further questions or need more detailed guidance, feel free to ask!