From 3a1883253d6cf083573fd271dfddcdc65ba5828a Mon Sep 17 00:00:00 2001 From: "kirill.chalov" Date: Wed, 23 Apr 2025 12:08:02 +0800 Subject: [PATCH 1/2] feat: add check for summary and update contribution guide --- ...shing-dates.yml => pr-article-details.yml} | 48 +++++++++++-- archetypes/blog.md | 15 ++++ assets/css/custom.css | 9 ++- .../writing-content/index.md | 68 +++++++++++-------- 4 files changed, 102 insertions(+), 38 deletions(-) rename .github/workflows/{pr-publishing-dates.yml => pr-article-details.yml} (58%) create mode 100644 archetypes/blog.md diff --git a/.github/workflows/pr-publishing-dates.yml b/.github/workflows/pr-article-details.yml similarity index 58% rename from .github/workflows/pr-publishing-dates.yml rename to .github/workflows/pr-article-details.yml index c9b80ea07..bc3d9c413 100644 --- a/.github/workflows/pr-publishing-dates.yml +++ b/.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,7 +83,6 @@ jobs: if: always() run: | error_found=0 - today=$(date +%Y-%m-%d) while IFS= read -r mdfile; do @@ -91,13 +90,48 @@ jobs: 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 diff --git a/archetypes/blog.md b/archetypes/blog.md new file mode 100644 index 000000000..1c47c8391 --- /dev/null +++ b/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//_index.md` +# - Add your personal data at `data/authors/.json` +# - Add your author name(s) below +authors: + - "author-name" +# Add tags +tags: ["Tag1", "Tag2"] +--- diff --git a/assets/css/custom.css b/assets/css/custom.css index 4fb1b0bc4..e4b81db94 100644 --- a/assets/css/custom.css +++ b/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; } diff --git a/content/pages/contribution-guide/writing-content/index.md b/content/pages/contribution-guide/writing-content/index.md index c97c4bfe2..940b2b03d 100644 --- a/content/pages/contribution-guide/writing-content/index.md +++ b/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//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 /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//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 /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//_index.md`, create your page - - At `data/authors/.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: - - "" # 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. From b656c4a678996bc27cfc0f40d4b7979163fc33d9 Mon Sep 17 00:00:00 2001 From: "kirill.chalov" Date: Wed, 23 Apr 2025 15:58:10 +0800 Subject: [PATCH 2/2] ci: update triggering logic for link checking --- .github/workflows/pr-check-links-caller.yml | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/.github/workflows/pr-check-links-caller.yml b/.github/workflows/pr-check-links-caller.yml index c4e5623d8..815b4cca0 100644 --- a/.github/workflows/pr-check-links-caller.yml +++ b/.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: