Most of the time, I wasn't trying to build anything. I just needed a better way to read markdown.
While working on new projects, I usually document commands, configs, notes, and setup steps as I go. Those quick README-style files often end up becoming the actual reference for deployments, onboarding, or environment setup later.
That workflow is where the friction started.
I'd open those docs in Visual Studio Code preview mode and follow along while configuring systems or testing environments. But the experience never quite felt designed for active usage.
Copying commands from code blocks was clumsy. Preview interactions often broke focus. Small interruptions kept repeating during workflows that already required attention.
Individually, none of those issues were major. Collectively, they slowed everything down.
I tried a few online markdown viewers, but most felt either too minimal to rely on or overloaded with features unrelated to actually using documentation during work.
Many tools seemed optimized for:
- editing
- note-taking
- collaboration
- workspace management
What I wanted was simple: a better way to consume markdown documentation while working. At some point, the problem became obvious. I didn't need another markdown app but a better documentation workflow.
You can try Opsly MD here: Opsly MD
Building Opsly MD
The first version was intentionally simple.
No accounts.
No syncing.
No cloud dependency.
Just a markdown workspace running entirely in the browser. That simplicity eventually became the core philosophy of the project.
I wanted something that could:
- open markdown instantly
- render large documents smoothly
- make code blocks easy to use
- support diagrams and math properly
- stay local-first
- feel lightweight and practical
Instead of building around "features," I started building around workflow friction.
What Started Shaping the Experience
As the project evolved, certain patterns kept becoming important during real usage.
Organization mattered more than expected. Documentation workflows quickly become messy when everything lives in a flat list, so workspace and folder structure became part of the experience early on.
Code blocks also needed to become more than static text. That eventually led to secure code block workflows through Opsly Mask, along with improvements around copying, formatting, and readability for large snippets and JSON responses.
Reliability became another major focus. Autosave, draft protection, import/export support, and persistent document state all came from trying to reduce small workflow interruptions that repeatedly break focus during technical work.
Across all of it, the goal stayed the same: make markdown documentation easier to navigate, safer to work with, and more practical during real-world workflows.
The Principles Behind It
Local-first by default.
Your markdown files stay with you.
No uploads.
No forced cloud sync.
No account wall before opening a .md file.
For documentation workflows, reducing dependency on external services felt important from the beginning.
Reading comes before editing
Most markdown tools focus heavily on writing. My workflow was different. I already write documentation in editors and repositories. What I needed was a better experience for actually using those docs while working.
That changed a lot of design decisions.
- Code blocks became interactive instead of static.
- Tables needed to remain readable.
- Mermaid diagrams had to render reliably.
- Math support needed to feel integrated instead of bolted on.
The goal was reducing friction during real workflows.
The Unexpected Complexity
Building a markdown renderer sounds simple until you start working with real-world markdown at scale.
Different formatting styles, nested structures, syntax variations, rendering inconsistencies, large documents, and plugin edge cases all start appearing surprisingly fast. Even small differences between markdown implementations can affect how documents render and behave.
Then there were the problems around the renderer itself: clipboard handling across browsers, rendering performance, parsing quirks, plugin compatibility, and keeping layouts consistent across different types of content.
What made things more complicated was realizing that markdown is far less standardized than it initially appears. GitHub Flavored Markdown, custom directives, math delimiters, MDX-style syntax, and platform-specific behavior all introduce their own variations and edge cases.
Supporting those differences reliably became a large part of the project.
Markdown is technically "simple" in the same way Kubernetes is "just containers."
The Features I Intentionally Avoided
One thing became clear while building Opsly MD:
Feature accumulation is easy. Most software starts focused and gradually becomes heavier over time.
I wanted Opsly MD to stay centered around the actual workflow:
reading, navigating, and using markdown documentation efficiently.
That meant being careful about adding features that increase complexity without improving the core experience.
The goal was never to build an all-in-one productivity platform.
It was to create a fast, practical, local-first markdown workspace that stays focused on real documentation workflows. That philosophy shaped almost every decision in the project.
What I Learned
The biggest lesson wasn't technical. It was how much small workflow interruptions affect focus over time.
Things like:
- losing your place while following setup steps
- constantly switching contexts
- struggling with code block interactions
- navigating poorly rendered tables
- repeatedly copying commands manually
None of those problems are major on their own, but together they create enough friction to disrupt the workflow. That became the real focus behind Opsly MD.
Where Opsly MD Is Heading
Opsly MD is still evolving, with current work focused on improving secure code block workflows, adding encryption and decryption support, refining rendering consistency across markdown variants, and making the overall experience feel faster and more workflow-oriented.
But the core direction remains unchanged.
Opsly MD is being built to stay local-first, lightweight, fast, and practical. The goal has never been to become another bloated "all-in-one productivity platform" held together by twelve AI buzzwords and investor hallucinations.
It exists because documentation workflows should feel simple, reliable, and frictionless.
That alone felt worth building.
Top comments (0)