Using Friendly URLs

Friendly URLs (FURLs) replace addresses like index.php?id=42 with readable paths based on Resource aliases, such as /about/ or /blog/my-post.

You need two things:

1. Web server rewrite rules sending unknown paths to index.php
2. Friendly URLs enabled in MODX

1. Configure your web server¶

MODX Cloud: rewrite rules are already in place — skip this step.

Other servers: pick your guide:

• Apache (most shared hosting; uses ht.access → .htaccess)
• IIS (web.config + URL Rewrite)
• nginx
• lighttpd

Until rewrites work, enabling Friendly URLs in MODX will 404 on pretty paths.

2. Enable Friendly URLs in MODX¶

In the Manager, open System Settings (gear icon, top navigation).

Filter by key friendly (or Area: Friendly URL), then set at least:

Optional: friendly_urls_strict returns 404 for unknown aliases instead of falling back to the pagetitle.

With Use Friendly Alias Path set to No, Resources behave as if they sit at the site root, ignoring parent folders.

Related: use_frozen_parent_uris (default No) makes child URIs relative to a parent's frozen URI instead of its current alias — useful when parents change often.

Container Resources (folders) use the container_suffix setting (default /) instead of friendly_url_prefix / friendly_url_suffix, removed in favour of Content Types. It applies only to folders whose content type is HTML.

For non-Latin pagetitles, configure alias transliteration (friendly_alias_translit: none (default), iconv, iconv_ascii, or a named table): Alias transliteration.

3. Add a base href in your Templates¶

Put this in the <head> of every Template serving HTML:

<base href="[[!++site_url]]" />

Relative asset URLs then resolve from the site root, even on nested paths.

4. Clear the site cache¶

Saving these settings rebuilds the URIs and reloads the config automatically. If the frontend still serves stale links or pages, clear the cache from the Manager (or delete core/cache/) — also needed after editing aliases or Templates.

Building links¶

Prefer link tags so URLs stay correct when you move Resources:

<a href="[[~1]]" title="Some title">Some Page</a>

See Resources for link tag syntax.

Optional: www and HTTPS redirects¶

After FURLs work, pick one canonical host (www or bare domain) and HTTP or HTTPS — duplicate hostnames cause session and SEO issues.

On Apache, the shipped ht.access file has commented-out example rules: uncomment the block you need and replace the domain. See the Apache guide.

On nginx, put equivalent return 301 logic in the matching server blocks.

On IIS, add equivalent redirect rules in web.config (see the IIS guide).

Related¶

• Alias transliteration
• friendly_urls_strict
• Server Requirements
• Content Types

Troubleshooting: pretty paths 404¶

• Pretty paths 404 but index.php?id=42 works → rewrite rules are missing or wrong for your server — go back to step 1.
• CSS/JS broke after enabling FURLs → add <base href> to your Templates (step 3).
• Links did not change after enabling friendly_urls → clear the cache (step 4); existing Resources keep their stored aliases until you edit them.
• Requests to core/ files return 404 → expected; core/ must stay blocked (Hardening MODX).