{{- /* recommended.html (shortcode): Renders a list of posts with `recommended = true`. Target: _index.md Example: {{< recommended TITLE="" LIMIT="" >}} Params: - TITLE (string, optional): H2 heading. - LIMIT (integer, optional): Number of items to show (Default: 4). Error handler: - warnf - OCD Repo: https://github.com/oxypteros/alpha */ -}} {{- /* Case-insensitive parameter retrieval (default chaining) */}} {{- $title := .Get "TITLE" | default (.Get "Title") | default (.Get "title") }} {{- $limit := .Get "LIMIT" | default (.Get "Limit") | default (.Get "limit") }} {{- /* Context for error reporting (warnf, OCD) */}} {{- $page := .Page.RelPermalink }} {{- /* OCD: Validate params manually against an allowlist. */}} {{- $allowedKeys := slice "title" "limit" }} {{- $invalidKeys := slice }} {{- /* Validate limit value */}} {{- $isNumber := (printf "%v" $limit | findRE "^[1-9][0-9]*$") }} {{- $intNumber := 4 }} {{- $warnNumber := false }} {{- if $isNumber }} {{- $intNumber = (index $isNumber 0 | int) }} {{- else if $limit }} {{- $warnNumber = true }} {{- end }} {{- /* Invalid Parameter Error Handling (OCD) */}} {{- range $key, $value := .Params }} {{- if not (in $allowedKeys (lower $key)) }} {{- $invalidKeys = $invalidKeys | append $key }} {{- end }} {{- end }} {{- if gt (len $invalidKeys) 0 }} {{- /* Warnf for error: ocd-sc-181 */}} {{- $errorCode := "ocd-sc-181" }} {{- $invalidKeysString := delimit $invalidKeys ", " }} {{- $errorMessage := printf "Invalid parameters: %s" $invalidKeysString }} {{- $logMessage := printf "OcdError [%s] Page: %s | %s" $errorCode $page $errorMessage }} {{- warnf "%s" $logMessage }} {{- /* OCD error card for: odc-sc-181 */}} {{- if and (eq hugo.Environment "development") (hugo.IsServer) (eq .Page.Site.Params.ocd_enabled true) }}
{{- i18n "OcdScParamError" . | default "Shortcode Parameter Error" }}

{{- $count := len $invalidKeys }} {{- i18n "OcdScNumList181" $count | default "Invalid parameter in the recommended shortcode on this page:" }} {{ .Page.Title }}

{{- i18n "OcdScParameter" $count | default "The parameters," }}  {{ $invalidKeysString }}  {{ i18n "OcdScNotRecognized" $count | default "are not recognized." }}


{{ i18n "OcdScAcceptedParameters" . | default "Accepted parameters:" }} TITLE, LIMIT

{{- end }} {{- end }} {{- /* Wrong Limit Value Error Handling (warnf, OCD) */}} {{- if $warnNumber }} {{- /* Warnf for error: ocd-sc-182 */}} {{- $errorCode := "ocd-sc-182" }} {{- $errorMessage := printf "The value of the LIMIT parameter is not an integer: %s." $limit }} {{- $logMessage := printf "OcdError [%s] - Page: %s | %s" $errorCode $page $errorMessage }} {{- warnf "%s" $logMessage }} {{- /* OCD error card for: odc-sc-182 */}} {{- if and (eq hugo.Environment "development") (hugo.IsServer) (eq .Page.Site.Params.ocd_enabled true) }}
{{- i18n "OcdScValueError" . | default "Shortcode Value Error" }}

{{- i18n "OcdScRecommended182" . | default "Invalid parameter value for the recommended shortcode on:" }} {{ .Page.Title }}

{{- i18n "OcdScThe" . | default "The" }}  LIMIT  {{- i18n "OcdScParameterValue" . | default "parameter value" }}  {{ $limit }}  {{ i18n "OcdScIsInvalid" . | default "is invalid." }}


{{- i18n "OcdSc" . | default "" }} LIMIT {{ i18n "OcdSc" . | default "must be an integer." }}

{{- end }} {{- end }} {{- /* The pages marked as recommended */}} {{- $recommendedPages := where site.RegularPages "Params.recommended" true }} {{- /* Number of random pages to pick */}} {{- $numPages := $intNumber }} {{- /* Get a sample, but don’t exceed the $numPages */}} {{- $sampleSize := math.Min (len $recommendedPages) $numPages }} {{- /* Respect the limit */}} {{- $actualPages := first $sampleSize ($recommendedPages) }} {{- if gt (len $actualPages) 0 }}
{{- /* Optional title rendering. */}} {{- with $title }}

{{- $title -}}

{{- end }}
{{- range $actualPages }} {{- /* Find the first letter of the title */}} {{- $titleAccent := substr .Title 0 1 }} {{- /* Display only the first category term of the taxonomy */}} {{- $category := "" -}} {{- with .GetTerms "categories" -}} {{- if ge (len .) 1 -}} {{- $category = (index . 0).LinkTitle -}} {{- end -}} {{- end -}} {{- /* Display 'new' badge only if `date` < 7 days from last build */}} {{- $new := gt .Date (now.AddDate 0 0 -7) }}
{{- if $new }} {{- $date := .Date | time.Format "2006-01-02T15:04:05-07:00" }}
{{- end }}

{{ .Title }}

{{- if or .Page.Params.series $category }}
{{ with .Page.Params.series }} {{ . }} {{- end }}
{{- with $category }} {{ . }} {{- end }}
{{- else }} {{- /* Maintain the card layout if no series/category */}}
{{- end }}
{{- end }}
{{- else }} {{- /* Warnf for error: ocd-sc-183 */}} {{- $errorCode := "ocd-sc-183" }} {{- $errorMessage := printf "No page is marked as recommended" }} {{- $logMessage := printf "OcdError [%s] - Page: %s | %s" $errorCode $page $errorMessage }} {{- warnf "%s" $logMessage }} {{- /* OCD error card for: odc-sc-183 */}} {{- if and (eq hugo.Environment "development") (hugo.IsServer) (eq .Page.Site.Params.ocd_enabled true) }}
{{- i18n "OcdScContentError" . | default "Shortcode Content Error" }}

{{- i18n "OcdScRecommended183" . | default "No page is marked as recommended, the shortcode recommended is disabled" }}


Add to the frontmatter of at least one page: recommended = true

{{- end }} {{- end }}