flixOpt · FBumann · Dec 3, 2025 · Dec 4, 2025 · Dec 4, 2025 · Dec 4, 2025
diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml
@@ -0,0 +1,108 @@
+name: Docs
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'docs/**'
+      - 'mkdocs.yml'
+      - 'flixopt/**'
+  pull_request:
+    paths:
+      - 'docs/**'
+      - 'mkdocs.yml'
+  workflow_dispatch:
+  workflow_call:
+    inputs:
+      deploy:
+        type: boolean
+        default: false
+      version:
+        type: string
+        required: false
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+  PYTHON_VERSION: "3.11"
+  MPLBACKEND: Agg
+  PLOTLY_RENDERER: json
+
+jobs:
+  build:
+    name: Build documentation
+    runs-on: ubuntu-24.04
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+
+      - uses: astral-sh/setup-uv@v6
+        with:
+          version: "0.9.10"
+          enable-cache: true
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: ${{ env.PYTHON_VERSION }}
+
+      - name: Extract changelog
+        run: |
+          cp CHANGELOG.md docs/changelog.md
+          python scripts/format_changelog.py
+
+      - name: Install dependencies
+        run: uv pip install --system ".[docs,full]"
+
+      - name: Build docs
+        run: mkdocs build --strict
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: docs
+          path: site/
+          retention-days: 7
+
+  deploy:
+    name: Deploy documentation
+    needs: build
+    if: ${{ inputs.deploy == true }}
+    runs-on: ubuntu-24.04
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+
+      - uses: astral-sh/setup-uv@v6
+        with:
+          version: "0.9.10"
+          enable-cache: true
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: ${{ env.PYTHON_VERSION }}
+
+      - name: Install mike
+        run: uv pip install --system mike
+
+      - uses: actions/download-artifact@v4
+        with:
+          name: docs
+          path: site/
+
+      - name: Configure Git
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+
+      - name: Deploy docs
+        run: |
+          VERSION=${{ inputs.version }}
+          VERSION=${VERSION#v}
+          mike deploy --push --update-aliases --no-build $VERSION latest
+          mike set-default --push latest
diff --git a/.github/workflows/release.yaml b/.github/workflows/release.yaml
@@ -188,37 +188,7 @@ jobs:
     name: Deploy documentation
     needs: [create-release]
     if: "!contains(github.ref, 'alpha') && !contains(github.ref, 'beta') && !contains(github.ref, 'rc')"
-    runs-on: ubuntu-24.04
-    permissions:
-      contents: write
-    steps:
-      - uses: actions/checkout@v5
-        with:
-          fetch-depth: 0
-
-      - uses: astral-sh/setup-uv@v6
-        with:
-          version: "0.9.10"
-
-      - uses: actions/setup-python@v6
-        with:
-          python-version: ${{ env.PYTHON_VERSION }}
-
-      - name: Extract changelog
-        run: |
-          uv pip install --system packaging
-          python scripts/extract_changelog.py
-
-      - name: Install docs dependencies
-        run: uv pip install --system ".[docs]"
-
-      - name: Configure Git
-        run: |
-          git config user.name github-actions[bot]
-          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
-
-      - name: Deploy docs
-        run: |
-          VERSION=${GITHUB_REF#refs/tags/v}
-          mike deploy --push --update-aliases $VERSION latest
-          mike set-default --push latest
+    uses: ./.github/workflows/docs.yaml
+    with:
+      deploy: true
+      version: ${{ github.ref_name }}
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -7,10 +7,17 @@ repos:
       - id: check-yaml
         exclude: ^mkdocs\.yml$  # Skip mkdocs.yml
       - id: check-added-large-files
+        exclude: ^examples/resources/Zeitreihen2020\.csv$
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
     rev: v0.12.4
     hooks:
     - id: ruff-check
       args: [ --fix ]
     - id: ruff-format
+
+  - repo: https://github.com/kynan/nbstripout
+    rev: 0.8.1
+    hooks:
+      - id: nbstripout
+        files: ^docs/examples.*\.ipynb$
diff --git a/docs/examples/00-Minimal Example.md b/docs/examples/00-Minimal Example.md
diff --git a/docs/examples/01-Basic Example.md b/docs/examples/01-Basic Example.md
diff --git a/docs/examples/02-Complex Example.md b/docs/examples/02-Complex Example.md
diff --git a/docs/examples/03-Optimization Modes.md b/docs/examples/03-Optimization Modes.md
diff --git a/docs/examples/04-Scenarios.md b/docs/examples/04-Scenarios.md
diff --git a/docs/examples/05-Two-stage-optimization.md b/docs/examples/05-Two-stage-optimization.md
diff --git a/docs/examples/index.md b/docs/examples/index.md
diff --git a/docs/home/citing.md b/docs/home/citing.md
@@ -12,7 +12,7 @@ If you've published research using flixOpt, please let us know! We'd love to fea
 
 ### List of Publications
 
-*Coming soon: A list of academic publications that have used flixOpt*
+Coming soon: A list of academic publications that have used flixOpt.
 
 ## Contributing Back
 

diff --git a/docs/home/installation.md b/docs/home/installation.md
@@ -87,5 +87,5 @@ For more details on logging configuration, see the [`CONFIG.Logging`][flixopt.co
 ## Next Steps
 
 - Follow the [Quick Start](quick-start.md) guide
-- Explore the [Minimal Example](../examples/00-Minimal Example.md)
+- Explore the [Minimal Example](../notebooks/01-quickstart.ipynb)
 - Read about [Core Concepts](../user-guide/core-concepts.md)
diff --git a/docs/home/license.md b/docs/home/license.md
@@ -4,7 +4,7 @@ flixOpt is released under the MIT License.
 
 ## MIT License
 
-```
+```text
 MIT License
 
 Copyright (c) 2022 Chair of Building Energy Systems and Heat Supply - TU Dresden

diff --git a/docs/home/quick-start.md b/docs/home/quick-start.md
@@ -88,27 +88,49 @@ battery = fx.Storage(
 flow_system.add_elements(solar, demand, battery, electricity_bus)
 ```
 
-### 5. Run Optimization
+### 5. Visualize and Run Optimization
 
 ```python
-# Create and run optimization
-optimization = fx.Optimization('solar_battery_optimization', flow_system)
-optimization.solve(fx.solvers.HighsSolver())
+# Optional: visualize your system structure
+flow_system.topology.plot(path='system.html')
+
+# Run optimization
+flow_system.optimize(fx.solvers.HighsSolver())
 ```
 
-### 6. Save Results
+### 6. Access and Visualize Results
 
 ```python
-# This includes the modeled FlowSystem. SO you can restore both results and inputs
-optimization.results.to_file()
+# Access raw solution data
+print(flow_system.solution)
+
+# Use statistics for aggregated data
+print(flow_system.statistics.flow_hours)
+
+# Access component-specific results
+print(flow_system.components['battery'].solution)
+
+# Visualize results
+flow_system.statistics.plot.balance('electricity')
+flow_system.statistics.plot.storage('battery')
+```
+
+### 7. Save Results (Optional)
+
+```python
+# Save the flow system (includes inputs and solution)
+flow_system.to_netcdf('results/solar_battery.nc')
+
+# Load it back later
+loaded_fs = fx.FlowSystem.from_netcdf('results/solar_battery.nc')
 ```
 
 ## What's Next?
 
 Now that you've created your first model, you can:
 
 - **Learn the concepts** - Read the [Core Concepts](../user-guide/core-concepts.md) guide
-- **Explore examples** - Check out more [Examples](../examples/index.md)
+- **Explore examples** - Check out more [Examples](../notebooks/index.md)
 - **Deep dive** - Study the [Mathematical Formulation](../user-guide/mathematical-notation/index.md)
 - **Build complex models** - Use [Recipes](../user-guide/recipes/index.md) for common patterns
 
@@ -120,8 +142,10 @@ Most flixOpt projects follow this pattern:
 2. **Create flow system** - Initialize with time series and effects
 3. **Add buses** - Define connection points
 4. **Add components** - Create generators, storage, converters, loads
-5. **Run optimization** - Solve the optimization
-6. **Save Results** - For later analysis. Or only extract needed data
+5. **Verify structure** - Use `flow_system.topology.plot()` to visualize
+6. **Run optimization** - Call `flow_system.optimize(solver)`
+7. **Analyze results** - Via `flow_system.statistics` and `.solution`
+8. **Visualize** - Use `flow_system.statistics.plot.*` methods
 
 ## Tips
 

diff --git a/docs/index.md b/docs/index.md
@@ -14,7 +14,7 @@ title: Home
 
 <p class="hero-buttons">
   <a href="home/installation/" class="md-button md-button--primary">🚀 Get Started</a>
-  <a href="examples/" class="md-button">💡 View Examples</a>
+  <a href="notebooks/" class="md-button">💡 View Examples</a>
   <a href="https://github.com/flixOpt/flixopt" class="md-button" target="_blank" rel="noopener noreferrer">⭐ GitHub</a>
 </p>
 
@@ -30,7 +30,7 @@ title: Home
 
     New to FlixOpt? Start here with installation and your first model
 
-- :bulb: **[Examples Gallery](examples/)**
+- :bulb: **[Examples Gallery](notebooks/)**
 
     ---
-Original file line number
+Diff line change
@@ Expand Up / @@ -4,7 +4,7 @@ flixOpt is released under the MIT License. @@
     ## MIT License
-    ```
+    ```text
     MIT License
     Copyright (c) 2022 Chair of Building Energy Systems and Heat Supply - TU Dresden
@@ Expand Down @@