Updated docs, added blog

maximebf · maximebf · commit 4909198586ab · 2025-09-24T22:13:27.000+02:00
diff --git a/docs/blog/index.md b/docs/blog/index.md
@@ -0,0 +1,5 @@
+---
+hide: [navigation, footer]
+---
+# Blog
+
diff --git a/docs/blog/posts/launch-annoncement.md b/docs/blog/posts/launch-annoncement.md
@@ -0,0 +1,56 @@
+---
+date: 2025-09-24
+pin: true
+---
+# Launch annoncement
+
+After 2 years of working on & off on Hyperflask, I'm happy to finally announce a working version that can be used to create actual production apps ! Although it is still in beta, all the desired features are present and working.
+
+In reality, Hyperflask is more than 10 years in the making ! My previous attempt at a comprehensive framework went nowhere but some of its ideas survived. The rise of [htmx](https://htmx.org/) and the revival of backend driven apps led me to get excited again.
+
+Backend-driven apps using something like htmx are not an answer to all type of web development. However, I'm convinced that they provide a solution for 80% of use cases (if not more) while simplying greatly the development experience, the cognitive load and the many footguns that frontend-heavy frameworks bring.
+
+I love [Flask](https://flask.palletsprojects.com/) as a framework but unfortunately, a lot of Flask extensions are barely maintained. In the meantime, other frameworks have introduced amazing innovations that greatly simplify the developer experience. Hyperflask is my attempt at synthetizing all the parts I like across various technologies and frameworks in a coherent stack. Integration between each chosen technology should be completely seamless.
+
+Among these innovations, notable ones are:
+
+ - [File-based routing](/guides/pages/) with a [new file format](https://github.com/hyperflask/jinjapy) that combines some python code and a jinja template, inspired by [Astro pages](https://docs.astro.build/en/basics/astro-pages/#astro-pages)
+ - [A component system](/guides/components/) inspired by frontend frameworks and [Astro islands](https://docs.astro.build/en/concepts/islands/). It can be used to create frontend or backend components. Components can have their own endpoints.
+ - Using streaming content to [display loaders](/guides/suspense/), inspired by [React Suspense](https://react.dev/reference/react/Suspense)
+ - [Static content](/guides/static/) generation with collections, inspired by [Jekyll](https://jekyllrb.com/)
+
+More than just a framework, **Hyperflask is a truly full stack solution**. From dev environments, to UI framework to deployments.  
+On top of the previously mentionned features, Hyperflask provides:
+
+ - Deep integration with [htmx](https://htmx.org/)
+ - An easy to use and [powerful ORM](https://github.com/hyperflask/sqlorm) that stays close to SQL
+ - A large library of [UI components](/components/) powered by [Tailwind](https://tailwindcss.com/), [DaisyUI](https://daisyui.com/) and [Bootstrap Icons](https://icons.getbootstrap.com/)
+ - A modern assets pipeline using [esbuild](https://esbuild.github.io/) with image optimizations
+ - [Server push](/guides/push/) for realtime updates using SSE, based on the [Mercure protocol](https://mercure.rocks/)
+ - [Template based emails](/guides/emails/) powered by [MJML](https://mjml.io/)
+ - Background tasks
+ - Translations
+ - Dev environments based on [dev containers](https://containers.dev/)
+ - Deployments using containers
+
+All the technologies used by Hyperflask have been carefully selected for their quality, developer experience, ease of use, feature set and popularity.
+
+The framework is optimized to limit "magic" features while ensuring ease of use. React Server Components or Phoenix LiveView are impressive but they hide too many things, often leading to many footguns and hacks around them. In Hyperflask, everything is just Python, standard Flask and Jinja with jinjapy files and htmx as the binding agent.
+
+One of my side goals with Hyperflask is to revive and modernize the Flask ecosystem. As a result, **almost all of the features listed before have been developed as independent Flask extensions**. Hyperflask itself is mostly glue code to make them work together. [Pick and choose the extensions](https://github.com/hyperflask) you want for your own projects.
+
+In the same spirit, there are some projects developed as part of Hyperflask that can be used indepently of Flask:
+
+ - [sqlorm](https://github.com/hyperflask/sqlorm), a performant and straighforward ORM that does not attempt to hide SQL
+ - [jinjapy](https://github.com/hyperflask/jinjapy), a new file format that combines python code and a jinja template
+ - [jinja-super-macros](https://github.com/hyperflask/jinja-super-macros), a new syntax to call macros in jinja
+ - [uilib-spec](https://github.com/hyperflask/uilib-spec), a specification to generate bindings for UI component libraries (see [uilib-spec-daisyui](https://github.com/hyperflask/uilib-spec-daisyui) for a use case)
+ - [docker-web-deploy](https://github.com/hyperflask/docker-web-deploy), a CLI tool to deploy containers to various platforms, including VPS
+
+All these projects are available on the [Hyperflask Github organization](https://github.com/hyperflask).
+
+Check out the [Getting Started](/getting-started) tutorial, read more about the [goals, technologies and reasoning](/why) behind the project or [deep dive into the guides](/guides/setup).
+
+PS: I've already used Hyperflask to build [SQLify](https://sqlify.me/) as part of my job at [Digicoop](https://digicoop.io) and the experience was very satisfying.
+
+
diff --git a/docs/getting-started.md b/docs/getting-started.md
@@ -35,6 +35,9 @@ What you will need:
 
 Python is not needed on your machine, everything will be executed inside containers.
 
+!!! info
+    Although VS Code with dev containers is the recommended experience, it is not mandatory. Hyperflask apps are standard python apps and you can install their requirements in a virtualenv and start a server using the CLI. See the [setup guide for more information on how to run without VS Code or dev containers](/guides/setup/#advanced)
+
 ## Installation
 
 We will use [Hyperflask-Start](https://github.com/hyperflask/hyperflask-start) to create our project.
@@ -47,10 +50,7 @@ This will prompt you for some options and create the project in a new folder.
 
 Open your project folder in VS Code. It should prompt you to "re-open workspace in development container" which you should accept. VS Code will create and start the development container and re-launch itself.
 
-You are now developping from the container inside which you will find Python 3.11, Node & npm and hyperflask installed.
-
-!!! info
-    Although VS Code with development containers is the recommended experience, it is not mandatory. Hyperflask apps are standard python apps and you can install their requirements in a virtualenv and start a server using the CLI.
+You are now developping from the container inside which you will find Python 3.13, NodeJS 24, uv and hyperflask installed.
 
 ## Running your app
 
diff --git a/docs/guides/components.md b/docs/guides/components.md
@@ -8,6 +8,7 @@ Components are essentials pieces of Hyperflask apps. They can be interactive, ar
 ## HTML components
 
 HTML components are re-usable pieces of HTML. Define them in the *app/components* folder. The filename is the component name.
+They are rendered on the backend.
 
 Components can recieve parameters named *props*.
 
@@ -26,7 +27,7 @@ For example, to create a dropdown component, let's create the file *app/componen
 
 Here, the component must be provided 2 parameters: label and items.
 
-To call this component, we use a special syntax in our templates:
+To call this component, we use a [special syntax](https://github.com/hyperflask/jinja-super-macros?tab=readme-ov-file#new-macro-tags-syntax) in our templates:
 
  - `<{ComponentName prop1=value prop2=value }/>` : to call a component without providing children
  - `<{ComponentName prop1=value }>...</{ComponentName}>` : to provide children
diff --git a/docs/guides/deploy.md b/docs/guides/deploy.md
@@ -3,7 +3,7 @@
 !!! info
     This feature is provided by [Docker Web Deploy](https://github.com/hyperflask/docker-web-deploy)
 
-## Build & deploy
+## Build & deploy using Hyperflask-Start
 
 Run the following command:
 
@@ -13,12 +13,25 @@ $ uv run hyperflask deploy
 
 ## Static site generation
 
-TODO
+Run `hyperflask build`. You site will be generated in the `_site` folder.
 
-## Only build the image
+!!! tip
+    Use `hyperflask csp-header` to print the CSP policy to properly configure your web server.
+
+## Building for production
+
+### Only building the docker image
 
 When using Hyperflask-Start, the app is containerized. Run `docker build .` to build the image.
 
+### Without docker
+
+Run `hyperflask build` to build assets and static content.
+
+In production, assets will not be built and nodejs is not required. Ensure that the file `app/assets.json` and the `public` directory are shipped.
+
+If you have static content, it will be generated in the *_site* folder. You can use a proxy server like nginx to serve urls from this folder first or fallback to your app for hybrid content mode.
+
 ## Monitoring
 
 Check out the [recipe on monitoring](/recipes/monitoring).
diff --git a/docs/guides/for-flask-users.md b/docs/guides/for-flask-users.md
@@ -8,6 +8,9 @@ The `flask` module can be replaced by `hyperflask` for all your Flask related im
 
 The `hyperflask` command should be used instead of `flask` to run and manage your app.
 
+!!! warning
+    Hyperflask loads its configuration from files. Configuration happens as part of the Hyperflask constructor. This means once you have created your app, it is already configured and extensions are already initialized. To provide configuration at app creation time, use `app = Hyperflask(__name__, config={"key": "value"})`
+
 ```py
 # app.py
 from hyperflask import Hyperflask, request
diff --git a/docs/guides/interactive-apps.md b/docs/guides/interactive-apps.md
@@ -6,6 +6,7 @@ Hyperflask can be used to create interactive apps thanks to HTMX.
 
 HTMX has [comprehensive documentation](https://htmx.org/docs/) but this section will cover the essential.
 
+TODO
 
 ## Interactive components
 
@@ -150,4 +151,8 @@ You can also add out of band elements in your template using the `<{HtmxOob}>` c
 
 ```
 <{HtmxOob}><{Sidebar}/></{HtmxOob}>
-```
+```
+
+## Realtime apps
+
+Add realtime updates to your app using [push messages](/guides/push).
diff --git a/docs/guides/metadata.md b/docs/guides/metadata.md
@@ -1,3 +1,5 @@
 # Metadata
 
+Hyperflask can manage a page metadata for you. This is necessary for SEO.
+
 TODO
diff --git a/docs/guides/push.md b/docs/guides/push.md
@@ -21,28 +21,34 @@ current_app.sse.publish("messages", current_app.components.ChatMessage(msg="hell
 
 ## Listening for events
 
-Use htmx [sse extension](https://htmx.org/extensions/sse/) to connect to the SSE stream. Retrieve the stream URL for an event using `mercure_hub_url(event_names)`. Use `mercure_authentified_hub_url(event_names)` to create authentified URLs that can receive private events.
-
-```html
-<div hx-ext="sse" sse-connect="{{mercure_authentified_hub_url('messages')}}" sse-swap="message" hx-swap="beforeend">
-</div>
-```
-
-Hyperflask also provides a component that encapsulates the previous html:
+Hyperflask provides some components to leverage the htmx [sse extension](https://htmx.org/extensions/sse/). 
 
 ```
 <{MercureStream topic="messages"}>
+    {# default content #}
 </{MercureStream}>
 ```
 
-| Property | Required | Type | Description |
-|----------|----------|------|-------------|
+| Property | Required | Type | Description | Default |
+|----------|----------|------|-------------|---------|
 |topic|Yes|string|The topic name|
-|private|No|bool|Whether to use an authentified url|
-|hx_swap|string|The swap strategy (default: beforeend)|
-|type|string|The type of event to listen to (default: message)|
-|auto_scroll|bool|Whether to keep the div scrolled at the bottom when receiving new items|
-|Any additional properties|No|any||
+|private|No|bool|Whether to use an authentified url|False
+|hx_swap|No|string|The swap strategy|beforeend
+|type|No|string|The type of event to listen to|message
+|auto_scroll|No|bool|Whether to keep the div scrolled at the bottom when receiving new items|False
+|Any additional properties|||Will be used as attributes of the div|
+
+To create a div which content will be replaced on each new message, use `hx_swap="innerHTML"`.
+
+!!! info
+    Using Hyperflask components is optional and htmx sse extension or any EventSource can be used directly.
+    
+    Retrieve the stream URL for an event using `mercure_hub_url(event_names)`. Use `mercure_authentified_hub_url(event_names)` to create authentified URLs that can receive private events.
+
+    ```html
+    <div hx-ext="sse" sse-connect="{{mercure_authentified_hub_url('messages')}}" sse-swap="message" hx-swap="beforeend">
+    </div>
+    ```
 
 ## Using with models
 
diff --git a/docs/guides/scaling.md b/docs/guides/scaling.md
@@ -1,6 +1,6 @@
 # Scaling
 
-Hyperflask is a standard Flask app. It is made of 4 different processes:
+Hyperflask is made of different processes. It uses [honcho](https://honcho.readthedocs.io/en/latest/) as process manager.
 
 | Process | Description | Defaut port | Can be multiplied
 | --- | --- | --- | --- |
diff --git a/docs/guides/setup.md b/docs/guides/setup.md
@@ -18,23 +18,50 @@ Python is not needed on your machine, everything will be executed inside contain
 
 We will use [Hyperflask-Start](https://github.com/hyperflask/hyperflask-start) to create our project.
 
-!!! info
-    Although it is not mandatory, Hyperflask-Start is the officially recommended experience.
-
 Launch the following command to create your project:
 
     curl -L https://raw.githubusercontent.com/hyperflask/hyperflask-start/main/start.sh | bash
 
 This will prompt you for some options and create the project in a new folder.
 
+## Launching using VS Code and dev containers
+
 Open your project folder in VS Code. It should prompt you to "re-open workspace in development container" which you should accept. VS Code will create and start the development container and re-launch itself.
 
 You are now developping from the container inside which you will find Python 3.11, Node & npm and hyperflask installed.
 
-## Installation without Hyperflask-Start
+## Advanced
+
+Although **VS Code with dev containers is the recommended experience**, it is not mandatory. Hyperflask apps are standard python apps and you can install their requirements in a virtualenv and start a server using the CLI.
+
+### Launching without dev containers
+
+First [create a project using Hyperflask-Start](#installation-using-hyperflask-start).
+
+1. Ensure that your system meet the requirements:
+    - Python (>=3.10)
+    - [uv](https://docs.astral.sh/uv/)
+    - [nodejs](https://nodejs.org/fr) (>=22)
+2. Run `npm install`
+3. Launch app using `uv run hyperflask dev`
+
+### Launching with devcontainers-cli
+
+If you are not using VS Code but want to use dev containers, a CLI tool is available:
+
+1. [Install devcontainers-cli](https://github.com/devcontainers/cli#npm-install)
+2. Start dev container: `devcontainer up --workspace-folder .`
+3. Launch your app: `devcontainer exec uv run hyperflask dev`
+3. Go to http://localhost:5000
+
+### Installation without Hyperflask-Start
+
+This installation method works with any python package manager
 
-1. Create your project directory: `mkdir example-project && cd example-project`
+1. Ensure that your system meet the requirements
+2. Create your project directory: `mkdir example-project && cd example-project`
 2. Create and activate a virtualenv: `python -m venv .venv && source .venv/bin/activate`
 3. `pip install hyperflask`
 4. Run `hyperflask init .`
-5. Start a development server using `hyperflask dev`
+5. Run `npm install`
+6. Start a development server using `hyperflask dev`
diff --git a/docs/guides/structure.md b/docs/guides/structure.md
@@ -25,15 +25,17 @@ When using the `hyperflask` command, an Hyperflask app instance will be automati
     
     The actuall application object is available at `hyperflask.factory:app` (or `hyperflask:current_app` when in [app context](https://flask.palletsprojects.com/en/stable/appcontext/)).
 
-The *app* folder is available as a python module and the following packages will be automatically imported from it if they exist:
+The *app* folder is available as a python package and the following will be automatically imported from it if they exist:
 
  - *models* : to define your database models
  - *routes* : to define app routed endpoints
  - *tasks*: to define background tasks using dramatiq
  - *cron*: to define scheduled tasks using dramatiq
  - *cli*: to define command line tasks
 
-To import things from these modules from the rest of your app:
+Define them as modules (eg. `app/models.py`) or packages (eg. `app/models/__init__.py`)?
+
+To import things from the rest of your app:
 
 ```py
 # app/models.py
@@ -47,17 +49,3 @@ class MyModel(db.Model):
 # anywhere else
 from app.models import MyModel
 ```
-
-## Manually creating the app
-
-An app will be automatically created only if no application can be automatically discovered following the [Flask mechanism](https://flask.palletsprojects.com/en/stable/cli/#application-discovery).
-
-To manually create an app, create an `__init__.py` file in the *app* folder with the following code:
-
-```py
-from hyperflask import Hyperflask
-
-app = Hyperflask(__name__)
-```
-
-When doing so, no automatic configuration or imports are performed.
diff --git a/docs/recipes/stripe.md b/docs/recipes/stripe.md
@@ -1,6 +1,6 @@
 # Stripe Checkout
 
-The Hypeflask organization maintains the [Flask-Stripe-Checkout](https://github.com/hyperflask/flask-stripe-checkout) project. Using it, you can quickly start charging people using [Stripe Checkout](https://stripe.com/payments/checkout), Stripe's hosted payment pages.
+Using [Flask-Stripe-Checkout](https://github.com/hyperflask/flask-stripe-checkout), you can quickly start charging people using [Stripe Checkout](https://stripe.com/payments/checkout), Stripe's hosted payment pages.
 
 ## Installation & setup
 
@@ -18,7 +18,7 @@ To use webhooks locally:
 
 Now, install the extension:
 
-    poetry add flask-stripe-checkout
+    uv add flask-stripe-checkout
 
 Configure your environment variables in *.env*:
 
diff --git a/docs/roadmap.md b/docs/roadmap.md
@@ -1,7 +1,7 @@
 ---
-hide: [navigation, footer]
+hide: [navigation, footer, toc]
 ---
-# Roadmap
+# Status & Roadmap
 
 Hyperflask is being actively developed and is not yet ready for production.
 
@@ -10,9 +10,10 @@ Checkout the list of all the projects developed as part of the Hyperflask Stack
 Key stuff that is still missing:
 
 - SQLite broker for Dramatiq and background task tests
-- Dockerfile & Deployments
-- Static content mode
-- Better error reporting for jinjapy files
+- [Dockerfile & Deployments](http://localhost:8000/guides/deploy/)
+- [Static content mode](http://localhost:8000/guides/static/)
+- [Image optimizations](http://localhost:8000/guides/assets/#optimized-images)
+- [Metadata](http://localhost:8000/guides/metadata/)
 - Syntax highlighting for the macro tags syntax in jinja templates
 
 Planned v1 experience:
@@ -32,8 +33,8 @@ Planned v1 experience:
 | I18n | 🚧 | finalizing | [flask-babel-hyper](https://github.com/hyperflask/flask-babel-hyper)
 | Static site generation | ❌ | | [hyperflask](https://github.com/hyperflask/hyperflask)
 | Deployments | ❌ | | [docker-web-deploy](https://github.com/hyperflask/docker-web-deploy)
-| VS Code integration | ✅ |  | 
-| Documentation | 🚧 |  | [hyperflask-docs](https://github.com/hyperflask/hyperflask-docs)
+| VS Code integration | 🚧 | missing syntax highlighting for macro tags | 
+| Documentation | 🚧 | continuous improvements, more beginner docs | [hyperflask-docs](https://github.com/hyperflask/hyperflask-docs)
 
 ## Extras
 
diff --git a/mkdocs.yml b/mkdocs.yml

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +hide: [navigation, footer]
 +---
 +# Blog
++