Building the Komodo DeFi Framework Documentation Site: A Weekend Project with Astro

For a recent weekend project, I decided to build a standalone documentation website for the Komodo DeFi Framework. The final result is now live at komodoplatform.dev.

Why Astro?

Astro was a natural fit for a documentation-first website. Its strong MDX support, static-first approach, and flexible content pipeline make it well suited to projects that need to turn an existing documentation base into a fast, maintainable site without imposing a heavyweight client-side framework.

The framework also leaves room for custom components, build-time processing, and lightweight interactive features where they are genuinely useful. For documentation, that balance matters: readers get a focused, fast-loading experience, while the underlying setup remains adaptable as the content evolves.

After a brief review of the Astro documentation, it was clear that the framework covered the core requirements. The remaining work was implementation.

The Implementation Process

I chose to use AI to speed up the implementation. It proved valuable for moving the work forward, but it was not a substitute for technical judgment. Migrating an established documentation base into a new environment inevitably surfaced edge cases in how content was rendered, linked, and presented.

Those issues called for deliberate validation rather than visual review alone. Automated checks and browser-based testing helped confirm that navigation, search, interactive elements, and internal links worked as intended before deployment.

The takeaway was straightforward: AI can handle a meaningful share of the implementation workload, but engineers still need to define the constraints, identify likely failure points, and set the acceptance criteria. The underlying expertise does not disappear; it shifts from writing every line to steering, validating, and owning the outcome.

Deployment Strategy

Once the Astro development was complete, I purchased the komodoplatform.dev domain and wrote a GitHub Actions workflow to build and publish the documentation to GitHub Pages. This workflow is triggered manually (workflow_dispatch). The deployment pulls the latest tip of the content branch, ensuring updates are deliberate actions rather than side effects of a push. The workflow updates the submodule to the latest dev commit, builds the site, runs the link checker as a gating mechanism, and only then publishes the result.

I also preserved the old URLs: the content repository maintains a map of 440 legacy links, and the build process generates redirects for these paths. Site-wide search is powered by Pagefind, which builds its index during the build phase, eliminating the need for a backend.

The final result: 408 pages, a fully static site, and free hosting.

I hope this overview proves helpful for developers and serves as a practical example of combining domain knowledge with AI.

Site: komodoplatform.dev
Content Repository: github.com/KomodoPlatform/komodo-docs-mdx