# [](#markdown-rendering--sharepoint-client-site-iis-hosted)Markdown Rendering — SharePoint Client Site (IIS-hosted)
This document describes how to serve a markdown-formatted version of public pages to verified LLM bots — when, and only when, they request it — on an IIS-hosted SharePoint Client Site (Microsoft stack with client-side HTML rendering). This is a common configuration for enterprise sites.
## [](#goal)Goal
When a verified LLM bot requests a public page, return high-density markdown instead of full HTML/CSS/JavaScript. When any other client requests the same URL, return the normal SharePoint response. The behavior is invisible to end users.
## [](#why-this-matters)Why this matters
Metric
Typical HTML response
Markdown response
Bytes per page
200 KB – 2 MB
5 KB – 80 KB
Useful content ratio
5% – 15%
90%+
Crawler retrieval time
high (full page weight)
low
RAG vectorization quality
mediocre (noise)
high (signal-dense)
Crawl budget consumed
high
low
Cloudflare formalized industry-level support for markdown-on-bot-request in late 2025. This is the same idea, implemented at the origin.
## [](#architecture)Architecture
Plaintext
```
┌────────────────────────┐
Request ────────▶│ IIS / Front Edge │
│ (existing) │
└─────────┬──────────────┘
│
▼
┌────────────────────────┐
│ Maya Header Router │ ← new component
│ (URL Rewrite + ASP. │
│ NET Core middleware) │
└─────────┬──────────────┘
│
┌───────────────┴───────────────┐
│ │
▼ ▼
┌────────────────────┐ ┌────────────────────┐
│ User-Agent ∈ allow │ │ Otherwise │
│ list and feature │ │ │
│ flag enabled │ │ │
├────────────────────┤ ├────────────────────┤
│ → /api/render/ │ │ → SharePoint │
│ markdown?path=… │ │ Client Site │
│ → text/markdown │ │ → text/html │
└────────────────────┘ └────────────────────┘
```
The router is a small ASP.NET Core middleware (or, equivalently, an IIS URL Rewrite rule) that runs **in front of** SharePoint, never inside it. SharePoint itself is unmodified.
## [](#component-a--header-router)Component A — Header Router
### [](#pattern-aspnet-core-middleware)Pattern (ASP.NET Core middleware)
C#
```
// Program.cs (or Startup.cs)
app.Use(async (context, next) =>
{
if (!FeatureFlag.IsEnabled("maya.markdown_rendering"))
{
await next();
return;
}
var ua = context.Request.Headers.UserAgent.ToString();
if (LlmBotMatcher.IsLlmBot(ua) && context.Request.Method == "GET")
{
// Internal redirect to markdown renderer.
var path = context.Request.Path.Value ?? "/";
var query = context.Request.QueryString.HasValue
? context.Request.QueryString.Value
: "";
context.Request.Path = "/api/render/markdown";
context.Request.QueryString = new QueryString($"?path={Uri.EscapeDataString(path + query)}");
}
await next();
});
```
### [](#iis-url-rewrite-alternative)IIS URL Rewrite alternative
If middleware deployment is constrained, IIS URL Rewrite can match on `User-Agent` and proxy to the markdown endpoint. Reference rule:
XML
```
```
The third condition (`featureflags\maya.markdown_rendering`) is a file-presence check — flipping the file in or out enables/disables the feature without an IIS restart.
## [](#component-b--markdown-renderer)Component B — Markdown Renderer
The renderer is a small ASP.NET Core endpoint (or a function on the BFF layer once migrated) that:
1. Resolves the requested path to its underlying SharePoint resource.
2. Fetches the rendered HTML internally (server-to-server, no public round-trip).
3. Converts to clean markdown.
4. Returns with `Content-Type: text/markdown; charset=utf-8` and a short `Cache-Control`.
### [](#reference-handler)Reference handler
C#
```
[ApiController]
[Route("api/render/markdown")]
public class MarkdownRenderer : ControllerBase
{
private readonly HttpClient _internalClient;
private readonly IHtmlToMarkdownConverter _converter;
public MarkdownRenderer(HttpClient internalClient, IHtmlToMarkdownConverter converter)
{
_internalClient = internalClient;
_converter = converter;
}
[HttpGet]
public async Task Render([FromQuery] string path)
{
if (string.IsNullOrEmpty(path) || !path.StartsWith("/"))
return BadRequest();
var html = await _internalClient.GetStringAsync(
new Uri(new Uri("https://internal-sharepoint/"), path));
var markdown = _converter.Convert(html, options: new()
{
StripScripts = true,
StripStyles = true,
RetainStructure = true, // headings, lists, tables, links
RetainOpenGraph = true, // emit OG tags as YAML front matter
});
Response.Headers.CacheControl = "public, max-age=300, s-maxage=900";
Response.Headers.ContentType = "text/markdown; charset=utf-8";
return Content(markdown, "text/markdown");
}
}
```
### [](#conversion-rules)Conversion rules
Element
Treatment
``–``
Preserved as `#`–`######`
`
`
Preserved as paragraph
``
Preserved as `[text](url)`
`![]()
`
Preserved as `` (with caption from `figcaption` if present)
`
`
Preserved as GitHub-flavored markdown table
`