Sidenote: Annotate Rendered Pages Directly, Let LLM Auto-Generate Git Commits

The Overlooked Pain Point: The Gap Between Editing Experience and Content Presentation

For anyone maintaining a technical blog or documentation site, this scenario is all too familiar: you're viewing a rendered page in the browser, spot an unclear sentence, a typo, or want to add a line — then you have to switch to your editor, dig through Markdown syntax, front matter, and directory structures to find the corresponding source file, locate the exact line, make the change, and commit to Git.

The root of this disconnect lies in the core design philosophy of static site generators (SSGs). Tools like Hugo, Jekyll, and Astro enforce a strict separation between "content source files" and "rendered output": authors write in Markdown or MDX, and the generator transforms it into HTML at build time. It's worth understanding that this "build-time rendering" philosophy was a deliberate rebellion against dynamic CMS platforms — traditional systems like WordPress query the database and render pages on every user request, introducing security vulnerabilities, performance bottlenecks, and operational overhead. SSGs front-load all rendering to the build stage, producing pure static files with CDN-friendly delivery, zero server requirements, and native version control. Hugo achieves millisecond-level builds with Go, Jekyll became the default for developer blogs through native GitHub Pages support, and Astro introduced "islands architecture" to enable selectively hydrated interactive components on a static-first foundation. This architecture delivers exceptional version control and deployment flexibility, but it also means that every character you see in the browser is the product of template engines, Markdown parsers, and component systems — separated from the source file by an opaque transformation pipeline. Front matter (the metadata block at the top of a file, typically in YAML or TOML format), shortcodes, content fragment references… any rendered paragraph might be assembled from multiple source files. Authors must maintain a mental mapping from Markdown syntax to HTML visual output at all times, which constitutes an ongoing cognitive load.

This back-and-forth switching process may seem trivial, but it's one of the biggest hidden friction points in content maintenance. Between what you see (rendered output) and what you edit (source markup), there's always a layer of cognitive translation cost.

A recent open-source project on Hacker News, Sidenote, targets exactly this pain point: it lets you annotate directly on rendered blog pages, then uses a large language model (LLM) to automatically generate the corresponding Git diff.

Sidenote's Core Workflow

According to the project's Show HN introduction, Sidenote's concept can be summed up in one sentence: Edit your static blog like leaving comments on Google Docs.

From "Annotations" to "Code Changes"

The entire workflow breaks down into three steps:

1. Comment on the rendered page: Users view the blog's final presentation in the browser and leave natural language annotations exactly where changes are needed — for example, "This sentence is too wordy, tighten it up" or "Add some recent data here."
2. LLM understands intent and locates source files: The system maps the user's comment and page context to the underlying source files, then hands it off to the LLM for analysis. The model must determine where the rendered content corresponds to in the source code and understand what modification the user wants.
3. Generate a Git diff: The LLM's output isn't a loose set of suggestions but a structured Git diff — a code change that can be directly reviewed, applied, and committed.

The elegance of this design lies in using the LLM as a translation layer, stitching together two previously disconnected experiences: "WYSIWYG annotation" and "version-controlled source code modification."

Why Output Git Diff Instead of Directly Modifying Files?

Sidenote's choice to output Git diff rather than directly overwriting files is a decision that reflects engineering prudence. Git diff is the standard difference format of the Git version control system, using +/- symbols to mark added and removed lines, with @@-prefixed line number ranges and three lines of context for anchoring, making change intent immediately clear. This format is essentially a universal "change description language": it doesn't depend on any specific editor or platform, and any Git-compatible toolchain can consume it directly via git apply or wrap it in a Pull Request workflow for team review. The choice of Git diff as the output format reflects three layers of consideration:

• Reviewable: LLM modifications are always presented in a human-readable comparison format. Authors retain final decision-making authority, preventing the model from making uncontrolled changes on its own.
• Reversible: All changes are tracked under version control and can be easily undone if something goes wrong. Git's distributed version management inherently provides a complete change history, and any erroneous commit can be precisely reversed via git revert or git reset.
• Compatible with existing workflows: Most technical blog authors already use Git for content management. Sidenote integrates seamlessly into existing habits rather than requiring a new system.

The Technical Trend Behind This Type of Tool

Although Sidenote is a small and focused project, it reflects an increasingly clear direction in recent years: LLMs are evolving from "content generators" to "intent executors."

From "Write for You" to "Edit for You"

The core value of early AI writing tools was "write for you" — give a prompt, get text output. Tools like Sidenote focus on "edit for you," and specifically on precise modifications within the constraints of a defined source code structure. This requires the LLM to possess several advanced capabilities:

• Contextual localization: Accurately mapping vague descriptions at the rendering layer back to specific positions in the source code. This is technically non-trivial — the model needs to simultaneously understand the dual semantics of HTML-rendered output and Markdown source, establishing precise positional correspondence between the two representations.
• Structured output: Generating changes that conform to Git diff format specifications, rather than free-form text. This relies on the "constrained generation" capabilities of modern LLMs — a capability with a clear technical lineage: OpenAI introduced Function Calling in 2023, allowing developers to predefine function signatures via JSON Schema to guide models toward outputs conforming to specific data structures. Subsequently, JSON Mode, Structured Outputs strict mode, Anthropic's Tool Use, and similar mechanisms matured, driving the error rate of obtaining machine-parseable structured data from models toward zero. For Sidenote, this means the model can be asked to output precise JSON objects containing file paths, line number ranges, and added/deleted content, which the application layer then formats into standard Git diff strings. Mainstream models like GPT-4 and Claude 3.5 have quite mature capabilities in this area, providing the technical prerequisite for tools like Sidenote to be viable today.
• Intent inference: Understanding high-level natural language instructions like "tighten this up" or "add data" and translating them into concrete text operations.

This aligns with the trajectory of AI coding assistants like Cursor, Aider, and Claude Code. These tools represent a new paradigm of "codebase-aware AI": they don't just answer questions in a chat box but can read an entire project's file structure, understand inter-code dependencies, and directly create, modify, or delete files in the repository. Cursor embeds AI capabilities into VS Code's editing experience; Aider uses a command-line interface to let LLMs operate directly on Git repositories; Claude Code further strengthens autonomous execution of multi-step tasks. Sidenote can be seen as a specialized extension of this paradigm into the "content creation" vertical — the LLM is no longer just a conversation partner but a collaborator capable of directly operating on codebases and generating executable changes.

Reconciling "Visual Editing" and "Source-First" Philosophies

The static site generator camp (Hugo, Jekyll, Astro) champions a "source-first, plain-text-controlled" philosophy, while tools like Notion and Google Docs represent the other extreme of "WYSIWYG, directly manipulating the visual presentation." Each has its adherents and its pain points. It's worth noting that multiple generations of content management system (CMS) tools have attempted to bridge this gap, but none have fully succeeded. First-generation headless CMSes (Contentful, Prismic) store content in cloud databases, serving it to frontends via REST or GraphQL APIs — editors get a rich text interface, but content is decoupled from local Git repository version control. Second-generation Git-based CMSes (Netlify CMS, now Decap CMS, Tina CMS, Forestry) read and write Markdown files directly in Git repositories, attempting to combine the best of both worlds. However, these solutions all require introducing separate backend services or cloud accounts, adding infrastructure complexity, and their editing interfaces are still fundamentally "graphical representations of source files" rather than "direct manipulation of the final rendered output" — they never truly addressed the core need of "annotating intent directly on the final rendered result."

Sidenote offers a middle path: preserving the version control advantages of a source-first approach while introducing a visual-layer editing experience through LLM. Its differentiation lies in not introducing a new content layer, but instead bridging the existing rendering layer and source layer with an LLM as an intelligent translation bridge — users express intent on the rendered page, and the system implements changes at the source layer. This may represent a convergence direction for future content tools.

Real-World Challenges and Limitations

As an early-stage project, Sidenote faces very practical challenges.

Mapping accuracy is the primary difficulty. The correspondence between rendered pages and source files isn't always one-to-one — the same rendered text might come from a combination of templates, components, Markdown content, and even external data. Whether the LLM can reliably locate the correct source position is the key factor determining the tool's usability. This problem is particularly acute in complex sites that make heavy use of shortcodes, content references, or dynamic data injection, and the model's context window limitations can also affect its localization accuracy in large content repositories.

Trust in modification quality is equally important. While Git diff provides a review step, if the LLM frequently generates changes that require substantial reworking, the review cost might actually exceed that of manual editing, negating the tool's value.

Additionally, API costs and response latency need to be weighed — every annotation requires an LLM call, and for high-frequency micro-editing scenarios, both factors are real constraints. Using mainstream model pricing as a reference, a GPT-4o or Claude 3.5 Sonnet request that includes full source file context costs on the order of a few cents; for larger sites with frequent annotations, cumulative costs and response wait times can both become factors affecting willingness to use the tool.

Small Tool, Big Direction

Sidenote itself may be just one of many developer tools built around LLMs, but it clearly demonstrates a product approach worth watching: using LLMs to bridge the gap between the "presentation layer" and the "source layer."

For content creators, the ideal editing experience should be "say what you're thinking, and let the tool handle the rest." Sidenote shows us that as LLMs continue to improve in intent understanding and structured output, the "say it and it's changed" editing paradigm is moving from concept to reality. For blog authors who have long been jumping back and forth between Markdown and the browser, this is a direction worth keeping an eye on.