folderweb/docs/reference/configuration.md

Configuration Reference

Complete reference for FolderWeb configuration options.

Configuration File

Location: /custom/config.ini (or /app/config.ini for defaults)

Format: INI format with sections

Override Behavior: Custom config values override defaults

Configuration Sections

[languages]

Controls language support and defaults.

[languages]
default = "en"
available = "en,no,fr"

default

Type: String
Required: Yes
Default: "en"

The primary language of your site. This language:

• Has no URL prefix
• Is used as fallback for missing translations
• Should match a translation file in /custom/languages/ or /app/default/languages/

Examples:

default = "en"    ; English
default = "no"    ; Norwegian
default = "fr"    ; French
default = "de"    ; German

available

Type: Comma-separated string
Required: Yes
Default: "en,no"

List of all languages supported by your site. Must include the default language.

Examples:

; English only
available = "en"

; English and Norwegian
available = "en,no"

; Multiple languages
available = "en,no,fr,de,es"

URL Structure:

• Default language: yoursite.com/page/
• Other languages: yoursite.com/fr/page/, yoursite.com/de/page/

File Structure

Default Configuration

Location: /app/config.ini

[languages]
default = "no"
available = "no,en"

Note: Never modify /app/config.ini directly.

Custom Configuration

Location: /custom/config.ini

Create this file to override defaults:

[languages]
default = "en"
available = "en,fr,de"

Only include settings you want to override.

Configuration Loading

Configuration is loaded in this order:

1. Load /app/config.ini (defaults)
2. Load /custom/config.ini if exists
3. Merge, with custom values overriding defaults

Example:

app/config.ini:

[languages]
default = "no"
available = "no,en"

custom/config.ini:

[languages]
default = "en"

Result:

[languages]
default = "en"        ; From custom
available = "no,en"   ; From default (not overridden)

Complete Configuration Examples

Single Language Site

[languages]
default = "en"
available = "en"

URLs: All at root level (/page/, /blog/, etc.)

Bilingual Site (English/Norwegian)

[languages]
default = "en"
available = "en,no"

URLs:

• English: /page/, /blog/
• Norwegian: /no/page/, /no/blog/

Multilingual Site

[languages]
default = "en"
available = "en,no,fr,de,es"

URLs:

• English (default): /page/
• Norwegian: /no/page/
• French: /fr/page/
• German: /de/page/
• Spanish: /es/page/

Language Codes

Use ISO 639-1 two-letter codes:

Code	Language
en	English
no	Norwegian
fr	French
de	German
es	Spanish
it	Italian
pt	Portuguese
nl	Dutch
sv	Swedish
da	Danish
fi	Finnish
pl	Polish
ru	Russian
ja	Japanese
zh	Chinese
ko	Korean
ar	Arabic

Full list: https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes

Related Configuration

Translation Files

For each language in available, create a translation file:

Pattern: /custom/languages/{lang}.ini

Example (with available = "en,no,fr"):

custom/languages/
├── en.ini
├── no.ini
└── fr.ini

See Translation Reference for details.

Content Files

Language-specific content uses the same codes:

Pattern: filename.{lang}.ext

Examples:

• index.md - Default language
• index.no.md - Norwegian
• index.fr.md - French

See Multi-Language Guide for details.

Validation

Check Configuration

Verify configuration is loaded correctly:

test-config.php:

<?php
require 'app/config.php';

$ctx = createContext();

echo "Default language: " . $ctx->defaultLang . "\n";
echo "Available languages: " . implode(', ', $ctx->availableLangs) . "\n";
echo "Current language: " . $ctx->currentLang . "\n";
echo "Language prefix: " . $ctx->langPrefix . "\n";

Run:

php test-config.php

Common Errors

Missing default in available:

; Wrong - default must be in available
[languages]
default = "en"
available = "no,fr"

; Correct
[languages]
default = "en"
available = "en,no,fr"

Invalid language codes:

; Avoid - use ISO codes
available = "english,norwegian"

; Correct - ISO 639-1 codes
available = "en,no"

Typos in section names:

; Wrong
[language]
default = "en"

; Correct
[languages]
default = "en"

Future Configuration Options

FolderWeb is minimal by design. Currently, only language settings are configurable.

Possible future additions:

• Date format preferences
• Timezone settings
• Content directory override
• Cache settings

For now, these are handled through code or conventions.

Environment-Specific Configuration

To use different configs per environment:

Option 1: Conditional Loading

custom/config.ini:

[languages]
default = "en"
available = "en,no"

custom/config.dev.ini:

[languages]
default = "en"
available = "en"

Modify app/config.php to load based on environment.

Option 2: Separate Deployments

Use different custom/config.ini files per deployment:

• Development: /custom/config.ini with dev settings
• Production: Different /custom/config.ini with prod settings

Configuration in Templates

Access configuration through context object:

<!-- Current language -->
<html lang="<?= $ctx->currentLang ?>">

<!-- Available languages -->
<nav class="language-switcher">
    <?php foreach ($ctx->availableLangs as $lang): ?>
        <a href="/<?= $lang ?>/"><?= strtoupper($lang) ?></a>
    <?php endforeach; ?>
</nav>

<!-- Default language check -->
<?php if ($ctx->currentLang === $ctx->defaultLang): ?>
    <p>Viewing in default language</p>
<?php endif; ?>

<!-- Language prefix for URLs -->
<a href="<?= $ctx->langPrefix ?>/about/">About</a>

Best Practices

Keep It Simple

Only configure what's necessary. FolderWeb embraces sensible defaults.

Match Translation Files

Ensure translation files exist for all languages:

[languages]
available = "en,no,fr"

Requires:

• custom/languages/en.ini
• custom/languages/no.ini
• custom/languages/fr.ini

Choose Appropriate Default

Your default language should be:

• Your primary audience's language
• The language with most content
• The language you'll maintain long-term

Document Your Choices

Add comments to explain configuration:

; Site uses English as primary language (most content)
; Norwegian and French are secondary translations
[languages]
default = "en"
available = "en,no,fr"

Testing Configuration Changes

After changing configuration:

1. Clear browser cache (Ctrl+Shift+R or Cmd+Shift+R)
2. Test default language: Visit /
3. Test other languages: Visit /no/, /fr/, etc.
4. Check navigation: Ensure menu links include language prefix
5. Verify translations: Check UI strings change per language
6. Test language switcher: Confirm switching works

Related

• Multi-Language Guide
• Translation Reference
• Metadata Reference
• Context Object Reference