diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js index 12ef22abe..a974c438f 100644 --- a/docs/.vuepress/config.js +++ b/docs/.vuepress/config.js @@ -225,7 +225,7 @@ module.exports = { '/how-to/websites-on-ipfs/link-a-domain', '/how-to/websites-on-ipfs/introducing-fleek', '/how-to/websites-on-ipfs/static-site-generators', - '/how-to/websites-on-ipfs/redirects-file-support' + '/how-to/websites-on-ipfs/redirects-and-custom-404s' ] }, { diff --git a/docs/how-to/websites-on-ipfs/redirects-and-custom-404s.md b/docs/how-to/websites-on-ipfs/redirects-and-custom-404s.md new file mode 100644 index 000000000..e4654fe7f --- /dev/null +++ b/docs/how-to/websites-on-ipfs/redirects-and-custom-404s.md @@ -0,0 +1,120 @@ +--- +title: Redirects and custom 404s +description: What the _redirect file is and how to use them with a website or single-page application (SPA) on IPFS. +--- +# Redirects, custom 404s, and SPA support + +::: callout +This feature is new, and requires Kubo 0.16 or later. +::: + +This feature enables support for redirects, [single-page applications](#catch-all-and-pwa-spa-support), [custom 404 pages](#add-a-custom-404-page-to-your-website), and moving to IPFS-backed hosting [without breaking existing links](https://www.w3.org/Provider/Style/URI). + +[[toc]] + +## Evaluation + +This feature is limited to websites hosted in web contexts with unique [Origins](https://en.wikipedia.org/wiki/Same-origin_policy) for content roots, e.g., [subdomain](/how-to/address-ipfs-on-web/#subdomain-gateway) or [DNSLink](/how-to/address-ipfs-on-web/#dnslink-gateway) gateways. + +Redirect logic will only be evaluated if the requested path is not in the [DAG](/concepts/glossary/#dag). Any performance impact associated with checking for the existence of a `_redirects` file or evaluating redirect rules will only be incurred for non-existent paths. If there are any errors reading or parsing the `_redirects` file, the error codes will be returned with an HTTP 500 status code. + +## How to set up + +To define rules executed when requested path is not found in DAG, there must be a file named `_redirects` stored underneath the root CID of the website. This `_redirects` file must be a text file containing one or more lines that follow the format explained below. + +## Format of the `_redirects` file + +Each line contained within the `_redirects` file has 3 basic components: + +```plaintext +from to [status] +``` + +1. The `from` path. This specifies the path to be redirected from. +1. The `to` path. This specifies the path to be redirected to. +1. The `status` component. This part is optional and specifies the HTTP status code that will be returned. (301, 404, etc.) + +For example, if you removed `home.html` and want to temporarily redirect traffic from `home.html` page to your `index.html` page, the `_redirects` file should contain a line that looks something like this: + +```plaintext +/home.html /index.html 302 +``` + + +### Status codes + +- `200` - OK (redirect will be treated as a rewrite, returning payload from alternative content path without changing the URL shown in the browser). +- `301` - Permanent redirect (the default status). +- `302` - Found (commonly used for temporary redirects). +- `404` - Not found (defines custom 404 page). +- `410` - Gone (the requested content has been permanently removed). +- `451` - Unavailable for legal reasons. + +### Placeholders + +Placeholders are named variables that can be used to match path segments in the `from` path and inject them into the `to` path. + +This is useful for redirecting users to their desired content, even if the way your website is organized changed . + +For example, if I wanted to search for an article titled "hello world" that was written on June 15, 2022, I could search for it like this: `/posts/06/15/2022/hello-world` and be redirected to `/articles/2022/06/15/hello-world` + +```plaintext +/posts/:month/:day/:year/:title /articles/:year/:month/:day/:title 301 +``` + +There is also special catch-all placeholder named `:splat` which represents everything captured via `*`. + +```plaintext +/blog/* /new-blog/:splat 302 +``` + +### Compatibility + +IPFS hosting supports only a subset of pre-existing standards supported by [Cloudflare](https://developers.cloudflare.com/pages/platform/redirects) and [Netlify](https://docs.netlify.com/routing/redirects/). +There is no overwrite/shadowing: the file is evaluated only when requested path is not found in a [DAG](/concepts/glossary/#dag). + +::: tip +For more detailed information about supported features, check out the [`_redirects` file specification](https://github.com/ipfs/specs/blob/main/http-gateways/REDIRECTS_FILE.md). +::: + + +## Examples + +### Catch all and PWA/SPA support + +The `200` status will be treated as a rewrite, returning OK without changing the URL shown in the browser. This staus code can be used to build [Progressive Web Apps](https://en.wikipedia.org/wiki/Progressive_web_app) and [Single Page Applications](https://en.wikipedia.org/wiki/Single-page_application). + +```plaintext +/app/* /app/index.html 200 +``` + +Opening `/app/this-does-not-exist` will return HTTP 200 response with content from `/app/index.html` + +### Redirect an old URL to a new place + +The `301` status is a permanent redirect, this is the default status code used when no code is specified. +Below two rules mean the same: + +```plaintext +/old/docs.html /new/documentation.html +/old/docs.html /new/documentation.html 301 +``` + +The `302` status is commonly used for temporary redirects. + +```plaintext +/home /under-construction.html 302 +``` + +For advanced and catch-all redirects, see [Placeholders](#placeholders) below. + +### Add a custom 404 page to your website + +Since the `_redirects` is evaluated only when requested path does not exist, +it is possibleto define a custom 404 page for your website: + +```plaintext +/* /custom-404.html 404 +``` + +With the above rule, opening `/this-does-not-exist` will return HTTP 404 Not Found error response with the payload of a custom error page defined in `custom-404.html`. diff --git a/docs/how-to/websites-on-ipfs/redirects-file-support.md b/docs/how-to/websites-on-ipfs/redirects-file-support.md deleted file mode 100644 index 33729209b..000000000 --- a/docs/how-to/websites-on-ipfs/redirects-file-support.md +++ /dev/null @@ -1,96 +0,0 @@ ---- -title: Redirects file support -description: What the _redirect file is and how to use them with a website on IPFS. ---- -## Redirects file support - -The `_redirects` file provides support for URL redirects and rewrites for websites hosted on subdomain or DNSLink gateways. This feature enables support for single-page applications, progressive web applications, custom 404 pages, and avoids link rot when moving to IPFS-backed hosting. On top of that, it also provides the ability to change the appearance of a URL, change where content is located without breaking existing links, and enable URL rewriting. - -This `_redirects` implementaion is a subset of pre-existing standards supported by [Cloudflare](https://developers.cloudflare.com/pages/platform/redirects) and [Netlify](https://docs.netlify.com/routing/redirects/). - -For more detailed information, check out the [`_redirects` file support specs](https://github.com/ipfs/specs/blob/main/http-gateways/REDIRECTS_FILE.md). - -## Supported HTTP status codes - -- `200` - OK (redirect will be treated as a rewrite, returning OK without changing the URL shown in the browser). -- `301` - Permanent redirect (the default status). -- `302` - Found (commonly used for temporary redirects). -- `404` - Not found (can be used redirect to custom 404 pages). -- `410` - Gone (the requested content has been permanently removed). -- `451` - Unavailable for legal reasons. - -## How to set up the `_redirects` file - -To use the `_redirects` file, there must be a file named `_redirects` stored underneath the root CID of the website. This `_redirects` file must be a text file containing one or more lines that follow the format explained below. - -### Format of the `_redirects` file - -Each line contained within the `_redirects` file has 3 basic components: - -1. The `from` path. This specifies the path to be redirected from. -1. The `to` path. This specifies the path to be redirected to. -1. The `status` component. This part is optional and specifies the HTTP status code that will be returned. (301, 404, etc.) - -For example, if you want to temporarily redirect traffic from your home page to your index page, the `_redirects` file should contain a line that looks something like this: - -```plaintext -/home /index.html 302 \n -``` - -The same format is used for all redirects. - -## Examples - -### Catch all and PWA/SPA support - -The `200` status will be treated as a rewrite, returning OK without changing the URL shown in the browser. This staus code can be used to build [Progressive Web Apps](https://en.wikipedia.org/wiki/Progressive_web_app) and [Single Page Applications](https://en.wikipedia.org/wiki/Single-page_application). - -```plaintext -/home /index.html 200 \n -``` - -### Redirect an old URL to a new place - -The `301` status is a permanent redirect, this is the default status code used when no others are spcified. - -```plaintext -/index /docs.html 301 \n -``` - -The `302` status is commonly used for temporary redirects. - -```plaintext -/home /under-construction.html 302 \n -``` - -### Add a custom 404 page to your website - -Use the `_redirects` file support to add a custom 404 page to your website. - -```plaintext -/home /custom-404.html 404 \n -``` - -### Placeholders - -Placeholders are named variables that can be used to match path segments in the `from` path and inject them into the `to` path. - -This is useful for redirecting users to their desired content, even if their search was not completely accurate. - -For example, if I wanted to search for an article titled "hello world" that was written on June 15, 2022, I could search for it like this: `/posts/06/15/2022/hello-world` and be redirected to `/articles/2022/06/15/hello-world` - -```plaintext -/posts//// /articles//// \n -``` - -## Evaluation - -The `_redirects` file is only supported on subdomain and DNSLink gateways, which provides [unique origin per root CID](https://en.wikipedia.org/wiki/Same-origin_policy). - -### No forced redirects - -Redirect logic will only be evaluated if the requested path is not in the DAG. Any performance impact associated with checking for the existence of a `_redirects` file or evaluating redirect rules will only be incurred for non-existent paths. - -## Error handling - -If there are any errors reading or parsing the `_redirects` file, the error codes will be returned with an HTTP 500 status code. \ No newline at end of file diff --git a/docs/how-to/websites-on-ipfs/single-page-website.md b/docs/how-to/websites-on-ipfs/single-page-website.md index ff6866a81..2df8d6ab6 100644 --- a/docs/how-to/websites-on-ipfs/single-page-website.md +++ b/docs/how-to/websites-on-ipfs/single-page-website.md @@ -7,6 +7,10 @@ description: Learn how to host a simple one-page website on IPFS and link up a d In this tutorial, we will host a simple one-page website on IPFS and link up a domain name. This is the first step is a series of tutorials to teach web developers on how to build websites and applications using IPFS. +::: callout +If you are looking for [single-page application (SPA)](https://en.wikipedia.org/wiki/Single-page_application) support, see [redirects and custom 404s](/how-to/websites-on-ipfs/redirects-and-custom-404s) instead. +::: + ## Install IPFS desktop IPFS desktop application is the easiest way to get up and running quickly with IPFS. The installation steps for IPFS desktop differ between operating systems. Follow the instructions for your system. @@ -254,3 +258,4 @@ This project was designed to get you up and running quickly, but there are many You may have noticed that when visiting [randomplanetfacts.xyz](http://randomplanetfacts.xyz), your browser redirects to [gateway.pinata.cloud/ipfs/QmW7S5HR...](https://gateway.pinata.cloud/ipfs/QmW7S5HRLkP4XtPNyT1vQSjP3eRdtZaVtF6FAPvUfduMjA). This isn't great for the user's experience, and it can cause issues with security certificates and other website validation methods. Also, this website is incredibly simple. There are no images, external stylesheets, or javascript files. If you're interested in building a more complex site using IPFS and securing it properly, [carry on with this tutorial series by hosting a multipage website on IPFS.](multipage-website.md) +