Serving my blog posts as Linux manual pages

Original Article ↗ Hacker News Discussion ↗

Serving blog posts as Unix man pages is praised as a clever way to reuse existing terminal tooling, with readers sharing one-liners, process substitution tricks, and notes on cross-platform quirks between Linux and macOS. Commenters highlight tools for converting Markdown to troff/groff, debate the correct MIME type, and suggest extensions like Debian packages, AUR entries, or even Docker images that turn a blog into locally browsable documentation. A significant thread revolves around security: whether piping remote content directly into commands like `man` (or worse, a shell) is safe, and how small changes to workflows—temporary files, `&&` chains, or sandboxing—can reduce risk.

Overall reaction to serving blog posts as man pages

  • Many commenters find the idea fun, clever, and well executed.
  • Some see it as a natural extension of Unix culture and man-page ergonomics.
  • A few think the post focused more on Nginx content negotiation than the “interesting” conversion problem.

Using curl/man and cross-platform quirks

  • Multiple one-liners are discussed to view posts as man pages:
    • Piping curl to man with -H "Accept: text/roff" and man -l - on Linux.
    • Using process substitution (man <(curl ...) in Bash, man =(curl ...) in Zsh) to avoid temporary files.
  • macOS’s man lacks -l and behaves differently with /dev/stdin and process substitution, leading to workarounds or use of mandoc.

Formatting, conversion, and roff/man nuances

  • Clarifications: .TH etc. come from the man macro package, not raw roff itself; the correct MIME type is text/troff.
  • Proper troff style (one sentence per line) and lines starting with . are mentioned as important for correctness and safety.
  • Several markdown→roff tools are suggested (pandoc, md2man, kramdown-man, ronn, lowdown, md2roff).
  • The author notes build-time concerns and GitHub Pages integration as reasons for not adding another parser yet.

Security: piping internet content into commands

  • Extensive debate on whether piping curl into commands is safe:
    • Strong warnings against curl | bash due to partial-download execution and server-side detection of piping.
    • Some argue piping into non-shell tools (like man) is less problematic, but others point out:
      • groff/troff historically can execute commands and have CVEs.
      • Even viewers and parsers (less, ffmpeg, cat, terminals) have had vulnerabilities.
  • Alternatives suggested:
    • Download to a temp file, then run (curl ... > /tmp/file && man /tmp/file).
    • General advice to form good habits and avoid streaming untrusted content directly into executors.

Packaging and subscription ideas

  • Idea: distribute blog posts as a .deb package so apt update pulls posts and man blogname shows them; a prototype repo exists.
  • Suggestions escalate jokingly: AUR package, Flatpak, AppImage, Electron app, Docker images, docker-compose “blogroll.”
  • Others point to existing Debian documentation integration and argue RSS might be more practical.

Related tools and terminal fun

  • Mentions of mdless, mkws.sh, and mandoc/groff multi-output (HTML, PDF, PS).
  • References to other terminal-based experiences: ASCII Star Trek movie, Star Wars over telnet, ANSI art viewers, and tldr pages.