MintyFlaskSSG has reached a point of relative stability. The core functionality works reliably, the architecture feels solid, and I can generate static sites without worrying about fundamental issues. MintyFlaskThemes, the companion project, still needs more work before I'd call it complete, but the separation between the two projects has clarified their respective responsibilities.
This feels like a good moment to assess where things stand.
The split and stabilisation
Splitting MintyFlaskSSG from MintyFlaskThemes created short-term disruption but long-term clarity. Originally, themes and core functionality lived in a single repository. This worked initially but conflated concerns that deserved separation. The static site generator handles content processing, routing, and build mechanics. The themes package provides template architecture and presentation.
After the split, I spent considerable time settling the codebase. Changes rippled through both projects as I refined interfaces, clarified dependencies, and established proper boundaries. Flask's app factory pattern meant reorganising how configuration flowed between projects. Template resolution needed careful attention to ensure the three-layer hierarchy worked consistently. The photo system required updates to support external directory structures properly.
This stabilisation phase involved more refactoring than I initially expected. Code that worked fine in a monolithic structure sometimes revealed assumptions that didn't hold across project boundaries. I fixed these issues as I found them, writing tests where complexity warranted extra certainty.
The result is a more maintainable architecture. MintyFlaskSSG focuses on what it does best—processing Markdown content, managing Flask routes, handling photo integration, and generating static HTML. MintyFlaskThemes concentrates on template patterns, CSS architecture, and presentation logic. Each project can evolve independently whilst maintaining compatibility through well-defined interfaces.
Documentation progress
Documentation currently exists but needs expansion. The core functionality is documented in the project README and code comments. Key architectural decisions have inline explanations. Configuration options are listed with brief descriptions. This covers the basics but leaves gaps for developers new to the project.
I've started building comprehensive documentation covering:
- Getting Started Guide: Installation, basic configuration, first site build
- Configuration Reference: All config options with examples and defaults
- Template System Guide: How the three-layer hierarchy works in practice
- Content Management: Writing Markdown, organising files, using frontmatter
- Photo Integration: Setting up galleries, processing images, EXIF handling
- Extending MintyFlaskSSG: Adding custom blueprints, creating new routes
The documentation lives alongside the code and generates through the docs blueprint. This means documentation itself uses MintyFlaskSSG, which serves as both practical validation and demonstration of capabilities.
You can find the current documentation at [project documentation URL]. It's incomplete but growing steadily.
Current focus areas
My immediate focus centres on two areas: settling the codebase and improving documentation.
Codebase stabilisation means addressing lingering issues from the split. Some functionality may have regressed when I separated the projects. The debug blueprint, which provides development-time introspection, needs verification that all routes still work correctly. The photos blueprint requires testing to ensure gallery processing and image optimisation function as expected after the external directory restructuring. CLI functionality, particularly the photo processing commands and content management tools, deserves thorough testing.
These aren't show-stopping bugs—the core functionality works—but they represent rough edges that need smoothing before I'd recommend MintyFlaskSSG to others without caveats.
Documentation improvement involves writing the tutorial content that helps developers get productive quickly. The reference documentation explains what configuration options do, but tutorials show how to accomplish common tasks: building a blog, creating a portfolio, setting up multi-language content, integrating photos effectively. This practical guidance matters more than exhaustive API documentation for a static site generator.
I'm also documenting architectural decisions. Why does the template system use three layers instead of two or four? Why process photos at build time rather than runtime? Why separate themes from core functionality? These explanations help developers understand the reasoning behind the structure, which makes extending and modifying MintyFlaskSSG more intuitive.
Known issues and limitations
Several known limitations deserve mention:
Debug blueprint functionality: After the split, some debug routes may not correctly reflect the current project structure. The debug system provides introspection into template resolution, route registration, and configuration values. This worked well in the monolithic version but needs verification in the split architecture. Routes that display template search paths, for instance, should correctly show both MintyFlaskSSG and MintyFlaskThemes directories.
Photos blueprint integration: The photo system underwent significant changes to support external directory structures. Whilst basic functionality works—images process, galleries generate, PhotoSwipe integration functions—edge cases around missing images, malformed EXIF data, and unusual file formats need more thorough testing. The photo processor should handle these gracefully rather than failing silently or producing cryptic errors.
CLI command reliability: Flask CLI commands for photo processing and content management may have rough edges. Commands like flask photos process and flask content create-post should work but need systematic testing across different project configurations. Error messages should clearly explain what went wrong rather than dumping stack traces.
These issues represent known problems with clear solutions rather than fundamental architectural concerns. They need time and attention, not redesign.
Where we stand
MintyFlaskSSG isn't finished—software rarely is—but it works. The core architecture feels solid. The separation from MintyFlaskThemes clarified both projects. The Flask patterns make sense to Flask developers. The semantic markup principles show through in generated HTML.
Some rough edges remain. Documentation needs expansion. Testing coverage wants improvement. The template resolution system sometimes requires careful debugging. The photo processing pipeline could use more format support. These are knowable problems with clear solutions.
But the foundation is there. You can build websites with MintyFlaskSSG today. You can extend it tomorrow. You can fork it, adapt it, ignore bits you don't need. That's the point—it's a toolkit, not a prison.
For developers who value semantic HTML, appreciate Flask's patterns, prefer Python to Node.js, and want their static sites generated through readable, debuggable processes—MintyFlaskSSG offers something different. Not necessarily better, not universally applicable, just different.
Sometimes different is exactly what you need.
Looking ahead
The immediate roadmap includes:
Configuration cleanup: The config.py file accumulated options over development. Some settings duplicate functionality, others have unclear names, and the overall structure could be more intuitive. A refactoring pass will consolidate related options, improve naming consistency, and add clearer documentation strings.
Enhanced Markdown features: Adding support for Mermaid diagrams would enable flowcharts, sequence diagrams, and other visual documentation directly in Markdown. This fits naturally with MintyFlaskSSG's documentation-friendly approach and requires minimal integration effort using existing Mermaid libraries.
Improved test coverage: Whilst core functionality has tests, coverage remains inconsistent. Systematic testing of blueprints, photo processing, and template resolution would catch regressions earlier and make confident refactoring easier.
These aren't promises—they're intentions. Development happens when time allows. But they represent logical next steps that would move MintyFlaskSSG from "works well enough" to "works reliably for others."
Using MintyFlaskSSG today
If you're considering MintyFlaskSSG for a project, understand its current state. It works for building static sites. The architecture is sound. The documentation exists but needs expansion. Some rough edges remain.
This makes it suitable for developers comfortable troubleshooting issues and reading code when documentation falls short. If you need polished, comprehensive, everything-just-works software, wait until documentation improves and known issues resolve. If you want to explore an alternative approach to static site generation that values Flask patterns and semantic HTML, MintyFlaskSSG offers that today.
The project is available at [repository URL]. Documentation lives at [documentation URL]. Issues and contributions welcome at [issues URL].
That's where we stand—functional, improving, useful for the right projects, and honest about its current limitations.