Etch: The Markdown-Native Personal Site Framework
Etch: The Markdown-Native Personal Site Framework
In an era where web development often means juggling JavaScript toolchains, complex build pipelines, and megabytes of configuration files, Etch arrives as a refreshing return to simplicity. This minimalist, Python-based web framework reimagines how content-driven websites should be built—by stripping away unnecessary complexity and embracing the tools developers already know and love.
The Philosophy Behind Etch
Etch was born from a simple realization: sometimes you don't need a JavaScript toolchain, Go templates, or a megabyte of YAML . You just want to write, commit, and publish in a familiar language . For Python developers weary of bloated static site generators, Etch offers a path back to straightforward, transparent web development.
The framework was designed with a bias toward simplicity and transparency . Unlike the complex ecosystems that have grown around modern web development, Etch keeps things minimal and hackable. It's the kind of tool that feels like home to developers who value clarity over complexity.
Core Architecture and Features
Markdown-First Publishing Model
At the heart of Etch is a markdown-first approach that respects the way content creators actually work. All content lives in straightforward directories—posts/, pages/, and projects/—and each file must be written in Markdown with a YAML frontmatter block.
This frontmatter pattern, familiar to anyone who has used static site generators, provides essential metadata while keeping content clean and readable:
yaml:
---
title: My First Post
date: 2025-07-01
tags: [ai, flask]
summary: A quick walkthrough of building Etch
---
Here's the main content...
Zero Build Steps
Perhaps the most liberating feature of Etch is the complete absence of build steps . Content is rendered at request time using Flask and Jinja2, meaning you can make edits and see them live immediately—no waiting for rebuilds, no complex deployment pipelines. This real-time feedback loop makes Etch perfect for personal blogs, digital résumés, and project portfolios where agility matters more than scale.
Smart Caching
Despite the request-time rendering model, Etch doesn't sacrifice performance. The framework features smart caching for fast reads , ensuring that your site remains responsive even as content grows. This intelligent approach to caching strikes a balance between the simplicity of dynamic rendering and the speed of static generation.
AI-Assisted Architecture
Etch embraces modern development practices, including AI-assisted architecture . The framework was built with Claude 3.5, demonstrating a forward-thinking approach to software creation. This integration hints at future possibilities for AI-enhanced content management and site customization.
Technical Implementation
Flask and Jinja2 Foundation
Built on Flask and Jinja2, Etch provides a fully Pythonic experience that developers can easily understand and extend . The project structure is refreshingly straightforward:
text:
etch/ ├── app.py # Main Flask app and routes ├── utils.py # Markdown parsing, helpers, caching ├── config.yml # Site config (paths, author info, etc.) ├── auth.py # Admin login + password hashing ├── templates/ # Jinja2 HTML templates ├── posts/ # Markdown files for blog posts ├── pages/ # Static pages (e.g., About) ├── projects/ # Markdown-based project entries ├── static/ # CSS, JS, images
This organization makes it immediately clear where everything belongs. The templates directory uses Jinja2, allowing for familiar and powerful templating without learning a new syntax . The static directory handles CSS and assets, and routes can be customized directly in app.py.
Content Type Registry
One of Etch's more flexible features is the CONTENT_TYPES registry in utils.py . This allows developers to add or remove content types easily, making the framework adaptable to different needs beyond the standard posts, pages, and projects.
Configuration and Customization
Site configuration lives in config.yml, where you can set site title, author information, description, post pagination, content directory paths, and even admin password hashes . The configuration is minimal by design—you only change what you need to change.
Admin Features
While admin routes aren't enabled by default, Etch includes auth.py with login helpers for future administrative features . This thoughtful inclusion suggests a roadmap for browser-based content editing, though for now, the framework sticks to its markdown-native roots.
Getting Started
Installation and Setup
Getting started with Etch is refreshingly simple. Install the package from PyPI :
bash:
pip install etch
Then create a new project:
bash:
etch new-site
Optionally, use the --bare or -b flag if you prefer starting without demo content . Once your project is created, navigate to it and run the server:
bash:
cd new-site
flask run # or python app.py
Visit http://localhost:5000 and you're ready to go. Make an edit, add a page or post, and your content will be live immediately—no server restart needed.
Writing Content
The content creation workflow is intuitive. Each markdown file in the appropriate directory must include a YAML frontmatter block, followed by the main content. This structure is consistent across all content types, making it easy to maintain a uniform workflow regardless of what you're publishing.
Who Is Etch For?
The Python Developer
If you're a Python developer who wants to avoid bloated static site generators, Etch is tailor-made for you . The framework feels natural to anyone comfortable with Python, Flask, and Jinja2.
The Minimalist Creator
For content creators tired of complexity, Etch removes the friction between writing and publishing. No build steps mean you focus on what matters—your content.
The Hackable Enthusiast
Etch is designed to be customized . Whether you want to modify templates, add new content types, or extend functionality, the framework's transparent structure makes it easy.
The Privacy-Conscious Developer
Running your own Etch site means you control everything—no third-party platforms, no data collection, no vendor lock-in. It's your content on your terms.
How Etch Compares to Alternatives
Traditional static site generators often require complex setup, build steps, and specialized knowledge. They can be powerful but overkill for many use cases. Etch offers a middle path—dynamic rendering with static-like speed, Python's accessibility, and zero build friction.
Unlike single-page applications that demand JavaScript knowledge and toolchains, Etch works with HTML and CSS anyone can understand. And unlike fully dynamic CMS platforms, Etch keeps things lightweight and transparent.
The framework's "AI-assisted architecture" also suggests a more future-ready approach than many older static site generators. This integration with modern AI tools, as evidenced by Etch's own development with Claude 3.5, hints at new possibilities for content creation and site management.
Future Directions
The inclusion of auth.py and admin login helpers suggests exciting possibilities for Etch's future. While browser-based editing isn't enabled by default, the foundation exists for more advanced features without compromising the framework's minimalist ethos.
The AI-assisted architecture also opens interesting doors. As AI tools continue to evolve, Etch's Python foundation and clean structure may make it particularly well-suited for AI-enhanced content creation, editing, and site management.
Conclusion
Etch represents a thoughtful rejection of complexity in web development. In a landscape filled with bloated frameworks, convoluted build processes, and ever-changing toolchains, Etch offers something precious: simplicity with power, transparency with capability, and Pythonic elegance with practical utility.
For developers who want to write content, not configuration files, and who believe that web development should be accessible rather than opaque, Etch is more than a framework—it's a philosophy. As the web continues to evolve, sometimes the most innovative approach is remembering what already works and making it better. Etch does exactly that.
The framework's motto might well be "just write, commit, and publish" . In those six words, Etch captures what content-driven web development should always have been about—focusing on the content, not the infrastructure built around it.