135 lines
4.8 KiB
Markdown
135 lines
4.8 KiB
Markdown
# PnP Development Guidelines
|
|
|
|
## Philosophy
|
|
|
|
**Just enough, nothing more.** This framework applies minimal PHP to enable modern conveniences while remaining maintainable for years or decades. Avoid rapidly changing components and dependencies. The code should be readable, simple, and strictly necessary.
|
|
|
|
## Core Principles
|
|
|
|
### Minimalism
|
|
- Use only what is strictly necessary to achieve the goal
|
|
- No frameworks, no build tools, no package managers for frontend code
|
|
- Avoid abstractions unless they provide clear, lasting value
|
|
- Sparse commenting—only mark main sections
|
|
|
|
### Technology Stack
|
|
- **Allowed:** HTML, PHP (8.3+), CSS
|
|
- **Not allowed:** JavaScript
|
|
- Use modern PHP features when they improve readability or performance
|
|
- Leverage modern CSS features for smart, efficient styling
|
|
|
|
### File-Based Routing
|
|
- Folder hierarchy dictates URL structure
|
|
- Drop a file (`.md`, `.php`, `.html`) in a folder and it renders immediately
|
|
- Assets placed in content directories are automatically accessible
|
|
- Frontpage is handled by `/content/frontpage.php`
|
|
- Directories with subfolders trigger list views
|
|
|
|
### Template System
|
|
- Custom templates override defaults (never modify defaults)
|
|
- Custom templates live in `/app/custom/`
|
|
- Default templates provide fallback behavior
|
|
- Docs get their own template variants for specialized presentation
|
|
- Templates use PHP includes—simple and straightforward
|
|
|
|
### Content Conventions
|
|
|
|
#### File Naming
|
|
- Page files: `page.php`, `page.html`, `page.md`
|
|
- Single/article files: `article.md`, `post.md`, `single.md` (and `.php`/`.html` variants)
|
|
- Index overrides: `index.php` in any directory takes precedence
|
|
- Cover images: `cover.jpg`, `cover.webp`, etc.
|
|
|
|
#### Date Formatting
|
|
- Folder names can include dates: `YYYY-MM-DD-title`
|
|
- Dates are automatically extracted and formatted (Norwegian format: "23. oktober 2025")
|
|
- Metadata can override automatic date detection
|
|
|
|
#### Metadata
|
|
- Use `metadata.ini` files for structured data
|
|
- Common fields: `title`, `date`, `summary`
|
|
- Metadata overrides automatic title/date extraction
|
|
|
|
### HTML & CSS Standards
|
|
- Classless CSS where possible
|
|
- HTML should be highly compliant with best practices
|
|
- Use semantic HTML5 elements
|
|
- Modern CSS features: custom properties, nesting, `oklch()` colors, grid, clamp, logical properties
|
|
- Responsive by default using fluid typography and flexible layouts
|
|
|
|
### Security
|
|
- Path validation prevents directory traversal
|
|
- Files must be within document root
|
|
- MIME types properly set for all served content
|
|
- No direct execution of arbitrary user input
|
|
|
|
### Code Style
|
|
|
|
#### PHP
|
|
- Modern syntax: arrow functions, null coalescing, match expressions
|
|
- Use type hints when practical
|
|
- Ternary operators for simple conditionals
|
|
- Keep functions focused and single-purpose
|
|
|
|
#### CSS
|
|
- Use CSS variables for theming
|
|
- Nesting for component-scoped styles
|
|
- Grid for layout, not tables or excessive flexbox
|
|
- `clamp()` for responsive sizing
|
|
- Avoid pixel values where relative units work better
|
|
|
|
#### Templates
|
|
- Escape output: `htmlspecialchars()` for user-generated content
|
|
- Short echo tags: `<?= $var ?>`
|
|
- Minimize logic in templates—prepare data beforehand
|
|
|
|
### Performance Considerations
|
|
- Page load time displayed in footer (transparency and pride in performance)
|
|
- CSS versioned with MD5 hash for cache busting
|
|
- Minimal HTTP requests through direct includes
|
|
- No JavaScript means no parsing delay
|
|
|
|
### Extensibility Patterns
|
|
- Third-party code goes in `/app/vendor/`
|
|
- Custom code goes in `/app/custom/`
|
|
- Never modify defaults—always override
|
|
- Use fallback chains: custom → default → docs variant
|
|
|
|
## Common Patterns
|
|
|
|
### Adding Custom Styles
|
|
Place CSS in `/app/custom/styles/base.css`—it automatically overrides default styles.
|
|
|
|
### Creating Custom Templates
|
|
Place templates in `/app/custom/templates/`—they automatically override defaults.
|
|
|
|
### Adding Fonts
|
|
Place font files in `/app/custom/fonts/` and reference them in your custom CSS.
|
|
|
|
### Creating Content
|
|
1. Create a directory for your content
|
|
2. Add a content file: `page.md`, `article.md`, etc.
|
|
3. Optionally add `metadata.ini` for title, date, summary
|
|
4. Optionally add `cover.jpg` for list view thumbnails
|
|
5. Content is immediately accessible at the URL matching the directory path
|
|
|
|
### List Views
|
|
When a directory contains subdirectories:
|
|
- Default list template generates automatic listings
|
|
- Each item shows title, date, optional cover image, optional summary
|
|
- Override with custom list template for specialized presentation
|
|
|
|
## What This Framework Is Not
|
|
|
|
- Not a CMS with an admin panel
|
|
- Not a single-page application
|
|
- Not a JavaScript framework
|
|
- Not opinionated about design aesthetics
|
|
- Not trying to scale to millions of users
|
|
|
|
## What This Framework Is
|
|
|
|
- A simple, intuitive way to publish content
|
|
- A foundation that will work for decades
|
|
- A teaching tool for understanding web fundamentals
|
|
- A protest against complexity for complexity's sake
|