The htaccess to nginx cheat sheet for the Lizely converter covers a deliberately narrow subset: RewriteRule lines that use only the L, R, R=301, and R=302 flags, Options -Indexes, local ErrorDocument 404 paths, and a quoted X-Robots-Tag Header set value. Everything else — RewriteCond blocks, unfamiliar flags like QSA, END, F, G, B, or NC, the no-substitution dash, environment variables, proxy logic, and conditional headers — is reported with its original line number and left for manual work rather than silently guessed. The output is a reviewed fragment, not a complete nginx.conf, so each line must be placed in the correct server or location context, validated with nginx -t, and tested on representative requests before any reload. Patterns from a document-root .htaccess normally match a path with the directory prefix already removed, so the converter inserts the leading slash that Nginx rewrite patterns expect. Apache and Nginx process requests through different architectures, which is why an auditable mapping with explicit warnings is safer than a silent best-guess translation that could change traffic shape without anyone noticing.
What the Converter Recognizes (and What It Refuses to Guess)
The htaccess to nginx converter works as a bounded inventory tool rather than a universal translator. It accepts a focused excerpt — usually a document-root .htaccess rather than a nested one — and emits only the four directive forms listed above. Anything conditional, syntactically ambiguous, or outside the supported flag set comes back as a line-numbered warning instead of a guessed line. That decision is part of the contract: a converter that silently writes plausible-looking but non-equivalent configuration is more dangerous than one that leaves explicit work, because a line that compiles can still send real traffic to the wrong place.
Three categories are explicitly out of scope and always produce warnings:
- RewriteCond lines. Apache conditions can inspect HTTPS state, host names, files, directories, query strings, headers, and captured groups. Their evaluation order and the server architecture matter. When a RewriteRule follows a condition, the tool suppresses the rule too, rather than emitting an unconditional redirect that could change traffic, create a loop, or expose a route.
- RewriteRule flags outside {L, R, R=301, R=302}. Unknown flags such as QSA, END, F, G, B, or NC stop conversion for that rule because their details cannot be erased safely.
- The no-substitution dash target. Apache uses a literal dash to mean "do not rewrite the URI", often combined with flags that alter access or processing without changing the URL. A literal dash is not a safe Nginx replacement, so the warning is part of the result.
Other status codes for ErrorDocument, external error URLs, environment variables, directive containers such as <IfModule>, and any auth-related directives also stay out of scope and require manual migration.
The Cheat Sheet: Apache Lines and Their Nginx Counterparts
The table below summarizes the supported subset. It is drawn directly from the converter's documented mapping contract, not from a third-party port. Anything outside the table is intentionally left to manual work and surfaces as a warning.
| Apache directive | Example input | Nginx output | Notes |
|---|---|---|---|
| RewriteRule with [L] | RewriteRule ^old$ /new [L] | rewrite ^/old$ /new last; | Internal last rule, no client round trip. |
| RewriteRule with [R=301] | RewriteRule ^old$ /new [R=301,L] | rewrite ^/old$ /new permanent; | Permanent redirect; browsers and CDNs may cache aggressively. |
| RewriteRule with [R=302] | RewriteRule ^old$ /new [R=302,L] | rewrite ^/old$ /new redirect; | Temporary redirect; safer for staged rollouts. |
| RewriteRule with bare [R] | RewriteRule ^old$ /new [R,L] | rewrite ^/old$ /new redirect; | Apache defaults bare R to 302; converter follows the same convention. |
| RewriteRule with capture | RewriteRule ^blog/(.*)$ /news/$1 [L,R=301] | rewrite ^/blog/(.*)$ /news/$1 permanent; | Capture backreferences are preserved as $1, $2, and so on. |
| Options -Indexes | Options -Indexes | autoindex off; | Disables directory listing for the surrounding context. |
| ErrorDocument 404 (local) | ErrorDocument 404 /404.html | error_page 404 /404.html; | Only the 404 status with a local path is mapped; external URLs and other codes require manual work. |
| Header set X-Robots-Tag | Header set X-Robots-Tag "noindex" | add_header X-Robots-Tag "noindex"; | Only a quoted static value is mapped; conditional headers and unset/envvar values stay manual. |
| RewriteRule with [QSA], [END], [F], [G], [B], [NC] | RewriteRule ^x$ y [QSA,L] | Warning at original line number | Unknown flag; no line emitted. |
| RewriteCond (any) | RewriteCond %{HTTPS} off | Warning at original line number | Conditions are never translated; following rule is also suppressed. |
| RewriteRule - (dash target) | RewriteRule .* - [L] | Warning at original line number | No-substitution target withheld; common combined with access-altering flags. |
How to Run the Conversion and Resolve the Warnings
Use this sequence every time. It keeps the bounded scope of the tool intact and prevents a clean syntax check from masking a context error.
- Copy a focused excerpt from a document-root .htaccess. Authentication, authorization, hotlink protection, proxy logic, and CMS front-controller rules do not belong in this tool — treat that migration as engineering work.
- Paste the excerpt into the htaccess to nginx converter form. Processing happens in the browser; the input is not sent to Lizely.
- Read every emitted Nginx line against the Apache mod_rewrite introduction and the Nginx rewrite module documentation. The output is a fragment, not a complete configuration file.
- Resolve each line-numbered warning manually. A warning is a checklist item: it tells you exactly which Apache line was not converted and why.
- Merge the reviewed lines into the appropriate Nginx context — typically a server block for redirects and error pages, or a location block for path-scoped rewrites — in a version-controlled file.
- Back up the active configuration, keep an open recovery session, and run nginx -t against the full assembled configuration before any reload.
- Stage representative requests on a reversible maintenance window: old paths, new paths, query strings, alternate hosts, and HTTPS behavior.
- For permanent redirects, start with the temporary form in a controlled environment, switch to permanent only after confirming the response Location header (not the browser address bar alone), and accept that browsers and intermediaries may cache permanent redirects aggressively.
Why the Mapping Stops at Four Directives
The four supported mappings — rewrite, autoindex, error_page, add_header — cover the cases that translate cleanly between Apache's per-directory configuration model and Nginx's centralized, context-selected one. Going further means making architectural assumptions the tool cannot verify from the pasted excerpt alone.
For example, RewriteCond %{HTTPS} off followed by a redirect rule looks like it should become an if ($scheme = http) block, but the same rule in a nested .htaccess, an Alias mapping, or a location that already handles HTTPS differently does something else. Per the Apache mod_rewrite introduction, condition variables, captures, and evaluation order change meaning depending on where the rule sits. The converter reports the line and stops.
The same conservatism applies to the leading-slash insertion. A document-root .htaccess pattern usually begins with a caret but no slash, because Apache strips the directory prefix before matching. Nginx rewrite patterns see a URI that begins with slash. The tool inserts that slash for the supported root-context pattern and calls it a documented scope assumption, not a universal transformation for nested .htaccess files, Alias mappings, or location-specific Nginx blocks.
After the Cheat Sheet: Placement, Validation, and Reload
A line can be syntactically valid yet wrong for its context. The fragment does not create an http, server, or location block, choose a listen port, set server_name, configure TLS, locate a document root, preserve PHP routing, forward a proxy, or define logs. Placement belongs to the operator, not the converter.
For an autoindex off; line, the conventional home is inside the server or location block that controls the directory you want to protect. For error_page 404 /404.html;, the same applies and the path must resolve against the document root or a root directive in scope — the Nginx core error_page documentation is the authoritative reference for status codes and URI forms. For add_header X-Robots-Tag "noindex";, scope matters because add_header only emits when the response status allows header insertion, so test the actual response rather than the rewritten text.
Before reload, validate the full assembled configuration with nginx -t, confirm the include order, and stage the change. A failed reload or redirect loop can make a public site unavailable, and permanent redirects deserve extra care because browsers and intermediaries may cache them. If you are moving from Apache under load, the existing patterns in your .htaccess probably also include authorization, environment variables, or front-controller logic that the converter never touches — keep that work on a separate plan and verify each piece against the official Nginx directive documentation for its target context. For zero-downtime rollout specifics, the Nginx reload without downtime guide covers the order of operations once the assembled file passes nginx -t.