Agents learn from docs with technical excellence (#3458)

* Add text/markdown to the existing mediaTypes block, add a new outputFormats block, extend outputs to cover pages, and add two new deployment matchers.

* add a layout for creating markdown pages without front matter

* add layouts to generate llms.txt and llms-full.txt

* add uglyUrl to allow markdown pages to have the same url as the slug + .md

* remove uglyURL as it's doing nothing

* correctly name layout files

* rename and move all markdown files so they can be accessed via <slug>.md

Author: todah-zg

build.sh

@@ -7,3 +7,13 @@ cd "${0%/*}"
 rm -rf public/
 
 hugo --minify
+
+# Rename slug/index.md → slug.md to match the clean .md URL convention.
+# Only processes directories that also contain an index.html, so section
+# indexes and other non-page artifacts are left untouched.
+find public -mindepth 2 -name "index.md" | while IFS= read -r f; do
+  dir=$(dirname "$f")
+  if [ -f "$dir/index.html" ]; then
+    mv "$f" "$(dirname "$dir")/$(basename "$dir").md"
+  fi
+done

config.yaml

@@ -21,11 +21,32 @@ params:
 imaging:
     resampleFilter: linear
     quality: 90
+outputFormats:
+  MarkdownPage:
+    mediaType: text/markdown
+    baseName: index
+    isPlainText: true
+    notAlternative: true
+  LLMSTxt:
+    mediaType: text/plain
+    baseName: llms
+    isPlainText: true
+    notAlternative: true
+  LLMSFull:
+    mediaType: text/plain
+    baseName: llms-full
+    isPlainText: true
+    notAlternative: true
 outputs:
-    home:
-        - HTML
-        - RSS
-        - JSON
+  home:
+    - HTML
+    - RSS
+    - JSON
+    - LLMSTxt
+    - LLMSFull
+  page:
+    - HTML
+    - MarkdownPage
 buildDrafts: true
 defaultContentLanguage: en
 disable404: true
@@ -223,6 +244,9 @@ menu:
               hide: true
 
 mediaTypes:
+    text/markdown:
+        suffixes:
+            - md
     video/mp4:
         suffixes:
             - mp4
@@ -261,6 +285,12 @@ deployment:
         - pattern: '^.+\\.xml$'
           contentType: 'application/rss+xml; charset=utf-8'
           gzip: true
+        - pattern: '^.+\\.md$'
+          contentType: 'text/markdown; charset=utf-8'
+          gzip: true
+        - pattern: '^llms.*\\.txt$'
+          contentType: 'text/plain; charset=utf-8'
+          gzip: true
 
 markup:
     goldmark:

layouts/404.markdownpage.md

@@ -0,0 +1 @@
+# 404 - Page Not Found

layouts/_default/index.llmsfull.txt

@@ -0,0 +1,16 @@
+{{- range .Site.RegularPages }}
+================================================================================
+source: {{ .Permalink }}
+title: {{ .Title }}
+{{ with .Params.description -}}
+description: {{ . }}
+{{ end -}}
+last_modified: {{ .Lastmod.Format "2006-01-02" }}
+================================================================================
+
+# {{ .Title }}
+{{ with .Params.description }}
+> {{ . }}
+{{ end }}
+{{ .RawContent }}
+{{ end -}}

layouts/_default/index.llmstxt.txt

@@ -0,0 +1,21 @@
+# Codemagic Docs
+
+> Codemagic is a CI/CD platform for building, testing, signing, and publishing
+> Android, iOS, Flutter, and React Native mobile apps. Pipelines are configured
+> via a codemagic.yaml file committed to your repository.
+>
+> In addition to CI/CD, Codemagic offers CodePush: a separate Over-the-Air (OTA)
+> update service specifically for React Native. CodePush allows developers to deploy
+> instant JavaScript and asset updates directly to users, bypassing the standard app
+> store review process for non-native changes.
+
+## Optional
+
+- [Complete documentation]({{ absURL "llms-full.txt" }}): Every documentation page concatenated into a single file for full-context retrieval
+
+## Documentation
+{{ range .Site.RegularPages.GroupBy "Section" }}
+### {{ .Key }}
+{{ range .Pages }}
+- [{{ .Title }}]({{ .Permalink | strings.TrimSuffix "/" }}.md){{ with .Params.description }}: {{ . }}{{ end }}
+{{ end }}{{ end }}

layouts/_default/single.markdownpage.md

@@ -0,0 +1,9 @@
+{{- $lastmod := .Lastmod.Format "2006-01-02" -}}
+<!-- source: {{ .Permalink }} -->
+<!-- last modified: {{ $lastmod }} -->
+
+# {{ .Title }}
+{{ with .Params.description }}
+> {{ . }}
+{{ end }}
+{{ .RawContent -}}