Update getting started documentation
Remove redundant quick start section Simplify requirements and installation Clarify local development setup Streamline first page creation Add shared hosting deployment instructions Update tutorial content structure Improve content format explanations Clarify asset handling Simplify metadata documentation Update styling documentation Improve template explanations Remove unnecessary examples Make documentation more concise
This commit is contained in:
Ruben
parent
cef370ca0c
commit
8855a9b5be
4 changed files with 226 additions and 759 deletions
|
|
@ -1,137 +1,70 @@
|
|||
# Getting Started with FolderWeb
|
||||
# Getting Started
|
||||
|
||||
Welcome to FolderWeb—a delightfully minimal PHP framework that turns your folder structure into a website. No build steps, no package managers, no JavaScript frameworks. Just files and folders doing what they do best.
|
||||
## Requirements
|
||||
|
||||
## What You Need
|
||||
- PHP 8.4+
|
||||
- Apache with mod_rewrite
|
||||
- A text editor
|
||||
|
||||
- **PHP 8.4+** — Modern PHP with all the good stuff
|
||||
- **A web server** — Apache, Nginx, or just PHP's built-in server for local development
|
||||
- **A text editor** — Whatever makes you happy
|
||||
|
||||
That's it. No npm, no webpack, no node_modules folder the size of the observable universe.
|
||||
|
||||
## Quick Start (5 Minutes)
|
||||
|
||||
### 1. Get the Code
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
git clone https://github.com/yourusername/folderweb.git
|
||||
cd folderweb
|
||||
```
|
||||
|
||||
### 2. Set Up Your Custom Directory
|
||||
|
||||
FolderWeb separates framework code (`app/`) from your customizations (`custom/`). Copy the defaults to get started:
|
||||
|
||||
**Unix/Linux/macOS:**
|
||||
```bash
|
||||
cp -r app/default custom
|
||||
```
|
||||
|
||||
**Windows (PowerShell):**
|
||||
```powershell
|
||||
Copy-Item -Recurse app\default custom
|
||||
```
|
||||
|
||||
**Or just:** Copy the `app/default` folder and rename it to `custom` using your file manager.
|
||||
|
||||
### 3. Create Your Content Directory
|
||||
|
||||
```bash
|
||||
mkdir content
|
||||
```
|
||||
|
||||
This is where your actual website content lives—separate from the framework.
|
||||
|
||||
### 4. Fire It Up Locally
|
||||
|
||||
**Using Podman (Recommended):**
|
||||
|
||||
If you have [Podman](https://podman.io/) installed, there's a ready-made setup:
|
||||
## Local Development
|
||||
|
||||
```bash
|
||||
cd devel
|
||||
podman-compose up
|
||||
podman-compose up -d
|
||||
```
|
||||
|
||||
Visit `http://localhost:8080` and you're live.
|
||||
|
||||
**Using PHP's Built-in Server:**
|
||||
Or with PHP's built-in server:
|
||||
|
||||
```bash
|
||||
php -S localhost:8080 -t .
|
||||
```
|
||||
|
||||
Simple, but you'll need to configure routing manually for production.
|
||||
Visit `http://localhost:8080`.
|
||||
|
||||
### 5. Make Your First Page
|
||||
## Your First Page
|
||||
|
||||
Create a file at `content/hello.md`:
|
||||
Create `content/hello.md`:
|
||||
|
||||
```markdown
|
||||
# Hello, World!
|
||||
|
||||
This is my first page. Look ma, no build step!
|
||||
This is my first page.
|
||||
```
|
||||
|
||||
Visit `http://localhost:8080/hello/` and there it is.
|
||||
Visit `http://localhost:8080/hello/`.
|
||||
|
||||
**Pro tip:** Notice the trailing slash? FolderWeb enforces them. Folders are folders, after all.
|
||||
## Deploying to Shared Hosting
|
||||
|
||||
## What Just Happened?
|
||||
### Recommended Structure
|
||||
|
||||
FolderWeb looked at your request (`/hello/`), found `content/hello.md`, processed the Markdown into HTML, wrapped it in a template, and served it. All in milliseconds.
|
||||
Keep the framework and content outside the web root. Use symlinks to expose them:
|
||||
|
||||
The magic is simple:
|
||||
- **Folders = URLs:** Your directory structure is your site structure
|
||||
- **Files = Content:** Drop a `.md`, `.html`, or `.php` file and it renders
|
||||
- **Templates = Presentation:** HTML wrappers that make everything pretty
|
||||
- **Metadata = Configuration:** Optional `.ini` files for titles, dates, and settings
|
||||
|
||||
## Next Steps
|
||||
|
||||
Now that you're up and running, you can:
|
||||
|
||||
1. **[Add more content](#)** — Learn about Markdown files, metadata, and organizing pages
|
||||
2. **[Customize the design](#)** — Edit templates and CSS to make it yours
|
||||
3. **[Deploy to production](#)** — Get your site online with a web host
|
||||
|
||||
Or just keep making pages. It's your website—do what makes you happy.
|
||||
|
||||
---
|
||||
|
||||
## Deploying to Production
|
||||
|
||||
When you're ready to go live, you'll need a web host with PHP support. Look for:
|
||||
|
||||
- **PHP 8.4+** (or at least 8.0, but why settle?)
|
||||
- **Apache or Nginx** with mod_rewrite or equivalent
|
||||
- **SSH access** (optional, but makes life easier)
|
||||
|
||||
Most shared hosting providers offer this. Avoid anything that says "managed WordPress only"—you're too cool for that.
|
||||
|
||||
### Deployment with Symlinks (Recommended)
|
||||
|
||||
Keep the framework separate from the web root for easy upgrades:
|
||||
|
||||
```bash
|
||||
# Your server structure:
|
||||
/home/yourusername/
|
||||
```
|
||||
/home/username/
|
||||
├── folderweb/ # Git repo (not public)
|
||||
│ ├── app/
|
||||
│ └── custom/
|
||||
├── content/ # Your content (not public)
|
||||
└── public_html/ # Web root (public)
|
||||
├── app -> ../folderweb/app/ # Symlink
|
||||
├── custom -> ../folderweb/custom/ # Symlink
|
||||
└── content -> ../content/ # Symlink
|
||||
└── public_html/ # Web root
|
||||
├── app -> ../folderweb/app/
|
||||
├── custom -> ../folderweb/custom/
|
||||
└── content -> ../content/
|
||||
```
|
||||
|
||||
**Why?** When you update FolderWeb, just `git pull` and you're done. No copying files, no risk of overwriting customizations.
|
||||
To update FolderWeb, `git pull` in the repo directory.
|
||||
|
||||
### Apache Configuration
|
||||
### Apache
|
||||
|
||||
If your host lets you use `.htaccess`, FolderWeb will handle routing automatically. Otherwise, add this to your Apache config:
|
||||
FolderWeb includes an `.htaccess` file that handles routing automatically. If your host requires manual configuration:
|
||||
|
||||
```apache
|
||||
<Directory /path/to/public_html>
|
||||
|
|
@ -142,24 +75,8 @@ If your host lets you use `.htaccess`, FolderWeb will handle routing automatical
|
|||
</Directory>
|
||||
```
|
||||
|
||||
### Nginx Configuration
|
||||
## Next Steps
|
||||
|
||||
```nginx
|
||||
location / {
|
||||
try_files $uri $uri/ /app/router.php?$query_string;
|
||||
}
|
||||
```
|
||||
|
||||
That's it. Upload your files, point your domain, and you're live.
|
||||
|
||||
---
|
||||
|
||||
## What's Next?
|
||||
|
||||
Ready to dive deeper? Head to the [Tutorial](#) to learn how to:
|
||||
- Organize content with folders and metadata
|
||||
- Customize templates and styles
|
||||
- Add multilingual support
|
||||
- Create list views and navigation menus
|
||||
|
||||
Or jump straight to the [Reference](#) if you're the "read the manual" type.
|
||||
- [Adding content](../02-tutorial/01-adding-content.md) — Pages, metadata, and content formats
|
||||
- [Styling](../02-tutorial/02-styling.md) — Customize the look
|
||||
- [Templates](../02-tutorial/03-templates.md) — Control how content is presented
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue