Sync Merge: docs/inject_dynamic_content

content/pages/contribution-guide/dynamic-content/index.md

@@ -0,0 +1,146 @@
+---
+title: "Dynamic content"
+date: 2025-09-09
+tags: ["Contribute"]
+showTableOfContents: true
+showAuthor: false
+authors:
+  - "kirill-chalov"
+---
+
+For pages that change frequently, it is useful to bypass git and inject the updated content dynamically instead of creating PRs every time. As of now, this is helpful for hardware and software product support pages that can update weekly. This article will provide a workflow for injecting dynamic content focusing on the product support pages.
+
+
+## Plan your page
+
+First of all, the content on a product support page should be classified into the following types:
+
+- **Static**: Rarely changing content
+  - Committed to the git repo
+  - Stored under
+    `content/{hardware|software}/product-x/index.md`
+- **Dymanic**: Frequently changing content
+  - Dynamically injected into HTML pages using the [dynamic-block](https://github.com/espressif/developer-portal/blob/main/layouts/shortcodes/dynamic-block.html) shortcode
+  - Stored in the root of the web server under
+    `./persist/{hardware|software}/product-x/product-x.json`
+  - Updated either manually or using CI
+  - For uploading to the web server, talk to the project maintainers
+
+The dynamic content must be stored in the root of the web server under `persist`. All other folders are fully overwritten daily.
+
+
+## Arrange your content
+
+From the hints in [Plan your page](#plan-your-page), it is not hard to understand the idea:
+
+- In your markdown file where a dynamic part needs to be injected, you add a `dynamic-block` shortcode with part's `jsonKey`
+- In your JSON file, you add all dynamic parts in markdown
+
+### Simplified syntax
+
+As you can see from [Example files](#example-files) below, raw markdown lists (`feature_list`) and tables (`periph_support_table`) are not reasonable to store in JSON. A simplified syntax provides a way to strip unnecessary characters for storing, and add them back during rendering. This way, the JSON source is easier to read and `dynamic-block` still renders it correctly.
+
+To use simplified syntax, mark the `jsonKey` accordingly. In each case, the raw and simplified versions render identically:
+
+- **Simplified list** -- append `list_simple` to its `jsonKey`<br>
+  Output: `feature_list` = `feature_list_simple`
+- **Simplified table** -- append `table_simple` to its `jsonKey`<br>
+  Output: `periph_support_table` = `periph_support_table_simple`
+
+### Emojis
+
+In JSON, include emojis as Unicode characters ✅ instaed of `: white_check_mark :`. This considerably reduces the render time of injected content.
+
+### Example files
+
+Git repo: `content/software/product-x/index.md`
+```
+---
+title: "Product X"
+date: 2025-08-28
+---
+
+**Last updated:** {{</* dynamic-block contentPath="persist/software/product-x/product-x.json" jsonKey="timestamp" */>}}
+
+This is a product status page for Product X.
+
+The following features are supported as of now:
+
+{{</* dynamic-block contentPath="persist/software/product-x/product-x.json" jsonKey="feature_list_simple" */>}}
+
+## Peripheral support table
+
+{{</* dynamic-block contentPath="persist/software/product-x/product-x.json" jsonKey="periph_support_table_simple" */>}}
+```
+
+Web server: `persist/software/product-x/product-x.json`
+
+```json
+{
+  "timestamp": "2025-08-28T00:07:19.716630Z",
+  "feature_list": "- Supported SDKs\n  - ✅ [ESP-IDF](https://github.com/espressif/esp-idf/)\n  - ⏳ SDK 2",
+  "periph_support_table": "| Peripheral | ESP32 |\n| :--- | :---: |\n| UART | ✅ |\n| LCD | ❌ |",
+  "feature_list_simple": [
+    "- Supported SDKs",
+    "  - ✅ [ESP-IDF](https://github.com/espressif/esp-idf/)",
+    "  - ⏳ SDK 2"
+  ],
+  "periph_support_table_simple": [
+    "Peripheral,ESP32",
+    ":---,:---:",
+    "UART,✅",
+    "LCD,❌"
+  ]
+}
+```
+
+The final page with the dynamic content should look somewhat like this:
+
+---
+
+<span style="font-size:2em; font-weight:bold;">Product X</span>
+
+**Last updated:** 28 Aug 2025, 8:07 am
+
+This is a product status page for Product X.
+
+The following features are supported as of now:
+
+- Supported SDKs
+  - ✅ [ESP-IDF](https://github.com/espressif/esp-idf/)
+  - ⏳ SDK 2
+
+<span style="font-size:1.5em; font-weight:bold;">Peripheral support table</span>
+
+| Peripheral | ESP32 |
+| :--- | :---: |
+| UART | ✅ |
+| LCD | ❌ |
+
+---
+
+
+## Test dynamic content
+
+Test your `.json` file locally before uploading to the web server:
+
+- In your git repo, place your `.json` file at the same path as on the server:
+  ```sh
+  📂 content/software/
+  ├── 📝 _index.md
+  └── 📂 product-x/
+      ├── 📝 index.md
+      └── 🧩 persist/software/product-x/product-x.json # remove after testing
+  ```
+- In your git repo's `layouts/shortcodes/dynamic-block.html`, adjust the toggle for testing:
+  ```javascript
+  {{ $localMode := true }}  <!-- change to true for local -->
+  ```
+
+After you run `hugo server` locally, the JSON content should be injected dynamically on your page.
+
+**If you update JSON**, do this for the changes to show up:
+
+- Restart `hugo server`
+- Refresh your browser tab
+- If no effect: clear the page cache

content/pages/contribution-guide/writing-content/index.md

@@ -143,6 +143,12 @@ Please have your featured image converted to WebP as requested in [Use WebP for
 
 [blowfish-front-matter]: https://blowfish.page/docs/front-matter/
 
+### Inject dynamic content
+
+If your page is going to be updated frequently, consider implementing injection of dynamic content. Usually, it is used for product status pages, such as [ESP32-C61 status](../../../hardware/esp32c61 "ESP32-C61 status").
+
+For more information, see [Dynamic content](../dynamic-content "Dynamic content").
+
 ## Use additional content types
 
 Apart from the usual content types supported by markdown, such as visuals or code blocks, you can use other content types enabled by Hugo shortcodes. This section briefly introduces the most relevant shortcodes implemented on the Espressif Developer Portal.

layouts/shortcodes/dynamic-block.html

@@ -1,13 +1,94 @@
+{{/*
+Shortcode: dynamic-block
+------------------------
+
+This shortcode allows you to inject frequently changing content from a JSON file
+into your Hugo pages. It is designed for cases where some parts of a page (such as
+status, last update timestamps, or feature lists) need to be updated often without
+rebuilding the entire site.
+
+See also https://developer.espressif.com/pages/contribution-guide/dynamic-content/
+
+Usage example
+
+  {{< dynamic-block contentPath="persist/path-to/file.json" jsonKey="timestamp" >}}
+
+Arguments
+
+- contentPath (string)
+  Path to the JSON file relative to the site base URL (e.g. "persist/status.json").
+  In production, JSON must be served from https://developer.espressif.com/persist/...
+
+- jsonKey (string)
+  The key within the JSON object whose value will be injected into the page.
+  The content can be plain text, Markdown, or a special field.
+
+Special field handling
+
+- jsonKey = "timestamp"
+  If the key is `"timestamp"`, the shortcode expects an ISO8601 date/time string.
+  It is automatically converted into a localized, human-readable format:
+  `DD Mon YYYY, HH:MM AM/PM` (using the en-GB locale).
+
+- jsonKey containing "list_simple"
+  If the key name includes "list_simple", the shortcode expects an array of strings representing a Markdown list.
+  The array is automatically joined into a proper Markdown list before rendering.
+  Example:
+  {
+    "feature_list_simple": [
+      "- Supported SDKs",
+      "  - ✅ [ESP-IDF](https://github.com/espressif/esp-idf/)",
+      "  - ⏳ SDK 2"
+    ]
+  }
+
+- jsonKey containing "table_simple"
+  If the key name includes "table_simple", the shortcode expects an array of CSV-style strings representing table rows.
+  Each string is converted into a Markdown table row before rendering.
+  Example:
+  {
+    "periph_support_table_simple": [
+      "Peripheral,ESP32",
+      ":---,:---:",
+      "UART,✅",
+      "LCD,❌"
+    ]
+  }
+
+Other keys
+
+- Any other key is assumed to contain Markdown content.
+  The Markdown is rendered to HTML before being injected.
+
+Error handling
+
+If the JSON file cannot be fetched or the key is not found, the shortcode will display
+an error message instead of the content.
+*/}}
+
+{{/*
+Toggle for local testing: set to true to load JSON locally from contentPath
+(relative to your index.md location).
+Leave false (default) to resolve via .Site.BaseURL (web mode).
+*/}}
+{{ $localMode := true }}  <!-- change to true for local -->
+
+
 {{ $uniqueID := .Get "jsonKey" | urlize }} <!-- Generate a unique ID -->
 <span id="content-{{ $uniqueID }}">Loading...</span>
 
 {{ $contentPath := .Get "contentPath" }}
 {{ $jsonKey := .Get "jsonKey" }}
-{{ $fullURL := printf "%s%s" .Site.BaseURL $contentPath }}
+
+{{/* Only build $fullURL in web mode */}}
+{{ $fullURL := "" }}
+{{ if not $localMode }}
+  {{ $fullURL = printf "%s%s" .Site.BaseURL $contentPath }}
+{{ end }}
 
 <script>
   document.addEventListener("DOMContentLoaded", function () {
-    const url = '{{ $fullURL }}';
+    const url = '{{ if $localMode }}{{ $contentPath }}{{ else }}{{ $fullURL }}{{ end }}';
     const jsonKey = '{{ $jsonKey }}';
     const uniqueID = '{{ $uniqueID }}';
 
@@ -29,6 +110,15 @@
           const isoTime = data[jsonKey];
           const options = { day: 'numeric', month: 'short', year: 'numeric', hour: 'numeric', minute: '2-digit', hour12: true };
           content = new Intl.DateTimeFormat('en-GB', options).format(new Date(isoTime));
+        } else if (jsonKey.includes("list_simple")) {
+          // Join simplified array back into markdown list
+          let markdown = data[jsonKey].join("\n");
+          content = marked.parse(markdown);
+        } else if (jsonKey.includes("table_simple")) {
+          // Convert simplified array back into a markdown table
+          const rows = data[jsonKey].map(row => `| ${row.replace(/,/g, " | ")} |`);
+          const markdown = rows.join("\n");
+          content = marked.parse(markdown);
         } else {
           // Extract the value for the key and convert the markdown to HTML
           let markdown = data[jsonKey];