CodePress/guide/en.codepress.md

# CodePress CMS Guide

## Welcome to CodePress

CodePress is a lightweight, file-based Content Management System built with PHP and Bootstrap.

## Features

### 🏠 Navigation
- Tab-style navigation with Bootstrap styling
- Dropdown menus for folders and sub-folders
- Home button with icon
- Automatic menu generation
- Responsive design
- Breadcrumb navigation with sidebar toggle
- Active state marking
- **Sidebar toggle** - Button placed left of HOME in the breadcrumb to open/close the sidebar. The icon changes between open and closed state. The choice is preserved during the session

### 📄 Content Types
- **Markdown (.md)** - CommonMark support
- **PHP (.php)** - Dynamic content
- **HTML (.html)** - Static HTML pages
- **Directory listings** - Automatic directory overviews
- **Language-specific content** - `en.` and `nl.` prefixes

### 🔍 Search Functionality
- Full-text search through all content
- Results with snippets and highlighting
- Direct navigation to found pages
- SEO-friendly search results
- Search URL: `?search=query`

### 🧭 Configuration
- **JSON configuration** in `config.json`
- Dynamic homepage setting
- SEO settings (description, keywords)
- Author information with links
- Theme configuration with colors
- Language settings
- Feature toggles

### 🎨 Layout & Design
- Flexbox layout for responsive structure
- Fixed header with logo and search
- Breadcrumb navigation
- Fixed footer with file info and links
- Bootstrap 5 styling
- Mustache templates
- Semantic HTML5 structure
- **Dynamic layouts** with YAML frontmatter
- **Sidebar support** with plugin integration and toggle function via breadcrumb

## Installation

1. Clone or download CodePress files
2. Upload to your web server
3. Make sure `content/` directory is writable
4. Navigate to your website in browser

## Configuration

### Basic Settings

Edit `config.json` in your project root:

\`\`\`json
{
    "site_title": "Your Website Name",
    "content_dir": "content",
    "templates_dir": "engine/templates",
    "default_page": "auto",
    "language": {
        "default": "en",
        "available": ["en", "nl"]
    },
    "theme": {
        "header_color": "#0a369d",
        "header_font_color": "#ffffff",
        "navigation_color": "#2754b4",
        "navigation_font_color": "#ffffff",
        "sidebar_background": "#f8f9fa",
        "sidebar_border": "#dee2e6"
    },
    "author": {
        "name": "Your Name",
        "website": "https://yourwebsite.com"
    },
    "seo": {
        "description": "Your website description",
        "keywords": "cms, php, content management"
    },
    "features": {
        "auto_link_pages": true,
        "search_enabled": true,
        "breadcrumbs_enabled": true
    }
}
\`\`\`

## Content Management

### File Structure

\`\`\`
content/
├── home.md              # Home page
├── blog/
│   ├── index.md         # Blog overview
│   ├── article-1.md     # Blog article
│   └── category/
│       └── article.md   # Article in category
└── about-us/
    └── info.md          # About us page
\`\`\`

### Content Types

#### Markdown (`.md`)
\`\`\`markdown
# Page Title

This is page content in **Markdown** format with CommonMark extensions.

## Subsection

- [x] Task list item
- [ ] Another task
- **Bold** and *italic* text
- [Auto-linked pages](?page=another-page)
\`\`\`

#### PHP (`.php`)
\`\`\`php
<?php
$title = "Dynamic Page";
?>
<h1><?php echo htmlspecialchars($title); ?></h1>
<p>This is dynamic content with PHP.</p>
\`\`\`

#### HTML (`.html`)
\`\`\`html
<h1>HTML Page</h1>
<p>This is static HTML content.</p>
\`\`\`

### File Naming Conventions

- **Lowercase names**: Use lowercase for all files
- **No spaces**: Use hyphens (-) or underscores (_)
- **Language prefixes**: `en.page.md` and `nl.page.md`
- **Display names**: `file-name.md` displays as "File Name" in menus

## Templates

### Template Variables

#### Site Info
- `site_title` - Website title
- `author_name` - Author name
- `author_website` - Author website
- `author_git` - Git repository link

#### Page Info
- `page_title` - Page title (filename without extension)
- `content` - Page content (HTML)
- `file_info` - File information (dates, size)
- `is_homepage` - Boolean: is this homepage?

#### Navigation
- `menu` - Navigation menu
- `breadcrumb` - Breadcrumb navigation
- `homepage` - Homepage link

#### Theme
- `header_color` - Header background color
- `header_font_color` - Header text color
- `navigation_color` - Navigation background color
- `navigation_font_color` - Navigation text color

#### Language
- `current_lang` - Current language (en/nl)
- `current_lang_upper` - Current language (EN/NL)
- `t_*` - Translated strings

## URL Structure

### Basic URLs
- **Home**: `/` or `?page=home`
- **Page**: `?page=blog/article`
- **Search**: `?search=query`
- **Guide**: `?guide`
- **Language**: `?lang=en` or `?lang=nl`

## SEO Optimization

### Meta Tags

The CMS automatically adds meta tags:

\`\`\`html
<meta name="generator" content="CodePress CMS">
<meta name="application-name" content="CodePress">
<meta name="author" content="Your Name">
<meta name="description" content="...">
<meta name="keywords" content="...">
<link rel="author" href="https://yourwebsite.com">
<link rel="me" href="https://github.com/youruser/codepress">
\`\`\`

## 🔌 Plugin System

### Plugin Structure

\`\`\`
plugins/
├── README.md                    # Plugin documentation
├── HTMLBlock/
│   ├── HTMLBlock.php            # Plugin class
│   └── README.md               # Plugin specific documentation
└── MQTTTracker/
    ├── MQTTTracker.php         # Plugin class
    ├── config.json             # Plugin configuration
    └── README.md               # Plugin documentation
\`\`\`

### Plugin Development

- **API access** via `CMSAPI` class
- **Sidebar content** with `getSidebarContent()`
- **Metadata access** from YAML frontmatter
- **Configuration** via JSON files
- **Event hooks** for extension

### Available Plugins

- **HTMLBlock** - Custom HTML blocks in sidebar
- **MQTTTracker** - Real-time analytics and tracking

## 🎯 Template System

### Layout Options

Use YAML frontmatter to select layout:

\`\`\`yaml
---
title: My Page
layout: sidebar-content
---
\`\`\`

### Available Layouts

- `sidebar-content` - Sidebar left, content right (default)
- `content` - Content only (full width)
- `sidebar` - Sidebar only
- `content-sidebar` - Content left, sidebar right
- `content-sidebar-reverse` - Content right, sidebar left

### Meta Data

\`\`\`yaml
---
title: Page Title
layout: content-sidebar
description: Page description
author: Author Name
date: 2025-11-26
---
\`\`\`

## 📊 Analytics & Tracking

### MQTT Tracker

- Real-time page tracking
- Session management
- Business Intelligence data
- Privacy aware (GDPR compliant)
- MQTT integration for dashboards

### Data Format

\`\`\`json
{
    "timestamp": "2025-11-26T15:30:00+00:00",
    "session_id": "cms_1234567890abcdef",
    "page_url": "?page=demo/sidebar-content&lang=en",
    "page_title": "Sidebar-Content Layout",
    "language": "en",
    "layout": "sidebar-content"
}
\`\`\`

## Tips and Tricks

### Page Organization

- Use subdirectories for categories
- Give each directory an `index.md` for an overview page
- Keep file names short and descriptive
- Use language prefixes: `en.page.md` and `nl.page.md`

### Content Optimization

- Use clear headings (H1, H2, H3)
- Add descriptive meta information
- Use internal links for better navigation

## Troubleshooting

### Common Issues

- **Empty pages**: Check file permissions
- **Template errors**: Verify template syntax
- **404 errors**: Check file names and paths
- **Navigation not updated**: Reload the page

## Support

### More Information

- Documentation: [CodePress GitHub](https://git.noorlander.info/E.Noorlander/CodePress.git)
- Issues and feature requests: GitHub Issues

---

*This guide is part of CodePress CMS and is automatically displayed when no content is available.*