Markdown output: render family page from front matter, serve at /<product>.md

Add layouts/index.md to render the family landing page's front matter (platforms, versions, install, capabilities, formats, resources) as real Markdown instead of dumping front matter. Publish the family .md at the bucket root as /<product>.md (deploy_product.yml + build-local.sh). Defensively strip a leading front-matter block in md/abs-content.txt for empty-body pages (CRLF-tolerant).

Author: vladimir-litvinchik

.github/workflows/deploy_product.yml

@@ -55,6 +55,25 @@ jobs:
           chmod +x ./move_md_to_ugly_urls.sh
           ./move_md_to_ugly_urls.sh public
 
+      - name: Publish family Markdown to bucket root as <product>.md
+        # The product build's home is the family landing page; serve its .md at
+        # /<product>.md (bucket root) instead of /<product>/index.md. Skipped for the
+        # `home` build, whose root index.md is the site landing page.
+        if: inputs.product_family != 'home'
+        run: |
+          BUCKET=${{ inputs.environment == 'production' && 'reference.groupdocs.com' || 'reference2.groupdocs.com' }}
+          aws s3 cp public/index.md "s3://$BUCKET/${{ inputs.product_family }}.md" \
+            --content-type "text/markdown; charset=utf-8" --region us-west-2
+        env:
+          AWS_ACCESS_KEY_ID: ${{ secrets.ACCESS_KEY }}
+          AWS_SECRET_ACCESS_KEY: ${{ secrets.SECRET_ACCESS }}
+
+      - name: Drop the prefixed family Markdown (served at /<product>.md instead)
+        # Removing it locally makes `hugo deploy --maxDeletes` delete the old
+        # /<product>/index.md from S3, so the family .md exists only at the root.
+        if: inputs.product_family != 'home'
+        run: rm -f public/index.md
+
       - name: Deploy to S3
         run: hugo --configDir config/sites/groupdocs/${{ inputs.product_family }} --environment ${{ inputs.environment }} deploy --target "${{ inputs.environment == 'production' && 'Production' || 'Stage' }}" --maxDeletes ${{ inputs.max_deletes }}
         env:
@@ -65,7 +84,7 @@ jobs:
         uses: chetan/invalidate-cloudfront-action@v2
         env:
           DISTRIBUTION: ${{ inputs.environment == 'production' && secrets.AWS_DISTRIBUTION_PROD || secrets.AWS_DISTRIBUTION }}
-          PATHS: ${{ inputs.invalidate_paths != '' && inputs.invalidate_paths || format('/{0}/*', inputs.product_family) }}
+          PATHS: ${{ inputs.invalidate_paths != '' && inputs.invalidate_paths || format('/{0}/* /{0}.md', inputs.product_family) }}
           AWS_REGION: 'us-west-2'
           AWS_ACCESS_KEY_ID: ${{ secrets.ACCESS_KEY }}
           AWS_SECRET_ACCESS_KEY: ${{ secrets.SECRET_ACCESS }}

README.md

@@ -56,7 +56,11 @@ consumption. Configured per product in `config/sites/groupdocs/<product>/_defaul
 The `.md` files are post-processed so they're clean and portable:
 
 1. **No front matter, real Markdown** — `single.md` / `list.md` emit `.RawContent` (Hugo strips
-   the YAML front matter), via the partial `layouts/partials/md/abs-content.txt`.
+   the YAML front matter), via the partial `layouts/partials/md/abs-content.txt`. The product
+   **family landing page** stores its content in front matter (platforms, capabilities, formats,
+   resources) with an empty body, so `layouts/index.md` renders that data as Markdown instead
+   (matching `family.html`). Its `.md` is published at the bucket root as **`/<product>.md`**
+   (not `/<product>/index.md`) by `deploy_product.yml`.
 2. **Absolute links** — links are made absolute so they work no matter where the `.md` is served:
    - `abs-content.txt` (in-template) absolutizes **root-relative** links (`/path/` → `BASE/path.md`).
    - [`resolve_md_links.py`](resolve_md_links.py) (post-build) absolutizes **relative** links

build-local.sh

@@ -31,6 +31,12 @@ for p in "${PRODUCTS[@]}"; do
        -b "http://localhost:$PORT/$p/" -d "$PWD/$OUT/$p" --cleanDestinationDir --minify
   python resolve_md_links.py "$OUT/$p" --base-url "http://localhost:$PORT/$p" >/dev/null
   bash move_md_to_ugly_urls.sh "$OUT/$p" >/dev/null
+  # Family page .md is served at /<product>.md (bucket root), not /<product>/index.md —
+  # mirror that locally (production does this via deploy_product.yml).
+  if [ -f "$OUT/$p/index.md" ]; then
+    cp "$OUT/$p/index.md" "$OUT/$p.md"
+    rm -f "$OUT/$p/index.md"
+  fi
 done
 
 echo

themes/docs/layouts/index.md

@@ -0,0 +1,53 @@
+{{- /* Home-page Markdown output.
+       Product builds: the home IS the product family landing (layout: family) whose content
+       lives entirely in front matter — render that data as real Markdown (mirrors family.html
+       and products/ layouts/partials/md/layout-family.txt) so the .md is useful instead of a
+       front-matter dump. Otherwise (site-root landing, layout: full-width) fall back to the
+       generic body, identical to _default/list.md. */ -}}
+{{- if eq .Layout "family" -}}
+# {{ .Title }}
+{{ with (or .Params.lead .Description) }}
+{{ . }}
+{{ end }}
+{{- with .Params.platforms }}
+## Choose your platform
+{{ range . }}
+### {{ .name }}{{ with .version }} — v{{ . }}{{ end }}
+{{ with .install }}
+```
+{{ . }}
+```
+{{ end }}
+{{- $u := .ref | strings.TrimPrefix "/" | absURL | strings.TrimRight "/" -}}
+[Browse API reference]({{ $u }}.md)
+{{ end }}
+{{ end -}}
+{{- with .Params.capabilities }}
+## Key capabilities
+{{ range . }}
+- {{ . }}
+{{- end }}
+{{ end -}}
+{{- with .Params.formats }}
+## Supported formats
+{{ delimit . ", " }}
+{{ end -}}
+{{- with .Params.resources }}
+## Resources
+{{ range . }}
+- [{{ .name }}]({{ .url }})
+{{- end }}
+{{ end -}}
+{{- else -}}
+# {{ partial "utils/title" . }}
+{{ with .Description }}
+{{ . }}
+{{ end }}
+{{ partial "md/abs-content.txt" . }}
+{{ if and (not .Params.hideChildren) (.Pages) }}
+## Contents
+{{ range .Pages.ByWeight }}
+- [{{ partial "utils/title" . }}]({{ strings.TrimRight "/" .Permalink }}.md)
+{{- end }}
+{{ end }}
+{{- end -}}

themes/docs/layouts/partials/md/abs-content.txt

@@ -4,6 +4,11 @@
        links are left untouched. Single-language site, so BaseURL is sufficient. */ -}}
 {{- $base := strings.TrimRight "/" .Site.BaseURL -}}
 {{- $c := .RawContent -}}
+{{- /* 0. defensively strip a leading YAML front-matter block: for pages with an EMPTY body
+       (e.g. an auto-generated namespace _index.md that is front matter only), Hugo's
+       .RawContent can contain the front matter. The inner-line guard ([A-Za-z]) avoids
+       matching a leading `---` horizontal rule (which is followed by a blank line). */ -}}
+{{- $c = replaceRE `(?s)\A---\r?\n[A-Za-z].*?\r?\n---\r?\n?` "" $c -}}
 {{- /* 1. markdown PAGE links ](/path/) -> ](BASE/path.md) */ -}}
 {{- $c = replaceRE `\]\((/[^)]*?)/\)` (printf "](%s${1}.md)" $base) $c -}}
 {{- /* 2. remaining markdown root-relative links (assets) ](/...) -> ](BASE/...) */ -}}