Add demo content and documentation for FolderWeb
Add about page with project philosophy and technical details Add articles about Markdown, templates, and getting started Implement demo content system that shows when no user content exists Update logo to show FolderWeb branding Improve Apache configuration for development environment
This commit is contained in:
Ruben
parent
36a3221dbb
commit
4c697122ab
19 changed files with 660 additions and 293 deletions
|
|
@ -0,0 +1,206 @@
|
|||
# Markdown Guide
|
||||
|
||||
Markdown is a lightweight markup language that's easy to write and read. FolderWeb uses [Parsedown](https://parsedown.org/) to convert your Markdown files into beautiful HTML.
|
||||
|
||||
## Headings
|
||||
|
||||
Use `#` symbols for headings:
|
||||
|
||||
```markdown
|
||||
# Heading 1
|
||||
## Heading 2
|
||||
### Heading 3
|
||||
#### Heading 4
|
||||
##### Heading 5
|
||||
###### Heading 6
|
||||
```
|
||||
|
||||
## Emphasis
|
||||
|
||||
Make text **bold** or *italic*:
|
||||
|
||||
```markdown
|
||||
*italic text* or _italic text_
|
||||
**bold text** or __bold text__
|
||||
***bold and italic*** or ___bold and italic___
|
||||
```
|
||||
|
||||
## Lists
|
||||
|
||||
### Unordered Lists
|
||||
|
||||
```markdown
|
||||
- Item one
|
||||
- Item two
|
||||
- Item three
|
||||
- Nested item
|
||||
- Another nested item
|
||||
```
|
||||
|
||||
### Ordered Lists
|
||||
|
||||
```markdown
|
||||
1. First item
|
||||
2. Second item
|
||||
3. Third item
|
||||
1. Nested item
|
||||
2. Another nested item
|
||||
```
|
||||
|
||||
## Links
|
||||
|
||||
```markdown
|
||||
[Link text](https://example.com)
|
||||
[Link with title](https://example.com "Title text")
|
||||
```
|
||||
|
||||
Example: [Visit FolderWeb](#)
|
||||
|
||||
## Images
|
||||
|
||||
```markdown
|
||||
|
||||
|
||||
```
|
||||
|
||||
## Code
|
||||
|
||||
### Inline Code
|
||||
|
||||
Use backticks for `inline code`:
|
||||
|
||||
```markdown
|
||||
Use the `$variable` in your code
|
||||
```
|
||||
|
||||
### Code Blocks
|
||||
|
||||
Use triple backticks for code blocks:
|
||||
|
||||
````markdown
|
||||
```php
|
||||
<?php
|
||||
echo "Hello, World!";
|
||||
?>
|
||||
```
|
||||
````
|
||||
|
||||
Renders as:
|
||||
|
||||
```php
|
||||
<?php
|
||||
echo "Hello, World!";
|
||||
?>
|
||||
```
|
||||
|
||||
## Blockquotes
|
||||
|
||||
```markdown
|
||||
> This is a blockquote.
|
||||
> It can span multiple lines.
|
||||
>
|
||||
> And multiple paragraphs.
|
||||
```
|
||||
|
||||
Result:
|
||||
|
||||
> This is a blockquote.
|
||||
> It can span multiple lines.
|
||||
|
||||
## Horizontal Rules
|
||||
|
||||
Create a horizontal rule with three or more hyphens, asterisks, or underscores:
|
||||
|
||||
```markdown
|
||||
---
|
||||
***
|
||||
___
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Tables
|
||||
|
||||
```markdown
|
||||
| Header 1 | Header 2 | Header 3 |
|
||||
|----------|----------|----------|
|
||||
| Cell 1 | Cell 2 | Cell 3 |
|
||||
| Cell 4 | Cell 5 | Cell 6 |
|
||||
```
|
||||
|
||||
Result:
|
||||
|
||||
| Header 1 | Header 2 | Header 3 |
|
||||
|----------|----------|----------|
|
||||
| Cell 1 | Cell 2 | Cell 3 |
|
||||
| Cell 4 | Cell 5 | Cell 6 |
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Use Semantic Structure
|
||||
|
||||
Start with `# H1` for your page title, then use `## H2`, `### H3`, etc. for sections.
|
||||
|
||||
### Write Readable Markdown
|
||||
|
||||
```markdown
|
||||
# Good Example
|
||||
|
||||
This paragraph is easy to read with proper spacing.
|
||||
|
||||
## Section Heading
|
||||
|
||||
- List items are clear
|
||||
- Each on its own line
|
||||
|
||||
---
|
||||
|
||||
# Bad Example
|
||||
No spacing makes it hard to read.
|
||||
##SectionWithoutSpace
|
||||
-ListItemsSmashed-Together
|
||||
```
|
||||
|
||||
### Links in FolderWeb
|
||||
|
||||
Internal links work best with absolute paths:
|
||||
|
||||
```markdown
|
||||
[About page](/about/)
|
||||
[Articles](/articles/)
|
||||
[Specific article](/articles/2025-10-15-markdown-guide/)
|
||||
```
|
||||
|
||||
## Advanced Features
|
||||
|
||||
### HTML in Markdown
|
||||
|
||||
You can use HTML directly in Markdown when needed:
|
||||
|
||||
```markdown
|
||||
<div class="custom-class">
|
||||
Custom HTML content
|
||||
</div>
|
||||
```
|
||||
|
||||
### Escaping Characters
|
||||
|
||||
Use backslash to escape Markdown characters:
|
||||
|
||||
```markdown
|
||||
\*This text is not italic\*
|
||||
\[This is not a link\]
|
||||
```
|
||||
|
||||
## Tips for FolderWeb
|
||||
|
||||
1. **Use descriptive filenames** - `article.md` is better than `content.md`
|
||||
2. **Add metadata** - Use `metadata.ini` for titles, dates, and summaries
|
||||
3. **Include images** - Place images in the same directory as your content
|
||||
4. **Add cover images** - Use `cover.jpg` for list view thumbnails
|
||||
|
||||
## Further Reading
|
||||
|
||||
- [Markdown Guide](https://www.markdownguide.org/) - Comprehensive Markdown reference
|
||||
- [Parsedown Documentation](https://parsedown.org/) - The parser FolderWeb uses
|
||||
- [CommonMark Spec](https://commonmark.org/) - Markdown specification
|
||||
|
|
@ -0,0 +1,3 @@
|
|||
title = "Markdown Guide"
|
||||
date = "2025-10-15"
|
||||
summary = "Master Markdown syntax for beautiful, semantic content in FolderWeb."
|
||||
|
|
@ -0,0 +1,165 @@
|
|||
# Templates and Customization
|
||||
|
||||
FolderWeb is built on a simple principle: **never modify defaults, always override**. This guide shows you how to customize your site while keeping it maintainable.
|
||||
|
||||
## The Override System
|
||||
|
||||
FolderWeb checks for custom files before falling back to defaults:
|
||||
|
||||
1. Check `/custom/templates/` → Use custom template
|
||||
2. Fall back to `/app/default/templates/` → Use default template
|
||||
|
||||
This means you can override any part of the system without touching the core files.
|
||||
|
||||
## Available Templates
|
||||
|
||||
### Base Template
|
||||
The main HTML structure with header, navigation, and footer.
|
||||
|
||||
**Override**: `/custom/templates/base.php`
|
||||
|
||||
### Page Template
|
||||
Wraps single pages and articles.
|
||||
|
||||
**Override**: `/custom/templates/page.php`
|
||||
|
||||
### List Templates
|
||||
|
||||
FolderWeb includes multiple list view variants:
|
||||
|
||||
- `list.php` - Simple list
|
||||
- `list-grid.php` - Grid layout
|
||||
- `list-card-grid.php` - Card grid with images
|
||||
- `list-faq.php` - Expandable FAQ format
|
||||
|
||||
**Select via metadata**:
|
||||
|
||||
```ini
|
||||
page_template = "list-card-grid"
|
||||
```
|
||||
|
||||
## Customizing Styles
|
||||
|
||||
### Add Your Own CSS
|
||||
|
||||
Create `/custom/styles/base.css` and it automatically overrides default styles.
|
||||
|
||||
Example custom stylesheet:
|
||||
|
||||
```css
|
||||
:root {
|
||||
--color-primary: oklch(0.5 0.2 270);
|
||||
--color-background: oklch(0.98 0 0);
|
||||
--font-body: 'Georgia', serif;
|
||||
}
|
||||
|
||||
article h1 {
|
||||
color: var(--color-primary);
|
||||
font-size: clamp(2rem, 5vw, 3rem);
|
||||
}
|
||||
```
|
||||
|
||||
### Modern CSS Features
|
||||
|
||||
FolderWeb's default styles use modern CSS:
|
||||
|
||||
- **CSS Nesting** - Scope styles naturally
|
||||
- **OKLCH Colors** - Perceptually uniform colors
|
||||
- **CSS Grid** - Flexible layouts
|
||||
- **Clamp()** - Responsive sizing
|
||||
- **Logical Properties** - Better internationalization
|
||||
|
||||
## Custom Fonts
|
||||
|
||||
1. Place font files in `/custom/fonts/`
|
||||
2. Reference them in your custom CSS:
|
||||
|
||||
```css
|
||||
@font-face {
|
||||
font-family: 'MyFont';
|
||||
src: url('/fonts/myfont.woff2') format('woff2');
|
||||
}
|
||||
|
||||
body {
|
||||
font-family: 'MyFont', sans-serif;
|
||||
}
|
||||
```
|
||||
|
||||
## Metadata Options
|
||||
|
||||
Control content behavior with `metadata.ini` files:
|
||||
|
||||
```ini
|
||||
; Basic fields
|
||||
title = "Page Title"
|
||||
date = "2025-10-28"
|
||||
summary = "Short description"
|
||||
|
||||
; Navigation
|
||||
menu = true
|
||||
menu_order = 1
|
||||
|
||||
; Templates
|
||||
page_template = "list-card-grid"
|
||||
|
||||
; Redirects
|
||||
redirect = "https://example.com"
|
||||
|
||||
; Attachments
|
||||
pdf = "document.pdf"
|
||||
```
|
||||
|
||||
## Template Variables
|
||||
|
||||
Templates have access to specific variables:
|
||||
|
||||
### Base Template
|
||||
- `$content` - Page content
|
||||
- `$currentLang` - Current language code
|
||||
- `$navigation` - Navigation items array
|
||||
- `$pageTitle` - Page title
|
||||
|
||||
### Page Template
|
||||
- `$content` - Article content
|
||||
- `$pageMetadata` - Metadata array
|
||||
- `$translations` - Translation strings
|
||||
|
||||
### List Templates
|
||||
- `$items` - Array of subitems
|
||||
- `$metadata` - Directory metadata
|
||||
- `$pageContent` - Intro text
|
||||
- `$translations` - Translation strings
|
||||
|
||||
## Creating a Custom Template
|
||||
|
||||
Example custom page template:
|
||||
|
||||
```php
|
||||
<?php
|
||||
// /custom/templates/page.php
|
||||
?>
|
||||
<article class="custom-layout">
|
||||
<?php if (isset($pageMetadata['date'])): ?>
|
||||
<time><?= htmlspecialchars($pageMetadata['date']) ?></time>
|
||||
<?php endif; ?>
|
||||
|
||||
<?= $content ?>
|
||||
|
||||
<footer>
|
||||
<p>Custom footer content</p>
|
||||
</footer>
|
||||
</article>
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Never modify `/app/default/`** - Always create overrides in `/custom/`
|
||||
2. **Use metadata** - Keep configuration in `metadata.ini` files
|
||||
3. **Leverage CSS variables** - Easy theming without rewriting styles
|
||||
4. **Keep it simple** - The less custom code, the easier to maintain
|
||||
|
||||
## Next Steps
|
||||
|
||||
- Explore default templates in `/app/default/templates/`
|
||||
- Study the default CSS in `/app/default/styles/base.css`
|
||||
- Check out the [Markdown Guide](/articles/2025-10-15-markdown-guide/) for content formatting
|
||||
|
|
@ -0,0 +1,3 @@
|
|||
title = "Templates and Customization"
|
||||
date = "2025-10-28"
|
||||
summary = "Customize your FolderWeb site with templates, styles, and metadata options."
|
||||
|
|
@ -0,0 +1,79 @@
|
|||
# Getting Started with FolderWeb
|
||||
|
||||
FolderWeb is designed to be the simplest way to publish content on the web. This guide will walk you through the core concepts and get you publishing in minutes.
|
||||
|
||||
## Installation
|
||||
|
||||
FolderWeb requires PHP 8.3+ and Apache with `mod_rewrite` enabled.
|
||||
|
||||
### Using Docker (Recommended for Development)
|
||||
|
||||
```bash
|
||||
cd development
|
||||
docker compose up
|
||||
```
|
||||
|
||||
Visit `http://localhost:8080` to see your site.
|
||||
|
||||
### Manual Installation
|
||||
|
||||
1. Point Apache's document root to the `/content` directory
|
||||
2. Ensure the `/app` directory is accessible at the same level
|
||||
3. Enable `mod_rewrite` in Apache
|
||||
4. That's it!
|
||||
|
||||
## Creating Your First Page
|
||||
|
||||
The easiest way to understand FolderWeb is to create some content.
|
||||
|
||||
### Create a Simple Page
|
||||
|
||||
1. Create a new directory: `/content/hello/`
|
||||
2. Add a file: `/content/hello/page.md`
|
||||
3. Write some Markdown:
|
||||
|
||||
```markdown
|
||||
# Hello World
|
||||
|
||||
This is my first page in FolderWeb!
|
||||
```
|
||||
|
||||
Your page is now live at `/hello/`
|
||||
|
||||
### Create an Article with Metadata
|
||||
|
||||
For richer content, add metadata:
|
||||
|
||||
1. Create: `/content/articles/2025-11-01-my-article/`
|
||||
2. Add metadata: `/content/articles/2025-11-01-my-article/metadata.ini`
|
||||
|
||||
```ini
|
||||
title = "My First Article"
|
||||
date = "2025-11-01"
|
||||
summary = "A brief description of my article"
|
||||
```
|
||||
|
||||
3. Add content: `/content/articles/2025-11-01-my-article/article.md`
|
||||
|
||||
The date in the folder name is automatically extracted and displayed.
|
||||
|
||||
## File Types
|
||||
|
||||
FolderWeb supports three content types:
|
||||
|
||||
- **Markdown (`.md`)** - Write in Markdown, rendered as HTML
|
||||
- **HTML (`.html`)** - Pure HTML for complete control
|
||||
- **PHP (`.php`)** - Dynamic content when needed
|
||||
|
||||
## File Naming Conventions
|
||||
|
||||
- **Page content**: `page.md`, `page.html`, `page.php`
|
||||
- **Articles/posts**: `article.md`, `post.md`, `single.md` (and `.html`/`.php` variants)
|
||||
- **Frontpage**: `/content/frontpage.php`
|
||||
- **Index override**: `index.php` in any directory takes precedence
|
||||
|
||||
## Next Steps
|
||||
|
||||
- Read the [Templates Guide](/articles/2025-10-28-templates-and-customization/) to customize your site
|
||||
- Learn [Markdown syntax](/articles/2025-10-15-markdown-guide/) for better content
|
||||
- Explore the default templates in `/app/default/templates/`
|
||||
|
|
@ -0,0 +1,3 @@
|
|||
title = "Getting Started with FolderWeb"
|
||||
date = "2025-11-01"
|
||||
summary = "Learn the basics of FolderWeb and create your first content in minutes."
|
||||
4
app/default/content/articles/metadata.ini
Normal file
4
app/default/content/articles/metadata.ini
Normal file
|
|
@ -0,0 +1,4 @@
|
|||
title = "Articles"
|
||||
menu = true
|
||||
menu_order = 1
|
||||
page_template = "list-card-grid"
|
||||
3
app/default/content/articles/page.md
Normal file
3
app/default/content/articles/page.md
Normal file
|
|
@ -0,0 +1,3 @@
|
|||
# Articles
|
||||
|
||||
A collection of guides and tutorials to help you get the most out of FolderWeb.
|
||||
Loading…
Add table
Add a link
Reference in a new issue