feat: add check for summary and update contribution guide (#475)

* feat: add check for summary and update contribution guide

* ci: update triggering logic for link checking

Author: f-hollow

.github/workflows/pr-publishing-dates.yml .github/workflows/pr-article-details.yml.github/workflows/pr-publishing-dates.yml renamed to .github/workflows/pr-article-details.yml

@@ -1,4 +1,4 @@
-name: Check publishing dates
+name: Check article details
 
 on:
   pull_request:
@@ -12,7 +12,7 @@ env:
   TARGET_BRANCH: "main"
 
 jobs:
-  check-publishing-dates:
+  check-article-details:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout PR contents
@@ -66,13 +66,13 @@ jobs:
           CURRENT_MONTH=$(date +%m)
 
           if [[ -s temp/no-yyyy-mm.txt ]]; then
-            echo "Move your article folder(s) to 'content/blog/${CURRENT_YEAR}/${CURRENT_MONTH}/':"
+            echo "❌ Wrong folder. Move your article folder(s) to 'content/blog/${CURRENT_YEAR}/${CURRENT_MONTH}/':"
             cat temp/no-yyyy-mm.txt
             error_found=1
           fi
 
           if [[ -s temp/incorrect-yyyy-mm.txt ]]; then
-            echo "Move your article folder(s) to 'content/blog/${CURRENT_YEAR}/${CURRENT_MONTH}/':"
+            echo "❌ Wrong folder. Move your article folder(s) to 'content/blog/${CURRENT_YEAR}/${CURRENT_MONTH}/':"
             cat temp/incorrect-yyyy-mm.txt
             error_found=1
           fi
@@ -83,21 +83,55 @@ jobs:
         if: always()
         run: |
           error_found=0
-
           today=$(date +%Y-%m-%d)
 
           while IFS= read -r mdfile; do
             if [[ -f "$mdfile" ]]; then
               post_date=$(awk '/^date:/ {gsub(/["'\''"]/,"",$2); print $2}' "$mdfile")
 
               if [[ ! "$post_date" =~ ^[0-9]{4}-[0-9]{2}-[0-9]{2}$ ]]; then
-                echo "In '$mdfile' YAML header, make sure the date is in YYYY-MM-DD format."
+                echo "❌ In '$mdfile': Invalid date format. Use YYYY-MM-DD."
                 error_found=1
               elif [[ "$post_date" < "$today" ]]; then
-                echo "Once your article in '$mdfile' is approved, make sure the date in its YAML header is not in the past (found: $post_date, today: $today)."
+                echo "❌ In '$mdfile': Date is in the past. Update the publishing date after the article is approved (found: $post_date, today: $today)."
                 error_found=1
+              else
+                echo "✅ In '$mdfile': Date format is valid and not in the past."
               fi
             fi
           done < temp/index.txt
 
           exit $error_found
+
+      - name: Check summaries in index.md files
+        if: always()
+        run: |
+          if [ -f temp/index.txt ]; then
+            missing_summary=false
+            placeholder_summary=false
+
+            while IFS= read -r file; do
+              # Extract YAML header from the file
+              header=$(awk '/^---$/ {flag=flag+1; next} flag==1' "$file" | awk '/^---$/ {exit} {print}')
+              summary_line=$(echo "$header" | grep '^summary:' || true)
+
+              if [ -z "$summary_line" ]; then
+                echo "❌ Missing summary in $file. Add the summary."
+                missing_summary=true
+              else
+                summary_value=$(echo "$summary_line" | cut -d':' -f2- | xargs)
+                if [[ "$summary_value" == Replace\ it\ with* ]]; then
+                  echo "❌ Placeholder summary found in $file. Update the summary."
+                  placeholder_summary=true
+                else
+                  echo "✅ Summary OK in $file"
+                fi
+              fi
+            done < temp/index.txt
+
+            if [ "$missing_summary" = true ] || [ "$placeholder_summary" = true ]; then
+              exit 1
+            fi
+          else
+            echo "✅ No new index.md files to check"
+          fi

.github/workflows/pr-check-links-caller.yml

@@ -2,7 +2,11 @@ name: Check links in diffs
 
 on:
   pull_request:
-    branches: [main]
+    branches:
+      - main
+    paths:
+      - 'content/**'
+      - 'README.md'
 
 jobs:
   check-links:

archetypes/blog.md

@@ -0,0 +1,15 @@
+---
+title: "{{ replace .Name "-" " " | title }}"
+date: "{{ now.Format "2006-01-02" }}"
+showAuthor: false
+# Add a summary
+summary: "Replace it with a brief summary that capture the essence of (1) what the article is about and (2) how the reader will benefit from reading it. For examples, check other article summaries."
+# Create your author entry
+#  - Create your page at `content/authors/<author-name>/_index.md`
+#  - Add your personal data at `data/authors/<author-name>.json`
+#  - Add your author name(s) below
+authors:
+  - "author-name"
+# Add tags
+tags: ["Tag1", "Tag2"]
+---

assets/css/custom.css

@@ -8,7 +8,7 @@
   font-size: 0.85rem;
 }
 
-/* This reduces font in article summaries */
+/* This reduces font in article card summaries */
 .py-1 {
   font-size: 0.85rem;
   font-weight: 400;
@@ -20,8 +20,11 @@
   line-height: 1.65;
 }
 
+/* This sets the style for article summaries */
 .article-summary {
+  font-weight: 700;
   font-style: italic;
-  padding-left: 10px;
-  border-left: 4px solid #e7352c;
+  padding-left: 1em;
+  border-left: 0.25rem solid #e7352c;
+  margin-top: 1.6em;
 }

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

@@ -20,45 +20,57 @@ There are the following prerequisites before you start writing content:
 
 ### Create and view an article
 
-See also the official [docs](https://gohugo.io/getting-started/quick-start/#add-content).
+To create a new article, determine the path and run
 
-- To create a new article, determine the path and run
-  ```sh
-  # Blog article
-  hugo new content blog/YYYY/MM/<article-folder-name>/index.md
-  # Blog article example
-  hugo new content blog/2025/04/ulp-lp-core-get-started/index.md
-  # Non-blog articles (workshops, events etc.)
-  hugo new content <path>/index.md
-  ```
-  This assumes that you want to organize the content as a leaf bundle (a single article). For multi-article entries (workshops, etc.), use the [branch bundle](https://gohugo.io/content-management/page-bundles/#comparison).
-- To view the changes, in your project folder run
+```sh
+# Blog article
+# (if specified folders don't exist, they will be created)
+hugo new content blog/YYYY/MM/<article-folder-name>/index.md
+# Blog article example
+hugo new content blog/2025/04/ulp-lp-core-get-started/index.md
+# Non-blog articles (workshops, events etc.)
+hugo new content <path>/index.md
+```
+
+See also the official Hugo [docs](https://gohugo.io/getting-started/quick-start/#add-content).
+
+The commands above assume that you want to organize the content as a leaf bundle (a single article). For multi-article entries (workshops, etc.), use the [branch bundle](https://gohugo.io/content-management/page-bundles/#comparison).
+
+To view the changes, in your project folder run
   ```sh
   hugo server
   ```
 
-### Add youself as an author
+### Fill out the blog article header
 
-The default Espressif author is used:
+After creating a blog article using `hugo new content blog/...`, go to your article file `index.md` and fill out its YAML header according to the instructions in comments.
 
-- If the author prefers to stay anonymous
-- For posts generated by scripts, such as automatic compilations, release notes, and so on
-- For articles generated with AI
+One of the YAML header parameters is _summary_ --- the article summary that appears just below the article title ([summary example](../../../blog/2025/04/soft-ap-tutorial/ "under-title summary example")) and also in the article card ([card example](../../../blog/ "card summary example")) where articles are listed. On how to write the article summary, check the additional guidelines below.
 
-In other cases, add yourself as an author. For this, do the following:
+#### Write an article summary
 
-- Create your author entry
-  - At `content/authors/<author-name>/_index.md`, create your page
-  - At `data/authors/<author-name>.json`, add your personal data
+Before you begin writing your article, it is a good exercise to summarize in one paragraph:
 
-- Add the following to your article's YAML header
+1. The **main topic** of your article (1 or 2 sentences).
+2. What **value** it brings to the reader (1 or 2 sentences).
 
-  ```yaml
-  showAuthor: false         # Hide default Espressif author
-  authors:
-    - "<author-name>"        # List your name(s)
-  ```
+{{< alert icon="eye" >}}
+Don't include links in summaries as they are not supported by design. Also, avoid formatting text as it doesn't look good in general.
+{{< /alert >}}
+
+This exercise might help you better understand how to structure and write your content. It will also help readers decide if they want to read your article as well as to set expectations.
+
+After you finish writing, revisit your summary to see if it needs any adjustments. You might be surprised by how the focus of your writing can shift during the process without you realizing it.
+
+#### Add youself as an author
+
+The default Espressif author is used:
+
+- If the author prefers to stay anonymous
+- For posts generated by scripts, such as automatic compilations, release notes, and so on
+- For articles generated with AI
 
+In other cases, add yourself as an author. For this, follow the instructions in the article's YAML header.
 
 ## Write the content
 
@@ -197,7 +209,7 @@ Some explanations:
 
 For a real example, see this [page](../../../blog/build-embedded-swift-application-for-esp32c6/#building-an-example-project).
 
-As you can see, the `tabs` shortcode has **the parameter** `groupId`. It creates association between all tabbed code blocks bearing the same `groupId` on a webpage. Once you choose a certain tab, all associated code blocks will switch to the same tab. It can be useful in tutorials covering multiple operating systems, programming lanugages, etc.
+As you can see, the `tabs` shortcode has **the parameter** `groupId`. It creates association between all tabbed code blocks bearing the same `groupId` on a webpage. Once you choose a certain tab, all associated code blocks will switch to the same tab. It can be useful in tutorials covering multiple operating systems, programming languages, etc.
 
 You can also easily **indent a tabbed code block**, by preceding the `tabs` and `tab` shortcodes with the required number of spaces. This is exactly what was [done][indented-tabbed-code-block] in the linked example above.