E.Noorlander/CodePress
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Fix guide template variable replacement and enhance documentation

Browse Source 
- Fix template variable replacement in guide pages by removing {{}} brackets
- Escape code blocks in guide markdown to prevent template processing
- Completely rewrite guide documentation with comprehensive CMS features
- Add bilingual guide support (English/Dutch) with detailed examples
- Enhance CodePressCMS core with improved guide page handling
- Update template system with better layout and footer components
- Improve language files with additional translations
- Update configuration with enhanced theme and language settings

Resolves issue where guide pages were showing replaced template variables
instead of displaying them as documentation examples.
This commit is contained in:
Edwin Noorlander
2025-11-26 16:50:49 +01:00
parent f5ac28a74e
commit 9c5a43c5ce
17 changed files with 1684 additions and 462 deletions
Download Patch File Download Diff File Expand all files Collapse all files

462
guide/en.codepress.md
View File

@@ -1,191 +1,68 @@
# CodePress CMS Guide
## Welcome to CodePress CMS
## Welcome to CodePress
CodePress is a lightweight, file-based Content Management System built with PHP and Bootstrap.
### Table of Contents
## Features
1. [Getting Started](#getting-started)
2. [Content Management](#content-management)
3. [Templates](#templates)
4. [Configuration](#configuration)
### 🏠 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
- Active state marking
---
### 📄 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
## Getting Started
### 🔍 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`
### Requirements
- PHP 8.4+
- Web server (Apache/Nginx)
- Modern web browser
- Write permissions for content directory
### 🧭 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
### Installation
1. Clone or download the CodePress files
### 🎨 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
## Installation
1. Clone or download CodePress files
2. Upload to your web server
3. Make sure the `content/` directory is writable
4. Navigate to your website in the browser
3. Make sure `content/` directory is writable
4. Navigate to your website in browser
### Basic Configuration
The most important settings are in `engine/core/config.php`:
```php
$config = [
'site_title' => 'My Website',
'default_page' => 'home',
'content_dir' => __DIR__ . '/../../content',
'templates_dir' => __DIR__ . '/../templates'
];
```
---
## Content Management {#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
CodePress supports four 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>
```
#### Directory Listings
Directories automatically generate listings:
- File information (size, dates)
- Navigation to subdirectories
- Responsive file listing layout
#### PHP (`.php`)
```php
<?php
$title = "Dynamic Page";
?>
<h1><?php echo $title; ?></h1>
<p>This is dynamic content with PHP.</p>
```
#### HTML (`.html`)
```html
<h1>HTML Page</h1>
<p>This is static HTML content.</p>
```
### Automatic Linking
CodePress automatically creates links to other pages when you mention page names in your content.
### Language Support
- **Browser detection**: Automatic language detection
- **URL switching**: `?lang=en` or `?lang=nl`
- **Language prefixes**: `en.page.md` and `nl.page.md`
- **Translation files**: `lang/en.php` and `lang/nl.php`
### Search Functionality
- **Full-text search**: Search through all content
- **Search URL**: `?search=query` for bookmarkable searches
- **Result highlighting**: Search terms highlighted in results
- **File and content search**: Searches both filenames and content
---
## Templates {#templates}
### Template Structure
CodePress uses Mustache-compatible templates:
- `layout.mustache` - Main template
- `assets/header.mustache` - Header component
- `assets/sidebar.mustache` - Sidebar navigation
- `assets/footer.mustache` - Footer component
### Template Variables
Available variables in templates:
#### **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 the homepage?
#### **Navigation**
- `{{menu}}` - Navigation menu
- `{{breadcrumb}}` - Breadcrumb navigation
- `{{homepage}}` - Homepage link
- `{{homepage_title}}` - Homepage title
#### **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)
- `{{available_langs}}` - Available languages
- `{{t_*}}` - Translated strings (t_home, t_search, etc.)
#### **SEO**
- `{{seo_description}}` - Meta description
- `{{seo_keywords}}` - Meta keywords
#### **Features**
- `{{has_content}}` - Boolean: is content available?
- `{{show_site_link}}` - Boolean: show site link?
- `{{is_guide_page}}` - Boolean: is this the guide page?
---
## Configuration {#configuration}
## Configuration
### Basic Settings
Edit `config.json` in your project root:
```json
\`\`\`json
{
"site_title": "Your Website Name",
"content_dir": "content",
@@ -199,12 +76,13 @@ Edit `config.json` in your project root:
"header_color": "#0a369d",
"header_font_color": "#ffffff",
"navigation_color": "#2754b4",
"navigation_font_color": "#ffffff"
"navigation_font_color": "#ffffff",
"sidebar_background": "#f8f9fa",
"sidebar_border": "#dee2e6"
},
"author": {
"name": "Your Name",
"website": "https://yourwebsite.com",
"git": "https://github.com/youruser/codepress"
"website": "https://yourwebsite.com"
},
"seo": {
"description": "Your website description",
@@ -216,70 +94,232 @@ Edit `config.json` in your project root:
"breadcrumbs_enabled": true
}
}
```
\`\`\`
### SEO Friendly URLs
CodePress automatically generates clean URLs:
- `home.md` → `?page=home`
- `blog/article.md` → `?page=blog/article`
- `nl.page.md` → `?page=nl.page&lang=nl`
## Content Management
### Language Support
- **Browser detection**: Automatic language detection
- **URL switching**: `?lang=en` or `?lang=nl`
### 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`
- **Directory precedence**: Directories take precedence over files
- **Display names**: `file-name.md` displays as "File Name" in menus
### Search Functionality
The built-in search function searches through:
- File names
- Content of Markdown/PHP/HTML files
- Search URL: `?search=query` for bookmarkable searches
- Result highlighting and snippets
## Templates
### Directory Listings
- **Auto-generation**: `?page=directory` shows directory contents
- **File information**: Creation/modification dates and sizes
- **Navigation**: Links to files and subdirectories
### 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`
- Directory names take precedence over files with same name
### File Naming Conventions
- **Lowercase names**: Use lowercase for all files
- **No spaces**: Use hyphens (-) or underscores (_)
- **Language prefixes**: `en.` or `nl.` for multilingual content
- **Display names**: `file-name.md` displays as "File Name" in menus
- **Special cases**: `phpinfo` → "phpinfo", `ict` → "ICT"
### Content Optimization
- Use clear headings (H1, H2, H3)
- Add descriptive meta information
- Use internal links for better navigation
### Security
- Keep your CodePress installation updated
- Restrict write permissions on the `content/` directory
- Use HTTPS when possible
## Troubleshooting
---
### Common Issues
## Support
### Troubleshooting
- **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