From: Rich Bowen Date: Mon, 11 May 2026 12:08:42 +0000 (+0000) Subject: Rewrite guide: replace index.xml with structured overview X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=1304d919b5fd5d7b76fba2d3ea3638ac3ed883fc;p=thirdparty%2Fapache%2Fhttpd.git Rewrite guide: replace index.xml with structured overview The index page was duplicating content from intro.xml (module capabilities, complexity warnings). Replace with a concise intro paragraph and a definition-list TOC that describes how the guide is organized. Rename the mod_rewrite reference link to "The Reference Manual." Add TODO.md tracking the remaining cross-file redundancies to resolve (path stripping, [L]/[END] looping, FallbackResource, duplicate warnings, etc.). Will be removed when cleanup is complete. git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@1934081 13f79535-47bb-0310-9956-ffa450edef68 --- diff --git a/docs/manual/rewrite/TODO.md b/docs/manual/rewrite/TODO.md new file mode 100644 index 0000000000..44189527db --- /dev/null +++ b/docs/manual/rewrite/TODO.md @@ -0,0 +1,47 @@ +# Rewrite Docs — Redundancy Cleanup TODO + +Working list of cross-file redundancies to resolve. Each item should +result in one file "owning" the content and others cross-referencing it. + +## HIGH Priority + +- [ ] **Per-directory path stripping** explained in full across three files + (intro.xml, tech.xml, htaccess.xml) with near-identical comparison + tables in tech.xml and htaccess.xml. + → htaccess.xml owns it; others get a brief mention + xref. + +- [ ] **[L] vs [END] looping** fully described in three places + (htaccess.xml, plus both the [L] and [END] sections of flags.xml). + → htaccess.xml owns the full explanation; flags.xml slims down + xrefs. + +- [ ] **FallbackResource / front-controller** recipe appears in four + places across three files (avoid.xml, remapping.xml ×2, htaccess.xml). + → avoid.xml owns it; others cross-reference. + +## MEDIUM Priority + +- [x] **index.xml is a mini-intro, not a TOC** — duplicates module + description and complexity warnings from intro.xml. + → Rewritten as concise intro + structured guide overview. + +- [ ] **Duplicate SSRF warning in flags.xml** — two nearly identical + warning boxes within the [P] flag section. + → Remove the literal duplicate. + +- [ ] **Two hostname canonicalization sections in remapping.xml** — + "canonicalhost" and "www-resolve" cover the same concept. + → Merge "www-resolve" into "canonicalhost". + +- [ ] **HTTPS redirect** covered in both avoid.xml and remapping.xml. + → remapping.xml owns the recipe; avoid.xml references it. + +## LOW Priority + +- [ ] **Harmonize `` blocks** — htaccess.xml not consistently + listed in other files' seealso despite being a major topic. + +- [ ] **Deprecated stub files** (access.xml, advanced.xml, proxy.xml) — + consider removal or ensure they don't appear in navigation. + +- [ ] **Figure numbering collision** — both intro.xml and tech.xml use + "Figure 1" for different images. diff --git a/docs/manual/rewrite/index.xml b/docs/manual/rewrite/index.xml index e33fdc25f7..e59a5e057d 100644 --- a/docs/manual/rewrite/index.xml +++ b/docs/manual/rewrite/index.xml @@ -32,53 +32,49 @@ expression rules. This allows you to map arbitrary URLs onto your internal URL structure in any way you like.

-

It supports an unlimited number of rules and an - unlimited number of attached rule conditions for each rule to - provide a really flexible and powerful URL manipulation - mechanism. The URL manipulations can depend on various tests: - server variables, environment variables, HTTP - headers, time stamps, external database lookups, and various other - external programs or handlers, can be used to achieve granular URL - matching.

- -

Rewrite rules can operate on the full URLs, including the path-info - and query string portions, and may be used in per-server context - (httpd.conf), per-virtualhost context (VirtualHost blocks), or - per-directory context - (.htaccess files and Directory blocks). The - rewritten result can lead to further rules, internal - sub-processing, external request redirection, or proxy - passthrough, depending on what flags you - attach to the rules.

- -

Since mod_rewrite is so powerful, it can indeed be rather - complex. This guide supplements the reference documentation, and - attempts to allay some of that complexity, and provide highly - annotated examples of common scenarios that you may handle with - mod_rewrite. But we also attempt to show you when you should not - use mod_rewrite, and use other standard Apache features instead, - thus avoiding this unnecessary complexity.

- - - +

This guide supplements the + reference manual with annotated examples, conceptual + explanations, and practical advice. It is organized as follows:

+ +
+
Introduction
+
Core concepts: regular expression syntax, RewriteRule and +RewriteCond basics, and how mod_rewrite fits into the request +processing lifecycle.
+ +
Per-directory Rewrites (.htaccess)
+
The key differences between using rewrite rules in server +configuration versus .htaccess files, including path +stripping, RewriteBase, and the looping behavior of the [L] flag.
+ +
RewriteRule Flags
+
A complete reference for all flags that can modify the behavior of +a RewriteRule, with examples for each.
+ +
Using RewriteMap
+
How to use external lookup sources — text files, DBM databases, +SQL queries, and internal functions — to drive your rewrite +rules.
+ +
Redirection and Remapping
+
Recipes for common tasks: HTTPS redirection, canonical hostnames, +trailing slash normalization, front-controller routing, and more.
+ +
Dynamic Virtual Hosts
+
Using mod_rewrite to dynamically map hostnames to document roots +without individual VirtualHost blocks.
+ +
When NOT to use mod_rewrite
+
Many common tasks are better accomplished with simpler directives. +This document shows the alternatives and when to prefer them.
+ +
Technical Details
+
How mod_rewrite hooks into the Apache request processing phases, +and the order in which rules and conditions are evaluated.
+
-mod_rewrite reference -documentation +The Reference Manual Mapping URLs to the Filesystem mod_rewrite wiki