CodePress/README.en.md

# CodePress CMS

**[🇳🇱 Dutch](README.md) | [🇬🇧 English](#)**

A lightweight, file-based content management system built with PHP (≥8.0).

**Version:** 2.5.1 | **License:** AGPL v3 / Commercial

## ✨ Features

- 📝 **Multi-format Content** - Markdown, PHP and HTML files
- 🧭 **Dynamic Navigation** - Automatic menu generation
- 🌍 **Multi-language** - NL/EN/DE/FR support
- 🔍 **Search** - Full-text search
- 📱 **Responsive** - Bootstrap 5 themes
- 🔒 **Security** - 100/100 pentest score
- 🛡️ **Admin Console** - CodeMirror editor, media management, themes, plugins
- 👥 **User Roles** - Admin, Content Manager, BI Manager, Site Admin
- 📊 **Analytics** - Visitor statistics with GeoIP
- 🤖 **BotGuard** - Bot/AI protection
- 📈 **Logging** - Comprehensive logging system
- 🔌 **Plugin System** - Sidebar plugins with own CSS/SCSS, Twig templates

## 🚀 Quick Start

```bash
# Install dependencies
composer install

# Start server with router for clean URLs
php -S localhost:8080 cms/router.php
```

**Website:** `http://localhost:8080`  
**Admin:** `http://localhost:8080/admin` (login: `admin` / `admin`)

## 📚 Documentation

See **[guide/](guide/)** for extensive documentation per role:

| Role | Guide |
|------|-------|
| 📝 Content Editor | [Content Manager](guide/en/content-beheerder.md) |
| ⚙️ Administrator | [Admin Manager](guide/en/admin-beheerder.md) |
| 🎨 Theme Developer | [Theme Developer](guide/en/theme-developer.md) |
| 💻 Developer | [CodePress Developer](guide/en/codepress-developer.md) |

Each guide has sub-topics in separate folders with sidebar navigation.

## 👥 User Roles

| Role | Permissions |
|------|------------|
| **Admin** | Full access (everything) |
| **Content Manager** | Content management, guide |
| **BI Manager** | Statistics, logs, guide |
| **Site Admin** | Theme, plugins, statistics, logs, update, guide |

## 📁 Project Structure

```
codepress/
├── cms/                        # Core CMS engine
│   ├── core/class/             # CMS classes (CodePressCMS, ThemeManager, etc.)
│   ├── core/plugin/            # Plugin system (PluginManager, CMSAPI)
│   ├── lang/                   # Translation files (nl.php, en.php)
│   └── router.php              # PHP dev server router (clean URLs)
├── admin/                      # Admin console
│   ├── config/                 # Admin configuration (admin.json)
│   ├── src/AdminAuth.php       # Authentication, roles, permissions
│   ├── storage/                # Logs, cache, geoip
│   └── theme/default/          # Admin theme
│       ├── assets/             # CSS, JS, fonts, codemirror
│       ├── views/              # Twig templates (layouts, pages)
│       └── theme.json          # Admin theme configuration
├── themes/                     # Website themes
│   ├── default/                # Default theme
│   │   ├── theme.json          # Layout mapping, colors
│   │   ├── base.twig          # Main layout
│   │   ├── *.twig             # Layout templates
│   │   ├── partials/           # Header, navigation, footer
│   │   └── assets/            # SCSS, CSS, JS, img
│   └── demo/                  # Demo theme
├── plugins/                    # Plugins
│   ├── HTMLBlock/              # Example sidebar plugin
│   └── Navigation/            # Essential navigation plugin (protected)
│       ├── Navigation.php      # Plugin code
│       ├── plugin.json         # Plugin metadata
│       ├── assets/scss/        # Plugin SCSS source
│       └── assets/css/         # Plugin CSS
├── content/                    # Website content (.md, .php, .html)
├── public/                     # Web root
│   ├── index.php               # Website entry point
│   └── admin.php               # Admin entry point + routing
├── guide/                      # Documentation (nl/en)
│   ├── nl/                     # Dutch guides
│   └── en/                     # English guides
├── cli/test/                   # Test suites
├── var/                        # Cache (twig)
├── config.json                 # Site configuration
├── composer.json               # PHP dependencies
└── version.php                 # Version information
```

## ⚙️ Configuration

### config.json

```json
{
    "site_title": "CodePress",
    "active_theme": "default",
    "default_page": "auto",
    "language": {
        "default": "nl",
        "available": ["nl", "en"]
    },
    "enabled_plugins": ["HTMLBlock", "Navigation"],
    "features": {
        "search_enabled": true,
        "breadcrumbs_enabled": true
    },
    "security": {
        "block_ai_bots": true,
        "rate_limit_enabled": true
    },
    "analytics": { "enabled": true },
    "logging": { "enabled": true }
}
```

## 🔧 Dependencies

- **PHP ≥8.0** with extensions: json, mbstring
- **Composer** packages:
  - twig/twig (templating)
  - scssphp/scssphp (SCSS compilation)
  - league/commonmark (Markdown with HeadingPermalinks)
  - maxmind-db/reader (GeoIP)

## 🔐 Security

- ✅ XSS prevention (htmlspecialchars)
- ✅ CSRF tokens (admin forms)
- ✅ Path traversal prevention (realpath checks)
- ✅ Secure cookies (HttpOnly, SameSite)
- ✅ Security headers (X-Frame-Options, CSP)
- ✅ Bot/AI protection (BotGuard)
- ✅ Rate limiting per IP
- ✅ Role-based access control (RBAC)

## 🔌 Plugins

### Plugin structure

```
plugins/MyPlugin/
├── MyPlugin.php             # Plugin code (name = plugin name)
├── plugin.json              # Plugin metadata
├── assets/scss/            # Plugin SCSS source
└── assets/css/             # Plugin CSS (after compilation)
```

### Essential plugins

The **Navigation** plugin is an essential plugin and cannot be disabled, edited, or deleted. This plugin automatically generates sidebar navigation for guides and content.

### Plugin CSS

Plugin CSS is automatically loaded after theme CSS, so themes can override plugin styling.

## 📝 Content Examples

### Markdown with frontmatter

```markdown
---
layout: full_content
plugins: HTMLBlock, Navigation
---

# Page title

Content in Markdown format...
```

### PHP content

```php
<?php
/** @var ContentAPI $api */
$pages = $api->getAllPages();
echo "<h1>My Page</h1>";
echo "<p>Number of pages: " . count($pages) . "</p>";
```

## 🧪 Testing

```bash
# Penetration tests
cli/test/pentest/security-test.sh

# Accessibility tests (WCAG 2.1 AA)
cli/test/accessibility.sh

# Functional tests
cli/test/functional/*.sh
```

## 📞 Support

- **Documentation:** [guide/](guide/)
- **Issues:** Git repository
- **Contact:** commercial@noorlander.info

## 📄 License

**Dual-licensed:**

- **AGPL v3** - For open-source projects
- **Commercial** - For proprietary use

See [LICENSE](LICENSE) for details.

---

**CodePress CMS** - Built by E.Noorlander / CodePress Development Team