IdeaWell

Project ideas from Hacker News discussions.

Markdown in /src

Original Article

Hacker News Discussion

📝 Discussion Summary (Click to expand)

Theme 1: Where documentation lives in the repository
- “I generally put markdown in /docs. I don’t uppercase filenames. Instead I make a documentation generator consume the files so I get a decent navigation in HTML/PDF builds.” – ktpsns
- “Developer documentation in /src, yes. Anything else, no way. … keep it near and obvious.” – euroderf

Theme 2: Storing non‑code artifacts (logs, transcripts, screenshots, etc.) in version control
- “Let’s keep the Codex session JSONL there too… debug build logs… logs/reports from every test run… screenshots of every app run… token provider billing documents…” – throwuxiytayq
- “I store my markdown as GitHub issues, regardless of how I come up with a detailed feature description…” – jmathai

Theme 3: Treating documentation (including source, tests, agent transcripts) as first‑class code
- “I still like the idea of source code as documentation and unit tests as documentation.” – Naru41
- “This sounds a lot like a low tech version of Delta from Zed. All your agent transcripts live in the same place as code.” – tancop

🚀 Project Ideas

RepoDocGen

Summary

  • Scans repository for markdown files in any location (src/, packages/*/docs, docs/) and builds a unified, searchable documentation site with navigation that reflects code proximity.
  • Core value: eliminates the need to maintain separate docs folder while giving developers instant, contextual documentation alongside code.

Details

Key Value
Target Audience Software developers, open-source maintainers, teams using monorepos
Core Feature Automatic discovery and hierarchical navigation of markdown docs based on directory closeness to source code, with live reload and code symbol linking
Tech Stack Rust (cli) + Askama templating; optional Pandoc for PDF export
Difficulty Medium
Monetization Hobby

Notes

  • HN commenter ktpsns said: “I generally put markdown in /docs. I don't uppercase filenames. Instead I make a documentation generator consume the files so I get a decent navigation in HTML/PDF builds.” This tool directly satisfies that desire while allowing docs to live near code.
  • Enables new repo conventions (e.g., package‑level docs) and can be hooked into IDEs for on‑the‑fly docs lookup.

AgentSession Archive

Summary

  • Captures LLM agent transcripts (JSONL), test logs, screenshots, and billing documents automatically, storing them versioned alongside code.
  • Core value: provides a searchable, auditable history of AI‑assisted development for debugging, regression tracking, and compliance.

Details

Key Value
Target Audience ML/AI engineers, dev teams using LLM coding agents, QA engineers
Core Feature Hooks into agent frameworks to save session JSONL, captures test run stdout/stderr, takes UI test screenshots, stores billing PDFs, and indexes all content for full‑text search
Tech Stack Python hooks + SQLite/LMDB metadata; git‑annex or Git LFS for large files; optional React web UI
Difficulty High
Monetization Hobby

Notes

  • throwuxiytayq urged: “Let’s keep the Codex session JSONL there too… And the debug build logs… And logs/reports from every test run… screenshots of every app run… token provider billing documents.” This tool implements exactly that wishlist.
  • Provides a low‑tech analogue to Zed’s Delta, giving teams a tangible way to revisit AI‑driven changes and discuss reproducibility on HN.

SpecLink

Summary

  • Links markdown feature specs (stored as GitHub issues or repo files) directly to code changes via labels/branches, providing traceability from description to implementation.
  • Core value: reduces context switching and ensures LLMs and humans have up‑to‑date spec context when working on code.

Details

Key Value
Target Audience Product managers, developers, teams practicing spec‑driven development
Core Feature Automatically creates bidirectional links between a spec markdown file/issue and the PR/commit that implements it, shows spec status in IDE/status bar, and can export spec as markdown for LLM context
Tech Stack GitHub Actions (or GitLab CI) + small Node.js service; spec metadata kept in a .spec/ directory; optional web UI
Difficulty Medium
Monetization Hobby

Notes

  • jmathai noted: “I store my markdown as GitHub issues… Before implementation, context is always cleared to ensure that the model is working only from known context… agents can look up prior prompt instructions as needed.” SpecLink makes that prior context instantly accessible.
  • Sparks discussion about spec‑driven dev and how to keep LLMs aligned with evolving feature descriptions, a recurring theme in the thread.

Read Later