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,6 +1,6 @@
|
|||
# Adding Content
|
||||
|
||||
FolderWeb turns your folder structure into a website. That's not marketing speak—it's literally how it works. Let's explore what that means in practice.
|
||||
FolderWeb turns your folder structure into a website. Every file becomes a page, every folder becomes a URL path.
|
||||
|
||||
## The Basic Idea
|
||||
|
||||
|
|
@ -12,16 +12,14 @@ content/
|
|||
└── contact.html → yoursite.com/contact/
|
||||
```
|
||||
|
||||
Every file becomes a page. Every folder becomes a URL path. No configuration required.
|
||||
No configuration required.
|
||||
|
||||
## File Types
|
||||
## Content Formats
|
||||
|
||||
FolderWeb recognizes three content types:
|
||||
FolderWeb supports three content formats. You can use them individually or mix them within a single page.
|
||||
|
||||
### Markdown (`.md`)
|
||||
|
||||
The bread and butter of content creation. Write in Markdown, get HTML.
|
||||
|
||||
```markdown
|
||||
# My Page Title
|
||||
|
||||
|
|
@ -29,46 +27,30 @@ This is a paragraph with **bold** and *italic* text.
|
|||
|
||||
- Lists work
|
||||
- And so do [links](https://example.com)
|
||||
|
||||
## Subheading
|
||||
|
||||
More content here.
|
||||
```
|
||||
|
||||
FolderWeb uses [Parsedown](https://parsedown.org/) to convert Markdown to HTML, with caching for performance.
|
||||
Converted to HTML using [Parsedown](https://parsedown.org/) with caching.
|
||||
|
||||
### HTML (`.html`)
|
||||
|
||||
When you need more control or already have HTML:
|
||||
|
||||
```html
|
||||
<h1>My Page</h1>
|
||||
<p>This is plain HTML.</p>
|
||||
<p>Plain HTML, rendered as-is.</p>
|
||||
<div class="custom-widget">
|
||||
Whatever you want.
|
||||
Full control over markup.
|
||||
</div>
|
||||
```
|
||||
|
||||
### PHP (`.php`)
|
||||
|
||||
For dynamic content:
|
||||
|
||||
```php
|
||||
<?php
|
||||
$currentYear = date('Y');
|
||||
echo "<p>Copyright {$currentYear}</p>";
|
||||
?>
|
||||
|
||||
<h2>Latest Posts</h2>
|
||||
<?php
|
||||
$posts = ['Post 1', 'Post 2', 'Post 3'];
|
||||
foreach ($posts as $post) {
|
||||
echo "<li>{$post}</li>";
|
||||
}
|
||||
?>
|
||||
```
|
||||
|
||||
**Important:** PHP files are executed, so be careful with user input and security.
|
||||
PHP files are executed server-side. Be careful with user input and security.
|
||||
|
||||
## Folder Structure as URL Structure
|
||||
|
||||
|
|
@ -90,14 +72,13 @@ content/
|
|||
└── index.md → /projects/my-project/
|
||||
```
|
||||
|
||||
**Key points:**
|
||||
- Folder names become URL slugs
|
||||
- Date prefixes (`YYYY-MM-DD-`) are stripped from URLs but preserved for sorting
|
||||
- Trailing slashes are enforced (FolderWeb redirects `/about` → `/about/`)
|
||||
- Trailing slashes are enforced (`/about` redirects to `/about/`)
|
||||
|
||||
## Multiple Files in One Page
|
||||
|
||||
You can combine multiple content files in a single directory. They render as a single page, combined in filename order.
|
||||
Multiple content files in one directory render as a single page, combined in filename order.
|
||||
|
||||
**Prefix filenames with numbers to control the order:**
|
||||
|
||||
|
|
@ -111,11 +92,11 @@ content/portfolio/
|
|||
|
||||
All four files render as one page at `/portfolio/`. You can mix `.md`, `.html`, and `.php` freely — use whichever format fits each section best.
|
||||
|
||||
**Why number prefixes?** Files are sorted using natural sort (`strnatcmp`), so `10-` comes before `20-` comes before `30-`. Using increments of 10 leaves room to insert new sections later without renaming existing files. Files without a number prefix sort after numbered files.
|
||||
**Why number prefixes?** Files are sorted using natural sort, so `10-` comes before `20-` comes before `30-`. Using increments of 10 leaves room to insert new sections later without renaming existing files. Files without a number prefix sort after numbered files.
|
||||
|
||||
## Dates in Folder Names
|
||||
|
||||
FolderWeb automatically extracts dates from folder names:
|
||||
FolderWeb extracts dates from folder names automatically:
|
||||
|
||||
```
|
||||
content/blog/
|
||||
|
|
@ -124,17 +105,16 @@ content/blog/
|
|||
└── 2025-01-01-new-year-post/ # Date: January 1, 2025
|
||||
```
|
||||
|
||||
The date format is `YYYY-MM-DD-` and it's **stripped from the URL**:
|
||||
The `YYYY-MM-DD-` prefix is stripped from the URL:
|
||||
|
||||
- Folder: `2024-12-15-my-first-post`
|
||||
- URL: `/blog/my-first-post/`
|
||||
- Date: Extracted and available in templates
|
||||
|
||||
Dates are automatically formatted based on your language (e.g., "15. desember 2024" in Norwegian).
|
||||
Dates are formatted based on your configured language.
|
||||
|
||||
## Adding Assets (Images, Files)
|
||||
## Assets
|
||||
|
||||
Drop assets directly in your content folders:
|
||||
Drop images and other files directly in your content folders:
|
||||
|
||||
```
|
||||
content/blog/my-post/
|
||||
|
|
@ -144,17 +124,17 @@ content/blog/my-post/
|
|||
└── styles.css # Page-specific styles
|
||||
```
|
||||
|
||||
**Reference in Markdown:**
|
||||
Reference in Markdown:
|
||||
|
||||
```markdown
|
||||
|
||||
```
|
||||
|
||||
**Cover images:** Name your cover image `cover.jpg`, `cover.png`, or `cover.webp`. FolderWeb automatically uses it in list views and social media meta tags.
|
||||
**Cover images:** Name your image `cover.jpg`, `cover.png`, or `cover.webp`. FolderWeb uses it automatically in list views and social media meta tags.
|
||||
|
||||
## Metadata Files
|
||||
## Metadata
|
||||
|
||||
Add a `metadata.ini` file to configure pages:
|
||||
Add a `metadata.ini` file to configure a page:
|
||||
|
||||
```
|
||||
content/blog/my-post/
|
||||
|
|
@ -162,7 +142,7 @@ content/blog/my-post/
|
|||
└── metadata.ini
|
||||
```
|
||||
|
||||
**Basic metadata:**
|
||||
Basic metadata:
|
||||
|
||||
```ini
|
||||
title = "My Awesome Post"
|
||||
|
|
@ -170,84 +150,71 @@ summary = "A short description for list views"
|
|||
date = "2024-12-15"
|
||||
```
|
||||
|
||||
**More options:**
|
||||
More options:
|
||||
|
||||
```ini
|
||||
title = "My Post"
|
||||
summary = "Short description"
|
||||
date = "2024-12-15"
|
||||
search_description = "SEO-friendly description for search engines"
|
||||
search_description = "SEO description for search engines"
|
||||
menu = 1 # Show in navigation menu
|
||||
menu_order = 10 # Menu position (lower = first)
|
||||
|
||||
[settings]
|
||||
show_date = true # Display date on page
|
||||
hide_list = false # Don't show list view even if subdirectories exist
|
||||
hide_list = false # Force page view even with subdirectories
|
||||
```
|
||||
|
||||
See the [Metadata Reference](#) for all available options.
|
||||
See the [Metadata Reference](../03-reference/02-metadata.md) for all options.
|
||||
|
||||
## List Views vs. Page Views
|
||||
|
||||
FolderWeb automatically decides whether to show a **list** or a **page**:
|
||||
|
||||
**List view** (directory has subdirectories):
|
||||
**List view** — directory has subdirectories:
|
||||
```
|
||||
content/blog/
|
||||
├── index.md # Intro content
|
||||
├── metadata.ini # List configuration
|
||||
├── index.md # Intro content (shown above list)
|
||||
├── metadata.ini
|
||||
├── 2024-12-15-first-post/
|
||||
└── 2024-12-20-second-post/
|
||||
```
|
||||
Result: `/blog/` shows a list of posts.
|
||||
|
||||
Result: `/blog/` shows a list of posts with the intro content at the top.
|
||||
|
||||
**Page view** (directory has only files):
|
||||
**Page view** — directory has only files:
|
||||
```
|
||||
content/about/
|
||||
└── index.md
|
||||
```
|
||||
Result: `/about/` shows the page content.
|
||||
|
||||
Result: `/about/` shows just the page content.
|
||||
|
||||
**Override:** Use `hide_list = true` in `metadata.ini` to force page view even with subdirectories.
|
||||
Set `hide_list = true` in `metadata.ini` to force page view even when subdirectories exist.
|
||||
|
||||
## Custom URL Slugs
|
||||
|
||||
Don't like your folder name as the URL? Override it with metadata:
|
||||
|
||||
```ini
|
||||
slug = "custom-url-path"
|
||||
```
|
||||
|
||||
**Example:**
|
||||
|
||||
```
|
||||
content/blog/2024-12-15-very-long-title-that-i-regret/
|
||||
└── metadata.ini
|
||||
```
|
||||
Override the folder name as URL with metadata:
|
||||
|
||||
```ini
|
||||
slug = "short-title"
|
||||
```
|
||||
|
||||
URL becomes `/blog/short-title/` instead of `/blog/very-long-title-that-i-regret/`.
|
||||
Folder `2024-12-15-very-long-title/` becomes `/blog/short-title/` instead of `/blog/very-long-title/`.
|
||||
|
||||
## Navigation Menus
|
||||
## Navigation Menu
|
||||
|
||||
Add pages to the navigation menu with metadata:
|
||||
Add pages to the navigation menu:
|
||||
|
||||
```ini
|
||||
title = "About Us"
|
||||
menu = 1 # Show in menu
|
||||
menu_order = 20 # Position (lower numbers first)
|
||||
menu_order = 20 # Position (lower = first)
|
||||
```
|
||||
|
||||
Menu items are sorted by `menu_order`, then alphabetically by title.
|
||||
Items are sorted by `menu_order`, then alphabetically by title.
|
||||
|
||||
## Practical Examples
|
||||
## Examples
|
||||
|
||||
### Simple Blog Post
|
||||
### Blog Post
|
||||
|
||||
```
|
||||
content/blog/2024-12-15-my-first-post/
|
||||
|
|
@ -260,7 +227,7 @@ content/blog/2024-12-15-my-first-post/
|
|||
```markdown
|
||||
# My First Post
|
||||
|
||||
This is my blog post content.
|
||||
Blog post content goes here.
|
||||
|
||||
|
||||
```
|
||||
|
|
@ -271,7 +238,7 @@ title = "My First Post"
|
|||
summary = "An introduction to my blog"
|
||||
```
|
||||
|
||||
### Multi-Section Page
|
||||
### Multi-Format Page
|
||||
|
||||
```
|
||||
content/services/
|
||||
|
|
@ -283,28 +250,8 @@ content/services/
|
|||
|
||||
All content files render together as one page at `/services/`, in number-prefix order.
|
||||
|
||||
### Documentation Site
|
||||
## Next Steps
|
||||
|
||||
```
|
||||
content/docs/
|
||||
├── index.md
|
||||
├── getting-started/
|
||||
│ └── index.md
|
||||
├── tutorial/
|
||||
│ ├── index.md
|
||||
│ ├── basics.md
|
||||
│ └── advanced.md
|
||||
└── reference/
|
||||
└── index.md
|
||||
```
|
||||
|
||||
Creates a hierarchical documentation structure with automatic list views.
|
||||
|
||||
## What's Next?
|
||||
|
||||
Now that you know how to add content, learn how to:
|
||||
- **[Customize styling](#)** — Make it look like your own
|
||||
- **[Create templates](#)** — Control how content is presented
|
||||
- **[Add multilingual support](#)** — Reach a global audience
|
||||
|
||||
Or jump to the [Reference](#) for detailed documentation on metadata, templates, and configuration.
|
||||
- [Styling](02-styling.md) — Customize colors, fonts, and layout
|
||||
- [Templates](03-templates.md) — Control how content is presented
|
||||
- [Internationalization](../03-reference/04-internationalization.md) — Multi-language support
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue