<!-- mobian-agent-page publisher="dailydev" canonical="https://daily.dev/posts/OKFHYpym1" -->

---
title: > htmx ~ Markdown in | daily.dev
description: Carson Gross argues that Markdown is evolving into source code rather than documentation in the era of agentic coding, where LLMs generate implementation from...
canonical: https://daily.dev/posts/htmx-markdown-in-okfhypym1
twitter:card: summary_large_image
twitter:site: @dailydotdev
og:type: website
og:site_name: daily.dev
og:title: > htmx ~ Markdown in | daily.dev
og:description: Carson Gross argues that Markdown is evolving into source code rather than documentation in the era of agentic coding, where LLMs generate implementation from...
og:url: https://daily.dev/posts/htmx-markdown-in-okfhypym1
og:image: https://api.daily.dev/og/posts/OKFHYpym1.png
og:image:alt: > htmx ~ Markdown in
og:image:width: 1200
og:image:height: 630
og:locale: en
---

> ## Documentation Index
> Fetch the complete documentation index at: https://daily.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# > htmx ~ Markdown in

**[htmx](https://daily.dev/sources/htmx)** · 7 min read · 20 upvotes · 1 comments

## Summary

Carson Gross argues that Markdown is evolving into source code rather than documentation in the era of agentic coding, where LLMs generate implementation from prompts. He proposes checking Markdown into a new /src/md directory alongside generated code, structured with files like README.md, OVERVIEW.md, and feature/data/API descriptions, so code and tests can be derived from persisted Markdown rather than ephemeral prompt sessions. The essay draws on the principle of locality, arguing this keeps intent next to implementation for both humans and agents, while suggesting the /src/md directory should remain mostly human-authored rather than AI-generated.

## Full article

daily.dev links to this article rather than hosting it. Read it at the original source: <https://htmx.org/essays/markdown-in-src>

## Questions this post answers

### Why should Markdown files be checked into the source directory instead of just used as documentation?

Markdown is increasingly the real specification for software built with LLMs, since code is generated from prompts rather than hand-written, so keeping it as ephemeral prompt text loses the intent behind the code. Storing it in a directory like /src/md, next to the code it produces, follows the principle of locality: both humans and agents can find the rationale without hunting through wikis, tickets, or Slack threads.

_Developers rethinking how to document AI-generated code can find more perspectives like this on daily.dev._

### What is a proposed folder structure for storing markdown specifications alongside source code?

One proposed convention places a README.md as an agent entry point, a TODO.md for open tasks, an OVERVIEW.md for a technical summary, plus optional subfolders like features/, data/, api/, and infrastructure/ each holding topic-specific markdown files. The structure is intentionally flexible, meant to divide a module's behavior along whichever axes best capture it, and is still an early, evolving proposal rather than a fixed standard.

_Teams designing conventions for AI-assisted codebases can track evolving ideas like this via daily.dev._

## Community take

How the wider developer community reacted, aggregated from 2 discussions and 12 comments across lobsters, hackernews (as of 2026-09-21).

**TL;DR:** The proposal to treat a curated /src/md directory as source code draws mostly skepticism, with people questioning whether unchecked Markdown can function like a type system and whether the workflow of iterative prompting can realistically be captured in static docs.

**Sentiment:** 10% positive · 30% mixed · 60% skeptical

**The case for**

- The idea of keeping human-authored specs/interfaces alongside code and generating tests or implementations against them was seen as a reasonable, already-practiced pattern.
- One commenter noted the key caveat that the /src/md directory should stay human-authored rather than AI-slop is what makes the proposal workable at all.

**The pushback**

- Several found it odd to lump all markdown into one directory rather than colocating docs with the specific code they describe.
- Multiple commenters doubted Markdown, being unchecked and non-deterministic, can meaningfully serve as 'source code' the way typed languages do.
- Real development involves many iterative back-and-forth prompts that aren't easily captured or reduced to a single persisted document.
- Some argued this idea isn't really new, just a rebranding of the general principle that source artifacts (ADRs, notebooks, etc.) should live with code.

**By community**

- lobsters (skeptical): Most commenters pushed back on treating Markdown as source code, questioning the directory structure, the analogy to type systems, and the practicality of capturing iterative prompt sessions.
- hackernews (mixed): No substantive comments were provided for this discussion.

**Hottest debate:** Whether Markdown, being unchecked and non-deterministic, can legitimately be considered 'source code' comparable to typed programming languages.

**Open questions**

- How would the /src/md documents be kept in sync when new requirements or edge cases are discovered mid-implementation?
- Would this practically devolve into reviewing AI-generated 'plan mode' slop despite the intent for human authorship?

**Highlights**

> Really hard pass on this here, but I can definitely see why people want this, it sits right around the "tickets/discussion should be colocated with code" discussions. Elixir has `exdoc`, Rust has `rustdoc` and Unison has `{{ fancy doc comments}}`, there are also a quite a lot of notebook-style programming environments. I feel like all of those tools have (a lot!) more potential for being integrated with slopped code than seeing markdown as source code in a directory. It took years for type systems(ergonomic ones like OCaml/Elm) to catch some traction, and now we want to go and write some unchecked Markdown and see it as part of a system? Am I out of touch, or is that really the way to make resilient systems?
> — [zetashift on lobsters · 3 points, 1 comments](https://lobste.rs/s/xooho4/markdown_src#c_oeyqs1)

> I don't know how this is actually supposed to work. I do write detailed initial prompts, and I often try to capture those (usually in the commit message), but for anything nontrivial there follows several back and forth rounds where I'm telling it "actually, rip out the Foo and try just augmenting Bar" or "add some tests for condition X (and fix the code if they fail)" or whatever. (And no, I don't think this will go away with better models, because often _I_ don't know what I want without trying something and seeing how it looks.) Even if I was capturing these later prompts, they aren't very easy to interpret in the absence of the earlier iterations of the code, which I'm throwing away. I could capture the whole session, and I've seen people make the case for that, but that's not quite what's being asked for here.
> — [bakkot on lobsters · 1 points, 1 comments](https://lobste.rs/s/xooho4/markdown_src#c_mpqwh4)

> > I believe that agents should not be used to generate much content in /src/md. This directory should be mainly human authored and curated. I think that’s the key to this proposal but it’s buried deep down in the article. Otherwise people would assume plan mode slop which I find is excruciating to review.
> — [facundoolano on lobsters · 1 points](https://lobste.rs/s/xooho4/markdown_src#c_p2aq7f)

> In some projects, I will create a root folder `docs/`. I will then number files `YYYY-MM-DD-title.md` or `NNN-title.md`, starting at `000` and counting up. I strictly keep only human-authored documents in this folder. I will do things like spec out interfaces and tests and invariants by hand, and then write automated checks to ensure that the interfaces match what is documented. I also like to include what I call "Provenance" frontmatter for all files. For human-written markdown/code files, this is something like: ```md +++ created: YYYY-MM-DD author: Name <email> +++ ``` And for AI-generated e.g. code/markdown, this is something like: ```rs // created: YYYY-MM-DD // model: glorm-9-promax // driver: Name <email> ``` I have a strict "no AI edits human provenance, no human edits AI provenance" policy; AI edits also "infect" the provenance of human-produced artifacts should I manually break that rule. I will often like to write out e.g. trait, interface definition, or module files with human provenance, then generate a test suite / implementation with AI provenance against that interface definition.
> — [slightknack on lobsters · 1 points](https://lobste.rs/s/xooho4/markdown_src#c_wrsmen)

> It's strange to me that LLMs seem to motivate this, instead of "your source artifacts should live with your code..." ...and source artifacts include [decision records](https://adr.github.io/) of [various sorts](https://rfd.shared.oxide.computer/), lab notebooks used to run experiments, etc. Yeah, someone trying to understand the code needs access to all those; make it accessible to them.
> — [cceckman on lobsters · 1 points](https://lobste.rs/s/xooho4/markdown_src#c_zzbs5i)

**Source threads**

- [lobsters](https://lobste.rs/s/xooho4/markdown_src) · 10 points · 12 comments
- [hackernews](https://news.ycombinator.com/item?id=49787640) · 1 points · 0 comments

## Community discussion

Top comments from developers on daily.dev.

**@cholerakk** · 1 upvotes

> Yes, I even completely stopped using Confluence, instead, I am using markdown files directly in the codebase. I also developed by own desktop app in Rust that creates embeddings and provides better/faster information retrieval via MCP.

## Similar posts on daily.dev

- [It's time to move your docs in the repo](https://daily.dev/posts/it-s-time-to-move-your-docs-in-the-repo-5ncacizen) · Hacker News · 1 upvotes · 0 comments
- [Andrej Karpathy, Google and Garry Tan agree Markdown is the answer, but they’re not solving the same problem](https://daily.dev/posts/andrej-karpathy-google-and-garry-tan-agree-markdown-is-the-answer-but-they-re-not-solving-the-same-lxq4tg8i0) · The New Stack · 0 upvotes · 0 comments
- [Serving Markdown for AI Agents](https://daily.dev/posts/serving-markdown-for-ai-agents-j2txtbg8z) · RUBYLAND · 2 upvotes · 1 comments
- [Markdown Became the Control Plane for AI](https://daily.dev/posts/markdown-became-the-control-plane-for-ai-afcgdibtk) · API Evangelist · 23 upvotes · 2 comments

---

Tags: [#llm](https://daily.dev/tags/llm), [#architecture](https://daily.dev/tags/architecture), [#ai-coding](https://daily.dev/tags/ai-coding), [#markdown](https://daily.dev/tags/markdown)

[View this post on daily.dev](https://daily.dev/posts/htmx-markdown-in-okfhypym1)

```json
{"@context":"https://schema.org","@graph":[{"@type":"Organization","@id":"https://daily.dev/#organization","name":"daily.dev","url":"https://daily.dev","logo":{"@type":"ImageObject","url":"https://daily.dev/apple-touch-icon.png","width":180,"height":180},"sameAs":["https://twitter.com/dailydotdev","https://github.com/dailydotdev","https://www.linkedin.com/company/daily-dev-ltd"]},{"@type":"WebSite","@id":"https://daily.dev/#website","url":"https://daily.dev","name":"daily.dev","publisher":{"@id":"https://daily.dev/#organization"},"potentialAction":{"@type":"SearchAction","target":{"@type":"EntryPoint","urlTemplate":"https://daily.dev/search?q={search_term_string}"},"query-input":"required name=search_term_string"}}]}
{"@context":"https://schema.org","@type":"TechArticle","headline":"\u003e htmx ~ Markdown in","url":"https://daily.dev/posts/htmx-markdown-in-okfhypym1","mainEntityOfPage":{"@type":"WebPage","@id":"https://daily.dev/posts/htmx-markdown-in-okfhypym1"},"datePublished":"2026-09-21T13:39:17.057Z","dateModified":"2026-09-21T20:21:19.366Z","description":"Carson Gross argues that Markdown is evolving into source code rather than documentation in the era of agentic coding, where LLMs generate implementation from...","image":"https://media.daily.dev/image/upload/s--ZrL_HSsR--/f_auto/v1722860399/public/Placeholder%2006","thumbnailUrl":"https://media.daily.dev/image/upload/s--ZrL_HSsR--/f_auto/v1722860399/public/Placeholder%2006","isAccessibleForFree":true,"articleSection":"htmx","inLanguage":"en","publisher":{"@type":"Organization","name":"daily.dev","url":"https://daily.dev","logo":{"@type":"ImageObject","url":"https://daily.dev/apple-touch-icon.png","width":180,"height":180}},"author":{"@type":"Organization","name":"htmx","logo":"https://media.daily.dev/image/upload/t_logo,f_auto/v1/logos/b323e4d0aaf947cab86aec534f1f044b","url":"https://daily.dev/sources/htmx"},"commentCount":1,"discussionUrl":"https://daily.dev/posts/htmx-markdown-in-okfhypym1","interactionStatistic":[{"@type":"InteractionCounter","interactionType":{"@type":"LikeAction"},"userInteractionCount":20},{"@type":"InteractionCounter","interactionType":{"@type":"CommentAction"},"userInteractionCount":1}],"keywords":"llm,architecture,ai-coding,markdown","timeRequired":"PT7M"}
{"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https://daily.dev"},{"@type":"ListItem","position":2,"name":"htmx","item":"https://daily.dev/sources/htmx"},{"@type":"ListItem","position":3,"name":"\u003e htmx ~ Markdown in"}]}
{"@context":"https://schema.org","@type":"WebPage","@id":"https://daily.dev/posts/htmx-markdown-in-okfhypym1","comment":[{"@type":"Comment","text":"Yes, I even completely stopped using Confluence, instead, I am using markdown files directly in the codebase. I also developed by own desktop app in Rust that creates embeddings and provides better/faster information retrieval via MCP.","datePublished":"2026-09-23T06:17:22.906Z","url":"https://daily.dev/posts/OKFHYpym1#c-7e2EN76zc","author":{"@type":"Person","name":"Martin Leinweber","url":"https://daily.dev/cholerakk","image":"https://lh3.googleusercontent.com/a/ACg8ocIjCoI1kmwWb9TGMZYxVC8pjAGmy2Tv4LN_8KgjNxJpNIDUxHsl=s96-c"},"interactionStatistic":{"@type":"InteractionCounter","interactionType":{"@type":"LikeAction"},"userInteractionCount":1}}]}
{"@context":"https://schema.org","@type":"FAQPage","@id":"https://daily.dev/posts/htmx-markdown-in-okfhypym1#faq","mainEntity":[{"@type":"Question","name":"Why should Markdown files be checked into the source directory instead of just used as documentation?","acceptedAnswer":{"@type":"Answer","text":"Markdown is increasingly the real specification for software built with LLMs, since code is generated from prompts rather than hand-written, so keeping it as ephemeral prompt text loses the intent behind the code. Storing it in a directory like /src/md, next to the code it produces, follows the principle of locality: both humans and agents can find the rationale without hunting through wikis, tickets, or Slack threads. Developers rethinking how to document AI-generated code can find more perspectives like this on daily.dev."}},{"@type":"Question","name":"What is a proposed folder structure for storing markdown specifications alongside source code?","acceptedAnswer":{"@type":"Answer","text":"One proposed convention places a README.md as an agent entry point, a TODO.md for open tasks, an OVERVIEW.md for a technical summary, plus optional subfolders like features/, data/, api/, and infrastructure/ each holding topic-specific markdown files. The structure is intentionally flexible, meant to divide a module's behavior along whichever axes best capture it, and is still an early, evolving proposal rather than a fixed standard. Teams designing conventions for AI-assisted codebases can track evolving ideas like this via daily.dev."}}]}
```

