diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..b54c901 --- /dev/null +++ b/.gitignore @@ -0,0 +1,17 @@ +# Site-specific credentials and deployment overrides. +/cms/config.local.php + +# Runtime CMS state; retain only the web-access guards committed below. +/cms/data/* +!/cms/data/.htaccess +!/cms/data/index.php +/cms/logs/* +!/cms/logs/.htaccess +!/cms/logs/index.php + +# Uploaded content belongs to the deployed site rather than source control. +/uploads/* +!/uploads/.htaccess +!/uploads/index.php + +# Generated security-audit reports are retained deliberately and should remain visible to Git. diff --git a/README.md b/README.md index ec32df0..7f38781 100644 --- a/README.md +++ b/README.md @@ -1,52 +1,270 @@ # NeoCMS -## Version 2.0 +## Version 3.0 -Welcome to NeoCMS, the super lightweight, database-free content management system! Built with PHP and JavaScript, NeoCMS -is designed to be fast and easy to use. No complicated setup required—just drop it into your static website, and you’re -good to go. +Welcome to NeoCMS, the lightweight, database-free content management system. Built with PHP and JavaScript, NeoCMS is +designed to add controlled visual editing to an existing static website without changing how public pages are served. -Version 2.0 is a complete overhaul to support the latest versions of jQuery and TinyMCE (GPL). We’ve made things even -smoother for your content editing experience. +Version 3.0 adds filesystem-backed drafts, revision history, role-based permissions, scheduled publishing, page and media +management, SEO controls, shared content, navigation menus, responsive previews, accessibility checks, and an operational +dashboard. Public content remains ordinary HTML; the database server may continue its well-earned rest. + +Further technical documentation: + +* [Architecture](docs/ARCHITECTURE.md) +* [Development and testing](docs/DEVELOPMENT.md) ## Features * No Database Required: NeoCMS works without a database, so you don’t have to worry about setup hassles or performance slowdowns. -* Easy Content Editing: With our intuitive WYSIWYG editor, anyone can update content without writing a single line of - code. Adding the additional class *neo-dupe* will allow an element and it's children to be cloned. +* Easy Content Editing: The TinyMCE visual editor updates marked content regions without requiring authors to edit HTML. + Adding `neo-dupe` allows an element and its children to be cloned or removed. * Seamless Integration: Simply add the CMS to any existing static website. Just assign a special class to the elements you want to make editable, and you’re all set. * Consistent Layouts: NeoCMS supports page templates to keep your layouts neat and uniform across all pages. +* Drafts and Publishing: Editors can save drafts without changing the public page. Publishers can publish immediately or + schedule a publication. +* Revision History: Every changed or deleted page receives a timestamped filesystem snapshot that publishers can restore. +* Page Management: Search, create, duplicate, rename, and delete editable HTML pages, including pages in subdirectories. +* Media Library: Browse uploaded images, reuse them, maintain alternative text, see usage counts, and remove files. +* SEO Settings: Edit the page title, description, canonical URL, Open Graph image, and robots indexing setting. +* Shared Content: Mark content with `data-neo-shared="name"` and update matching regions across the site. +* Navigation Menus: Build ordered and nested navigation markup and insert it into an editable region. +* Responsive Preview: Preview the current page at desktop, tablet, and mobile widths. +* Accessibility Checks: Check common authoring problems such as missing alt text, empty links, heading jumps, missing labels, + and absent page metadata before publishing. +* Roles and Activity: Use editor, publisher, and administrator roles. The dashboard displays drafts, schedules, system + problems, and recent activity. ## Installation Guide -Ready to get started? Just follow these simple steps: +To install NeoCMS: -* Drop the CMS folder into your static website. -* Add the uploads folder to your site as well. -* Open /cms/config.php and edit the credentials for any users you want to set up. -* Update the div elements you want to make editable by adding the class editable. -* Visit /cms/, log in, and start editing! +* Place the `cms/` directory in the document root of the static website. +* Place the `uploads/` directory in the same document root. +* Copy `cms/config.local.php.example` to `cms/config.local.php`, add password hashes, and assign roles. +* Update the elements you want to make editable by adding the configured editable class. It is `editable` by default. +* Confirm that PHP may write to the managed HTML files, `cms/data/`, `cms/logs/`, and `uploads/`. +* Visit `/cms/`, log in, and begin editing. That’s it! You’re up and running. +## Configuration + +Tracked defaults live in `cms/config.php`. Deployment credentials and overrides belong in the Git-ignored +`cms/config.local.php`, which must return an array. The supplied Apache rules deny direct access to both files. + +| Setting | Type | Purpose | +| --- | --- | --- | +| `authentication` | array | Maps usernames to `password_hash()` values; plaintext credentials are rejected. | +| `roles` | array | Maps usernames to `editor`, `publisher`, or `administrator`. | +| `security` | array | Configures session expiry, login throttling, request limits, storage quotas, and audit-log retention. | +| `uploads` | array | Configures image size, dimension, file-count, and aggregate-storage limits. | +| `audit` | boolean | Enables daily activity logs under `cms/logs/`. | +| `skipWelcomePage` | boolean | Opens the public root instead of the built-in guide after login. | +| `showFullUrl` | boolean | Displays the current page path in the toolbar. | +| `editableClass` | string | Selects the single CSS class used to identify editable regions. | + +`dataDirectory` is an internal override used by the integration suite and specialised deployments. Normal installations +should allow NeoCMS to use `cms/data/`. + +### Editable Class + +The class used to identify editable regions is configurable: + +```php +'editableClass' => 'editable', +``` + +Set it to any single valid CSS class name without a leading dot, for example: + +```php +'editableClass' => 'cms-content', +``` + +Your page markup must then use that class: + +```html +
This region can be edited.
+``` + +Invalid configured values fall back to `editable`. The `neo-dupe` class remains fixed because it marks repeatable blocks, +not general editable content. When overriding `editableClass`, update the classes in `cms/templates/` as well so newly +created pages are immediately discoverable by the page picker. + +### Users and Roles + +Passwords must be generated with `password_hash()` and stored under `authentication` in `cms/config.local.php`. Assign the +same username a role under `roles`: + +```php +'authentication' => [ + 'author' => '$2y$10$...', + 'publisher' => '$2y$10$...', +], +'roles' => [ + 'author' => 'editor', + 'publisher' => 'publisher', +], +``` + +* `editor`: edit content, save drafts, and upload media. +* `publisher`: editor permissions plus immediate and scheduled publishing and revision restoration. +* `administrator`: publisher permissions plus page, media, shared-content, and menu management. + +Users without an explicit valid role receive `editor`, the least powerful role. Account removal, password-hash changes, +and role changes affect active sessions on their next request. Sessions expire after 30 minutes of inactivity and 12 hours +in total by default. + +When HTTPS terminates at a trusted reverse proxy, set `'cookieSecure' => true` beneath `security` in the local override. +This keeps the session cookie marked Secure even when PHP receives the proxy's internal HTTP request. + +Audit files rotate at 10 MiB and are retained for 90 days by default. Override `auditMaxFileBytes` and +`auditRetentionDays` beneath `security` where local retention obligations differ. + +### Password Hash Example + +Generate a hash on a trusted command line, then place only the resulting hash in `cms/config.local.php`: + +```bash +php -r 'echo password_hash(trim(fgets(STDIN)), PASSWORD_DEFAULT), PHP_EOL;' +``` + +There is deliberately no enabled default account. + +## Content Features + +### Repeatable Blocks + +Add `neo-dupe` alongside the configured editable class. The editor provides clone-before, clone-after, and delete controls: + +```html +
Repeatable content
+``` + +### Shared Content + +Use `data-neo-shared` to identify a global region: + +```html + +``` + +The Shared Content tool updates every HTML page containing the same key. Publishing a page also captures the current value +of its shared regions. + +### Navigation Menus + +Menu items use one line each in this format: + +```text +Home | / +About | /about.html +Team | /team.html | About +``` + +The optional third value is the label of the parent item. After saving, the generated `