diff --git a/README.md b/README.md
index 32d8346..b71192a 100644
--- a/README.md
+++ b/README.md
@@ -1,22 +1,11 @@
-JupyterHub Notebook Viewer
+# JupyterHub Notebook Viewer
 
 A Flask-based web application for viewing and browsing Jupyter notebooks from a JupyterHub shared directory. Features a responsive web interface with directory navigation, notebook preview, and download capabilities.
-Features
 
-    📁 Directory Navigation - Browse through nested directories with breadcrumb navigation
-    📄 Notebook Viewing - Convert and display Jupyter notebooks as HTML in the browser
-    ⬇️ Download Support - Direct download of notebook files
-    🎨 Responsive Design - Bootstrap-based UI that works on desktop and mobile
-    🔒 Security - Path traversal protection and configurable access controls
-    🛠️ Configurable - All settings configurable via environment variables
-    🐳 Docker Support - Ready-to-use Docker containers and compose files
-    ❄️ Nix Development - Complete Nix flake for reproducible development
-
-Quick Start
+## Quick Start
 Using Nix (Recommended)
 
-bash
-
+```bash
 # Enter development environment
 nix develop
 
@@ -26,20 +15,22 @@ setup-dev
 # Start development server
 dev-server
 
+```
+
 Using Docker
 
-bash
-
+```bash
 # Copy and configure environment
 cp .env.example .env
 # Edit .env with your settings
 
 # Start with Docker Compose
 docker-compose up
+```
 
 Manual Installation
 
-bash
+```bash
 
 # Install dependencies
 pip install -r requirements.txt
@@ -50,8 +41,9 @@ cp .env.example .env
 
 # Start the application
 python app.py
+```
 
-Configuration
+## Configuration
 
 All configuration is done via environment variables, typically in a .env file:
 Core Settings
@@ -81,12 +73,12 @@ UI Settings
 
     THEME - UI theme, dark or light (default: dark)
 
-Development
+## Development
 With Nix
 
 The project includes a complete Nix flake for reproducible development:
 
-bash
+```bash
 
 # Enter development shell
 nix develop
@@ -95,12 +87,13 @@ nix develop
 setup-dev     # Set up development environment
 dev-server    # Start development server with auto-reload
 run-tests     # Run basic tests
+```
 
 With Just
 
 If you have just installed:
 
-bash
+```bash
 
 # See all available commands
 just
@@ -111,10 +104,11 @@ just dev             # Start development server
 just docker-up       # Start with Docker
 just test            # Run tests
 just clean           # Clean temporary files
+```
 
 Manual Development
 
-bash
+```bash
 
 # Install dependencies
 pip install -r requirements.txt
@@ -128,12 +122,12 @@ mkdir -p shared
 
 # Start development server
 python app.py
+```
 
 Docker Deployment
 Basic Deployment
 
-bash
-
+```bash
 # Build and start
 docker-compose up --build
 
@@ -142,17 +136,20 @@ docker-compose up -d
 
 # View logs
 docker-compose logs -f
+```
 
 With Reverse Proxy
 
 The compose file includes an optional nginx reverse proxy:
 
-bash
+
+```bash
 
 # Start with proxy
 docker-compose --profile with-proxy up
+```
 
-Production Considerations
+## Production Considerations
 
 For production deployment:
 
@@ -162,7 +159,7 @@ For production deployment:
     Set up SSL: Configure HTTPS in your reverse proxy
     Resource limits: Set appropriate CPU and memory limits in Docker
 
-API Endpoints
+## API Endpoints
 
 When ENABLE_API=True, the following JSON API endpoints are available:
 
@@ -171,14 +168,8 @@ When ENABLE_API=True, the following JSON API endpoints are available:
     GET /view/<path> - View notebook as HTML
     GET /download/<path> - Download notebook file (if enabled)
 
-Security Features
 
-    Path Traversal Protection - Prevents access outside the configured directory
-    File Type Validation - Only allows configured file extensions
-    Configurable Downloads - Downloads can be disabled entirely
-    Non-root Docker User - Container runs as non-privileged user
-
-Troubleshooting
+## Troubleshooting
 Common Issues
 
     "No notebooks found"
@@ -193,44 +184,15 @@ Common Issues
         Ensure the application has read access to the shared directory
         Check Docker volume mounts
 
-Logs
+## Logs
 
 Application logs are printed to stdout. In Docker:
 
-bash
-
+```bash
 docker-compose logs -f notebook-viewer
+```
 
-Contributing
-
-    Fork the repository
-    Enter the development environment: nix develop
-    Make your changes
-    Run tests: run-tests
-    Submit a pull request
-
-License
+## License
 
 MIT License - see LICENSE file for details.
 Architecture
-
-┌─────────────────────────────────────────────────────────────┐
-│                     Web Browser                             │
-└─────────────────────┬───────────────────────────────────────┘
-                      │ HTTP
-┌─────────────────────▼───────────────────────────────────────┐
-│                  Flask App                                  │
-│  ┌─────────────┐ ┌──────────────┐ ┌─────────────────────┐   │
-│  │   Routes    │ │  Templates   │ │    Static Assets    │   │
-│  └─────────────┘ └──────────────┘ └─────────────────────┘   │
-└─────────────────────┬───────────────────────────────────────┘
-                      │ File System
-┌─────────────────────▼───────────────────────────────────────┐
-│              JupyterHub Shared Directory                    │
-│  ┌─────────────┐ ┌──────────────┐ ┌─────────────────────┐   │
-│  │ Notebooks   │ │ Directories  │ │   Other Files       │   │
-│  │ (.ipynb)    │ │              │ │   (.py, .md)        │   │
-│  └─────────────┘ └──────────────┘ └─────────────────────┘   │
-└─────────────────────────────────────────────────────────────┘
-
-