Search posts, papers, and topics
The essay argues that Markdown should be treated as source code and checked into a /src/md directory alongside the implementation it describes. Keeping intent in diffable, reviewable Markdown lets teams generate code and tests from it while preserving locality for both humans and AI agents.
The author turned a one‑off script that rendered each Jekyll page to Markdown and added a `<link rel="alternate" type="text/markdown">` tag into a reusable Jekyll plugin (jekyll‑md). The gem hooks into the build, extracts the main content (defaulting to `<main>` or `[role="main"]`), converts it to Markdown, injects the discovery link, and requires no per‑page front‑matter. Configuration is option…
Codename One replaced its Javadoc‑generated site with a Hugo‑based pipeline: a custom doclet emits one Hugo content file per Java type, preserving Markdown comments, generating a lightweight search index, and keeping the traditional offline Javadoc archive. The approach reduces index size (1.9 MB → 341 KB gzipped), retains existing anchors, and can be reused for other Java projects.
