DEV Community: Sumeet Naik

Serve Markdown to AI Agents from Hugo on Cloudflare Pages (Free Plan)

Sumeet Naik — Sun, 09 Aug 2026 05:45:54 +0000

AI agents, LLM crawlers, and CLI tools don't want your HTML. They want the content, i.e. the headings, lists and links without the nav bars, the theme toggles, and the 40 KB of markup around it. The polite way to give it to them is content negotiation: when a client sends Accept: text/markdown, hand back Markdown; otherwise, serve HTML like normal.

The catch: content negotiation branches on a request header, and a static host can't do that. A _headers file on Cloudflare Pages only sets response headers by path — it can't look at what the client asked for. So for years the answer was "use a real server."

Cloudflare offers a path here, too: a toMarkdown conversion utility on Workers AI that turns documents into Markdown on demand. It's a fine tool, but a different job — it converts arbitrary files at request time (and image conversions can dip into Workers AI billing), and it means adding a Workers AI binding as a dependency. For serving your own site's pages, you don't need it.

You don't need any of that. This post shows how to do it on Hugo + Cloudflare Pages, entirely on the free plan, with:

Hugo emitting a .md twin of every page at build time, and
One small Cloudflare Pages Function that swaps HTML for Markdown when — and only when — a client asks for it.

The end result:

$ curl -sD- -H 'Accept: text/markdown' https://sumeetnaik.com/blog/
HTTP/2 200
content-type: text/markdown; charset=utf-8
vary: accept
x-markdown-tokens: 32

# Blog

- [Serve Markdown to AI Agents ...](/blog/markdown-for-ai-agents-hugo-cloudflare-pages/) — 2026-07-14
...

A browser hitting the same URL gets HTML, untouched.

The shape of the solution

Two pieces, and they're independent:

Build time (Hugo): generate index.md next to every index.html. Static files, cached at the edge like anything else.
Request time (Pages Function): a tiny middleware that reads Accept, and if the client wants Markdown, serves the pre-built .md instead.

Because the Markdown is pre-rendered, the function does almost no work — it just picks which file to return. That keeps it fast and well within the free tier's limits.

Step 1 — Make Hugo emit Markdown for every page

Hugo's output formats let one page render to multiple files. Define a MARKDOWN format and turn it on for every page kind in your site config (hugo.toml):

[outputs]
  home    = ["HTML", "RSS", "MARKDOWN"]
  section = ["HTML", "MARKDOWN"]
  page    = ["HTML", "MARKDOWN"]

[outputFormats.MARKDOWN]
  mediaType   = "text/markdown"  # -> ".md" suffix
  baseName    = "index"          # -> <path>/index.md, beside index.html
  isPlainText = true             # don't run it through the HTML escaper
  notAlternative = true          # keep it out of <link rel=alternate> discovery

baseName = "index" is the important bit: it drops index.md right next to each index.html, so /blog/my-post/ gets a sibling /blog/my-post/index.md. Easy to map to later.

Step 2 — Write the Markdown templates

Output formats need templates. Hugo picks a template by name + format, so a template ending in .markdown.md only ever renders the MARKDOWN format and won't collide with your HTML layouts. You need three generic ones.

A single page — layouts/_default/single.markdown.md. .RawContent is the original Markdown source of the page, minus front matter — exactly what an agent wants:

# {{ .Title }}
{{ with .Date }}{{ if not .IsZero }}
_{{ .Format "January 2, 2006" }}_
{{ end }}{{ end }}
{{ .RawContent }}

A section list — layouts/_default/list.markdown.md:

# {{ .Title }}
{{ with .RawContent }}
{{ . }}{{ end }}
{{ range .Pages }}- [{{ .Title }}]({{ .RelPermalink }}){{ with .Date }}{{ if not .IsZero }} — {{ .Format "2006-01-02" }}{{ end }}{{ end }}
{{ end }}

The home page — layouts/index.markdown.md. Home pages are usually bespoke, so build it from your site params / menus rather than .RawContent:

# {{ .Site.Params.name }}

{{ .Site.Params.intro }}

## Pages
{{ range .Site.Menus.main }}
- [{{ .Name }}]({{ .URL }}){{ end }}

Run hugo and you'll see index.md files appear throughout public/. That's the generic case done.

The gotcha: pages that live in front matter

Here's the trap almost every Hugo site hits. Many "pages" store their content in front matter, not in the Markdown body — a /uses page with a groups: list, a /resume with jobs:, a /now with sections:. For those, .RawContent is empty, and the generic template above gives you a lonely # Title with nothing under it.

The fix is one Markdown template per custom layout, mirroring what the HTML template does — just emitting Markdown instead of <div>s. If your resume page renders from a jobs array in the HTML layout, add layouts/_default/resume.markdown.md:

# {{ .Title }}

{{ .Params.sub }}

## Experience
{{ range .Params.jobs }}
### {{ .title }}

_{{ .dateRange }}_ — {{ .meta }}

{{ range .points }}- {{ . }}
{{ end }}{{ end }}

Same idea for a uses page (delimit, nested range) or a now page. Whatever structured data your HTML layout reads, your Markdown layout reads the same fields. Hugo resolves <layout>.markdown.md automatically for any page whose front matter sets layout: "resume" (etc.).

Rule of thumb: for every custom HTML layout you have, check whether the content is in the body or the front matter. Body content → the generic single.markdown.md covers you. Front-matter content → write a matching *.markdown.md.

Step 3 — The Cloudflare Pages Function

Now the negotiation. Drop a single file at functions/_middleware.js in your repo root — Cloudflare Pages auto-detects the functions/ directory, no config, no wrangler.toml, no dependencies. _middleware.js runs on every request.

export async function onRequest(context) {
  const { request, next } = context;

  const accepts = request.headers.get("Accept") || "";
  // Require markdown to be explicitly acceptable — a bare `*/*` keeps HTML.
  if (!/text\/markdown/i.test(accepts)) {
    return next();
  }

  const url = new URL(request.url);
  const path = url.pathname;

  let mdPath;
  if (path.endsWith("/")) {
    mdPath = path + "index.md";
  } else if (!/\.[a-z0-9]+$/i.test(path)) {
    mdPath = path + "/index.md";        // extensionless page URL
  } else {
    return next();                      // real file (css, rss.xml, ...) — leave it
  }

  const mdUrl = new URL(url);
  mdUrl.pathname = mdPath;

  // Fetch the static .md that Hugo built for this page.
  const res = await next(new Request(mdUrl, request));

  // If there's no .md for this path, fall back to HTML. A missing asset can be a
  // 404 (production) OR the root index.html served with status 200 (wrangler
  // dev), so reject anything that isn't actually markdown — don't trust status.
  const type = res.headers.get("content-type") || "";
  if (!res.ok || /html/i.test(type)) {
    return next();
  }

  const body = await res.text();
  const headers = new Headers(res.headers);
  headers.set("Content-Type", "text/markdown; charset=utf-8");
  headers.set("Vary", "Accept");
  headers.delete("Content-Length");                 // let the runtime recompute
  headers.set("x-markdown-tokens", String(Math.ceil(body.length / 4)));

  return new Response(body, { status: 200, headers });
}

A few things worth calling out:

context.next(request) is the key trick. Called with no argument it continues the pipeline for the current URL; called with a Request for a different URL, it fetches that static asset instead. That's how we grab index.md without a second network hop. It does not re-enter the middleware, so there's no infinite loop.
We require text/markdown literally. A browser sends Accept: text/html,...,*/*;q=0.8, which doesn't match, so browsers are never affected. Agents opt in explicitly.
x-markdown-tokens is a courtesy header. There's no tokenizer at the edge, so chars / 4 is the standard rough estimate for English — good enough for a client to decide whether to fetch.

The bug you'll hit if you skip the content-type check

When the .md doesn't exist, you'd expect a clean 404. But wrangler pages dev serves the root index.html with status 200 as a fallback — so a naïve if (!res.ok) check passes, and you happily wrap HTML in a text/markdown content-type. I hit exactly this while testing a bogus URL. Checking that the fetched asset's content-type isn't HTML fixes it for both dev and production. Don't trust the status code alone.

Step 4 — Tell caches the response varies

One header keeps CDNs honest. Add Vary: Accept so a cache never serves the Markdown variant to a browser (or vice-versa). The function already sets it on Markdown responses; add it site-wide for the HTML side via static/_headers:

/*
  Vary: Accept

Test it locally

Build, then run Cloudflare's own dev server against the output with the function wired in:

hugo
npx wrangler pages dev public --port 8788

Then exercise both paths:

# Markdown for agents
curl -sD- -H 'Accept: text/markdown' http://localhost:8788/blog/ | head

# HTML for everyone else — unchanged
curl -sD- http://localhost:8788/blog/ | head

# Real files are left alone
curl -sD- -H 'Accept: text/markdown' http://localhost:8788/rss.xml | head

Check: Content-Type: text/markdown, an x-markdown-tokens header, and a Markdown body on the first; plain HTML on the second; and your feed untouched on the third. A non-existent URL should fall back to HTML, not a Markdown-labelled 404.

Why this stays free

Nothing here touches a paid feature:

Hugo's extra output is just more static files.
Pages Functions are included on the free plan (a generous daily request allowance), and this one does trivial work — read a header, fetch a pre-built file, set three headers.
No KV, no D1, no Workers paid tier, no build plugins.

Wrapping up

Three moving parts — an output format, a handful of *.markdown.md templates, and ~30 lines of middleware — and every page on your site now speaks Markdown to anything that asks for it, while humans keep getting the full experience. It pairs nicely with an agents.md and Link: rel="describedby" headers if you want to go further in making your site legible to machines.

The two things I'd remember if you're adapting this to your own theme: write a Markdown template for every front-matter-driven layout, and guard on the fetched content-type, not the status code. Everything else is mechanical.

I Built an AI Pipeline That Writes My Tech Posts While I Code

Sumeet Naik — Fri, 29 May 2026 07:53:58 +0000

This is a submission for the Hermes Agent Challenge

What I Built

Hermes Content Pipeline: a daily dev-to-social content workflow that turns your actual development work into LinkedIn, Twitter, and blog drafts, delivered to Telegram for review.

The problem: as a developer with a full-time job, I was doing meaningful work every day but never publishing about it. The friction wasn't the writing, it was the capture. By the time I sat down to draft a post, I'd forgotten the trade-offs I'd weighed, the bugs I'd worked around, and the decisions that shaped the work.

The pipeline solves this in three steps:

Auto-capture during work: A Hermes skill (content-capture) automatically logs trade-off decisions, bugs (as principles, not raw debugging), and task completions to a sidecar notes file as you work. No interruption, no extra input needed.
"Draft posts for today's tasks": A Python script parses the session database and sidecar notes into a structured prompt, then a skill calls the LLM to generate three drafts: a ~300 word LinkedIn post, a Twitter thread (or single tweet, contextually chosen), and a substantive blog post.
Review and refine from mobile: All three drafts land on Telegram. Reply with "make linkedin shorter" or "focus on the auth bug in twitter" and the refinement skill re-generates only the affected draft.

The key insight: the best dev content comes from real work, not from staring at a blank page. This pipeline eliminates the blank page by deriving posts from what you already did.

Demo

Here's the pipeline in action, a real session where I built the project itself:

Input: Sidecar notes from a work session:

// trade: Sidecar file over DB column — keeps notes portable — needs manual cleanup
// trade: Minimal approach over fully integrated — simpler, no cron complexity
// bug: Telegram Markdown parsing rejects some characters — built fallback to plain text
// note: Built content-capture skill that auto-logs trade-offs during sessions
// note: Built draft_posts.py pipeline — reads state.db + notes, calls LLM, generates drafts

Output (LinkedIn draft, 140 words after refinement):

Every developer has a graveyard of half-formed ideas — debugging discoveries, architecture trade-offs, patterns that took hours to find.

I've been building content capture into our tooling, and the biggest lesson: capture is everything.

We use a simple sidecar file for logging insights. Manual cleanup required. No cron jobs. No automation.

And that simplicity is the feature.

The minimal approach — agent-driven markers, a flat file, simple pipeline — has been more useful than any elaborate setup I've attempted.

Do you have systems to capture lessons from your dev sessions, or does most of it stay trapped in your head?

Refinement in action: Started at ~300 words, refined down to 140 with "make linkedin more concise, under 150 words"

Code

Repository: github.com/sumeetweb/hermes-content-pipeline

├── skills/
│   ├── content-capture/SKILL.md       # Auto-logging during sessions
│   ├── content-generator/SKILL.md     # LLM-driven draft generation
│   └── refine-posts/SKILL.md          # Natural language refinement
├── scripts/
│   ├── parse_drafts.py                # Session parsing + prompt building
│   └── telebot_send.py                # Telegram delivery
├── tests/                             # Unit tests
└── run.sh                             # Venv-aware runner

My Tech Stack

Hermes Agent: session logging (SQLite state.db), skill system, Telegram gateway
Python stdlib: SQLite3, json, pathlib, urllib (Telegram Bot API)
OpenAI SDK: LLM calls using whatever model Hermes is configured with (minimax-m2.7 via Ollama Cloud in my setup)
Hermes Skill Framework: YAML frontmatter + markdown for the auto-logging skill

How I Used Hermes Agent

This project leans on four Hermes Agent capabilities that no other agent framework provides as cleanly:

1. Session Database (state.db)

Hermes stores every conversation in a local SQLite database with full message history. The parse_drafts.py script queries this directly, no API, no export step, no manual copy-paste. The session transcript IS the source of truth. This is what makes "derive posts from real work" possible without any extra effort from the user.

2. Skill System for Zero-Friction Capture

The content-capture skill uses Hermes' skill framework (YAML frontmatter + markdown body) to instruct the agent to automatically log // trade:, // bug:, // note: markers to a sidecar file. The agent recognizes significant moments during the session and logs them silently. The user never has to stop what they're doing.

3. Model-Agnostic LLM Config

The skill layer reads model and provider settings directly from ~/.hermes/config.yaml and ~/.hermes/.env. It inherits whatever model the user is already running. I'm using minimax-m2.7 via Ollama Cloud, but someone else could be on Claude, GPT-4o, or DeepSeek and it would just work.

4. Telegram Gateway Integration

Hermes' Telegram gateway config and channel directory (channel_directory.json) means the pipeline can discover the bot token and home chat ID automatically. No environment variable setup, no manual configuration. The drafts arrives to the user directly on their phone.

Why Hermes was the right fit: Other agent frameworks would require building the session logging, skill system, and messaging integration from scratch. Hermes provides all three out of the box, and the content pipeline simply connects them. The project is ~600 lines of Python + 2 skills connecting existing Hermes infrastructure, not ~3000 lines reinventing it.

Team Dashboard - Manage Your Team Efficiently with KendoReact

Sumeet Naik — Sun, 28 Sep 2025 20:11:27 +0000

This is a submission for the KendoReact Free Components Challenge.

What I Built

Team Dashboard is an enterprise-grade team performance dashboard that revolutionizes how managers track productivity, attendance, and KPIs across distributed teams. Built with React and powered by KendoReact's professional UI components, this application transforms complex performance data into actionable insights.

🎯 Problems Solved:

Data Accessibility Challenge: Traditional performance management often involves scattered spreadsheets, complex reports, and time-consuming data gathering. Team Dashboard centralizes all employee metrics in an intuitive, searchable interface.

Historical Analysis Bottleneck: Managers typically struggle to access past performance data quickly. Our AI-powered natural language query system allows instant access to historical insights with simple conversational queries like "Show me Q2 results for developers in Bangalore".

Team Management Complexity: Managing large teams requires efficient CRUD operations for employee data. The dashboard provides professional-grade employee management with inline editing, bulk operations, and smart filtering.

Visual Analytics Gap: Raw performance data is difficult to interpret. TeamPulse Pro includes interactive charts and trend analysis that transform numbers into visual stories managers can act upon.

🏢 Target Users:

Engineering Managers tracking developer productivity and code quality metrics
HR Directors monitoring employee satisfaction and retention indicators
Department Heads analyzing team performance across multiple locations
C-Suite Executives requiring high-level performance overviews with drill-down capabilities

🎥 Video Walkthrough

🚀 Live Application

Demo URL: Click Here
Repository: https://github.com/NishikantaRay/KendoReact-Free-Components-Challenge

📸 Screenshots & Features

Main Dashboard Interface

Employee data grid with real-time search, sorting, and filtering capabilities

AI-Powered Query Assistant

Natural language query interface powered by Nuclia RAG technology

Performance Analytics

Interactive performance trends and KPI visualizations

Employee Management Dialog

Professional forms for employee data management with validation

KendoReact Components Used

We successfully integrated 12 free KendoReact components throughout the application:

Core Data Components:

Grid - The centerpiece employee data grid with sorting, filtering, and pagination
GridColumn - Individual column definitions with custom rendering
GridToolbar - Action toolbar for grid operations

User Interface Components:

Button - Used extensively across all dialogs and action bars
Input - Text input fields for search and form data entry
Switch - Toggle controls for dark mode and compact view settings

Form & Selection Components:

DatePicker - Date selection for employee hire dates
DropDownList - Team and role selection dropdowns with filtering capabilities

Modal & Navigation Components:

Dialog - Modal windows for employee add/edit operations
DialogActionsBar - Standardized button containers for dialog actions

Feedback Components:

Notification - Individual notification messages for user feedback
NotificationGroup - Container managing multiple notification instances

AI Coding Assistant Usage

We extensively leveraged AI coding assistance throughout the development process, which significantly accelerated my workflow:

Component Architecture & Setup

Rapid Scaffolding: Used AI to generate initial component structures and establish proper KendoReact imports
Best Practices Implementation: AI helped ensure proper component organization and React hooks usage
Configuration Assistance: Streamlined the setup of complex grid configurations and chart integrations

Code Generation & Optimization

CRUD Operations: AI accelerated the development of create, read, update, and delete functionality for employee management
State Management: Helped implement efficient React state patterns for handling employee data and UI states
Event Handling: Generated robust event handlers for grid operations, form submissions, and user interactions

Styling & Responsiveness

CSS Integration: AI assisted in properly integrating KendoReact themes with custom styling
Responsive Design: Helped create layouts that work seamlessly across desktop and mobile devices
Theme Consistency: Ensured consistent styling patterns throughout all components

Debugging & Problem Solving

Error Resolution: AI provided solutions for component integration challenges
Performance Optimization: Suggested improvements for grid rendering and data handling
Cross-browser Compatibility: Helped identify and resolve potential browser-specific issues

Natural Language Query System:

We integrated Nuclia's AI capabilities directly into the dashboard sidebar, creating an intelligent assistant that allows managers to query historical performance data using conversational language.

Some Sample Queries Supported:

"Show me Q2 results for developers in Bangalore"
"What was the average performance score last month?"
"Which team has the highest productivity?"
"How many employees joined in 2024?"

Thank you for considering our submission for the KendoReact Free Components Challenge!

Team Members:

TravelMate AI: Real-Time AI Travel Planner Powered by Redis Stack

Sumeet Naik — Sat, 09 Aug 2025 21:47:59 +0000

This is a submission for the Redis AI Challenge: Real-Time AI Innovators.

What I Built

TravelMate AI is an intelligent travel planning application that demonstrates Redis capabilities beyond traditional caching. The application leverages semantic caching, vector search, and real-time features to provide instant, personalized travel recommendations and itinerary planning.

Demo

GitHub Repository: https://github.com/sumeetweb/TravelMate-Redis-AI

Live Demo Video: https://www.youtube.com/watch?v=cReF-pLsH-g

Screenshots

Homepage:

Without Redis Cache:

With Redis Cache:

Day-wise Itinerary Info:

Itinerary Info Map View:

How I Used Redis 8

TravelMate AI showcases Redis as a comprehensive AI application platform through multiple advanced features:

1. Vector Search & Semantic Caching

Vector Database: Storing query embeddings for semantic similarity matching
HNSW Algorithm: Efficient nearest-neighbor search for query similarity detection
Intelligent Caching: 95% similarity threshold for cache hits, eliminating redundant AI calls

2. Redis JSON for Complex Data Storage

Structured Itineraries: Complete travel plans stored as JSON documents without serialization overhead
Location Metadata: Detailed place information with coordinates, descriptions, and timing
User Preferences: Session context and personalization settings as JSON objects

3. Real-time Communication with Pub/Sub

Live Updates: Server-Sent Events pipeline powered by Redis Pub/Sub
Progress Indicators: Real-time streaming of AI generation progress to frontend
Multi-client Support: Concurrent user sessions with isolated event streams

4. Event Logging with Redis Streams

Complete Audit Trail: Every user interaction logged with timestamps
Event Sourcing: Replay capabilities for debugging and optimization
Session Flow: Complete interaction sequences for user experience analysis

5. Performance Monitoring with TimeSeries

Real-time Metrics: Response times, cache hit rates, and performance trends
Live Dashboard: Streaming performance data to frontend analytics
Historical Analysis: Time-based performance tracking with granular data points

Technical Architecture

Frontend (React/Next.js) 
    ↕ WebSocket/SSE
Backend API (Node.js/Express)
    ↕ 
Redis Stack (Vector Search, JSON, Pub/Sub, Streams, Embeddings Cache)
    ↕
OpenAI API (GPT-4, Embeddings)

TravelMate AI proves Redis isn't just fast storage - it's an intelligent platform for modern AI applications. From semantic understanding to real-time experiences, Redis powers every aspect of intelligent travel planning. The question isn't whether Redis can handle AI workloads, but how much more can you build when you stop thinking of Redis as just a cache?

DEV Community: Sumeet Naik

Serve Markdown to AI Agents from Hugo on Cloudflare Pages (Free Plan)

The shape of the solution

Step 1 — Make Hugo emit Markdown for every page

Step 2 — Write the Markdown templates

The gotcha: pages that live in front matter

Step 3 — The Cloudflare Pages Function

The bug you'll hit if you skip the content-type check

Step 4 — Tell caches the response varies

Test it locally

Why this stays free

Wrapping up

I Built an AI Pipeline That Writes My Tech Posts While I Code

What I Built

Demo

Code

My Tech Stack

How I Used Hermes Agent

Team Dashboard - Manage Your Team Efficiently with KendoReact

What I Built

🎯 Problems Solved:

🏢 Target Users:

🎥 Video Walkthrough

🚀 Live Application

📸 Screenshots & Features

Main Dashboard Interface

AI-Powered Query Assistant

Performance Analytics

Employee Management Dialog

KendoReact Components Used

AI Coding Assistant Usage

Component Architecture & Setup

Code Generation & Optimization

Styling & Responsiveness

Debugging & Problem Solving

Natural Language Query System:

Team Members:

TravelMate AI: Real-Time AI Travel Planner Powered by Redis Stack

What I Built

Demo

Screenshots

How I Used Redis 8

1. Vector Search & Semantic Caching

2. Redis JSON for Complex Data Storage

3. Real-time Communication with Pub/Sub

4. Event Logging with Redis Streams

5. Performance Monitoring with TimeSeries

Technical Architecture

Team Submission: Team JCoders