fortropp.toml
/fortropp.toml is an optional config file that lives at the root of your uploaded files,
generated by default or uploaded like any other file. It controls which subdirectory is served as
your site's root, and lets you define redirects and custom response headers.
An auto-generated reference of every key and type is at fortropp.toml schema.
Default behaviour
Every new website starts with a generated fortropp.toml that serves the top level
of your files, sends /blog to /blog/ when /blog/index.html exists, serves /about.html at /about, and sends missing pages to your /404.html:
version = 1
[build]
publish = "/"
trailing_slash = "add"
[[redirects]]
from = "/*"
to = "/:splat.html"
# e.g. /about serves /about.html, /docs/intro serves /docs/intro.html
status = 200
[[redirects]]
from = "/*"
to = "/404.html"
status = 404 If you delete the file, default rules apply instead: the site root is served from the top level of your uploaded files, and no redirects (including the 404 page) or extra headers are applied.
Either way, / and any path ending in / serve that directory's index.html; that's built in and needs no rule. For example, / serves /index.html and /blog/ serves /blog/index.html.
If the fortropp.toml file exists but fails to parse, that's treated as an error at
upload time rather than invisibly falling back to the default rules. Unknown keys are errors
too, so a typo like [[redirect]] or publsh is caught instead of silently ignored.
Version
Every fortropp.toml starts with version = 1, at the top of the file
before any [section]. 1 is the only version, and a file without it is an
error. The generated file already has it.
Paths
Every local path in this file follows the same rules:
- It starts with
/. A trailing/is allowed. - No relative or empty segments:
.,..and//are errors. *is only allowed as the whole last segment, as in/blog/*, and only infromandfor./blog*,/*/editand/a/**are errors.
to in [[redirects]] can also be a URL: https://, then a
domain name (no IP addresses or localhost), an optional :port, and an optional path and query. The host must be lowercase, and there can't
be a user@ or user:password@ part before it. The path follows the same rules
as a local path.
Paths may contain any characters. A request for /caf%C3%A9.html and a rule written
as /café.html name the same file, and a percent-encoded %3F or %23 is part of a file name (/a%3Fb serves the file /a?b), never the start of a query. An encoded slash (%2F) is never
treated as a folder separator.
[build]
publish = "/dist" # subdir of your files to treat as the site root
# default "/" (site root)
trailing_slash = "add" # "add", "remove" or "ignore"; default "ignore" publish is applied first, as a route remap. Every other path in this file, from and to in [[redirects]], for in [[headers]], and the local-file existence check force depends
on, is resolved against the remapped site root, not the raw upload tree. /fortropp.toml itself is the one exception: it's always read from the true upload root, and that file is never
served to visitors.
Every file under the publish directory can be requested by anyone who knows its name,
including files you might not mean to share, such as a stray .env. If your
upload contains more than the site itself, put the site in a folder like /dist and set publish to it; files outside that folder are never served.
trailing_slash is applied next, before any [[redirects]]:
"add": a request for/blogis redirected (301) to/blog/when there's no file called/blogbut there is a/blog/index.html. Relative links inside that page then work as expected."remove": the reverse./blog/is redirected to/blog, and/blogmay serve/blog/index.html. That index then also counts as the file at/blogforforce(see below)."ignore", or left out: no redirects either way.
The query string is kept, and paths without a matching directory are left alone.
Each [[redirects]] block matches a request path and redirects or rewrites it.
[[redirects]]
from = "/old-path"
to = "/new-path"
status = 301 # what to do when `from` matches — see below
force = false # whether to apply even if a file is found at `from`
[[redirects]]
from = "/api/*"
to = "https://api.example.com/:splat"
status = 200
force = true
[[redirects]]
from = "/*"
to = "/404.html"
status = 404
# force defaults to false, so this rule only applies to missing files from supports a trailing * wildcard, matching the folder and
everything in it, however many more path segments follow: /blog/* matches /blog/ and /blog/2024/post. /blog/* doesn't apply to /blog, unless /blog is where /blog/index.html is
served (trailing_slash = "remove"). So a page like /blog.html served at /blog is left alone; add a from = "/blog" rule to catch it too. trailing_slash runs first: with "remove" and a /blog/index.html, /blog/ is redirected to /blog,
where this rule then applies.
A from without a wildcard matches exactly that path: /old matches /old but not /old/, which is the address of a folder. Write both
if you want both. The same matching applies to for in [[headers]]. trailing_slash only redirects paths whose folder
has an index.html, so for addresses that don't exist on your site, both
spellings reach your rules.
What to means depends on status:
- 301 / 302 — a real redirect. The browser navigates to
to. - 200 — a rewrite.
tois the content served atfrom's URL; the browser's address bar doesn't change. - 404 — same as 200 (
tois what gets served), but the response is tagged with a 404 status instead of 200. To use a catch-all error page, setfrom = "/*"to serve your own 404 page at any empty routes. If unset, the platform default is that no custom 404 route will be defined.tomust be a path on your site.
to can reference the matched portion of from with :splat, written as a whole path segment (/news/:splat). It can
be followed by a file extension in the last segment, as in /:splat.html. When
nothing was matched, the folder is kept (/blog/ → /news/), and a :splat with an extension doesn't apply at all. Using :splat in to when from has no wildcard is an error at upload time.
Redirects and proxies merge query strings: the parameters written in to come
first, followed by the visitor's. When both have the same parameter, the one in to wins. Names are compared decoded, so caf%C3%A9 and café are the same parameter. A rule to = "/new?from=old" sends a
visit to /old?page=2 to /new?from=old&page=2.
Requests are read the way browsers send them, under the WHATWG URL Standard. Redirect locations and proxied URLs pass the visitor's path on exactly as they sent it: %3B stays %3B and ; stays ;. The only
change is that characters browsers allow but RFC 3986 doesn't (|, [, ], and a % not followed by
two hex digits) are percent-encoded, which doesn't change what the path means.
force defines whether the rule also applies when a file is found at from. It defaults to false.
Rules are evaluated in the order they're written. For a given request, each rule is
checked top to bottom; a rule only counts as a match if from matches the path and one of these is true: force is true, or no file
exists at that path. The first matching rule wins and later rules are not checked. force does not reorder rules or let a later rule preempt an earlier one, it only changes whether that
rule itself counts as a match when a file exists.
A rule that serves a file from your site (status = 200 or 404 with a local to) also only counts as a match if that file exists. Otherwise
the next rule is tried.
Some cases that follow from these rules, in an order that works:
# /blog/2024/post → /news/2024/post
# /blog/ → /news/ (an empty :splat keeps the folder)
# It sits first: the catch-alls below would match /blog/ first.
[[redirects]]
from = "/blog/*"
to = "/news/:splat"
status = 301
# If /old.html still exists, it's served and this never fires.
# Add force = true to redirect anyway.
[[redirects]]
from = "/old.html"
to = "/new.html"
status = 301
# /about → /about.html if it exists, otherwise the next rule
# /about/ → the next rule (a :splat with an extension never
# matches a path ending in /)
[[redirects]]
from = "/*"
to = "/:splat.html"
status = 200
# Whatever is left and missing gets /404.html
[[redirects]]
from = "/*"
to = "/404.html"
status = 404Each [[headers]] block applies a set of response headers to paths matching for.
[[headers]]
for = "/*"
[headers.values]
X-Frame-Options = "DENY"
Auth = "skdnaksnf"
[[headers]]
for = "/assets/*"
[headers.values]
Cache-Control = "public, max-age=31536000, immutable"
[[headers]]
for = "/content/*"
[headers.values]
Auth = "kajsndkjsnfkns"
# a request for /content/a.json matches the first and third blocks, merged:
# X-Frame-Options: DENY (from "/*", no conflict)
# Auth: kajsndkjsnfkns ("/content/*" is more specific than "/*")
# (Cache-Control is not applied — "/assets/*" doesn't match this path) for supports a trailing * wildcard, same as from in [[redirects]]: /blog/* doesn't apply to /blog,
unless /blog is where /blog/index.html is served (trailing_slash = "remove").
Header names follow the HTTP standard (RFC 9110): letters, digits and !#$%&'*+-.^_`|~. They're case-insensitive, so Cache-Control and cache-control are the same header. Each name can
appear only once per block.
Header values must be plain ASCII: letters, digits, punctuation, spaces and tabs. They can't contain line breaks or other control characters, and can't start or end with whitespace. To put other characters in a header, percent-encode them yourself.
Unlike redirects, headers merge: every [[headers]] block
whose for matches the request contributes its headers. If two matching blocks set
the same header key, the one with the more specific for wins for that key.
Specificity is measured by the path length before a trailing *, with an exact
(no-wildcard) for always beating a wildcard one — so for = "/content/*" outranks for = "/*" for any path under /content/.
If two blocks have the exact same for and set the same header (in any capitalization),
there's no specificity to break the tie, so that's treated as an error at upload time rather
than picking one arbitrarily.
Headers on rewrites. A status = 200 or 404 redirect serves content from to, but the browser's address bar still shows from. [[headers]] matching follows what the client sees: blocks are matched against from, not to.
Headers on 301 / 302. These are real redirects, the browser makes a brand
new request to to. That new request goes through normal [[headers]] matching against to like any other request. [[headers]] blocks
matching from don't apply to the redirect response itself, and neither do
they apply to any redirects caused by a trailing_slash rule.
Proxying to an external origin. If to is an absolute URL
(like the /api/* example above), a status = 200 rule proxies instead of serving a local file:
the full request — method, request headers, body, query string — is forwarded to to, and the response, including its status code, is streamed back. Redirects
from that server are passed back to the browser rather than followed. Headers that only
concern a single connection (Connection, Upgrade, Keep-Alive and the like) are not forwarded, so WebSockets can't be proxied.
fortropp tells your server who it is proxying for: the first address in X-Forwarded-For is the visitor's IP (any later addresses are network hops), X-Forwarded-Host is your site's hostname and X-Forwarded-Proto says whether the visitor used https. Any X-Forwarded-For, X-Forwarded-Host, X-Forwarded-Proto, X-Real-IP or Forwarded header
the visitor sent is dropped first, so your server can trust these three. Every other
header is passed along as the visitor sent it, so don't use any other header to identify
the visitor. force works the same as any other rule: the file-existence check still
happens before rerouting. [[headers]] still apply as usual, matched against from; if a header set locally collides
with one the upstream response already has, the local one wins.
Rewrites don't chain. For 200 / 404, the to is served as-is; it is not itself checked against [[redirects]] again. If you need multiple hops, write each one out as its own rule pointing straight at the
final target. This also means two such rules can't form a loop.
Request methods. Files on your site answer GET and HEAD (the same response without a body); other methods, like POST, get a 405. A path with no file is a 404 whatever the method. Proxied
paths forward GET, HEAD, POST, PUT, PATCH, DELETE and OPTIONS. Any other method gets a 501 everywhere on your site.
Preview links. Your preview link applies this file exactly as the live
site does, and adds X-Robots-Tag: noindex to every response so search engines don't
index it.
301 / 302 don't have that protection: since the browser makes a real new
request to to, that request goes through [[redirects]] matching again like any
other request. Two 301 rules pointing at each other will loop. That's on whoever wrote the config,
not something the platform can prevent.