From 2b5697242bac1fe96109c8c4e94ac3bd8df46044 Mon Sep 17 00:00:00 2001 From: TMoMoreau Date: Wed, 7 Sep 2022 11:04:40 -0400 Subject: [PATCH 01/12] Creating branch and adding the page to `config.js` --- docs/.vuepress/config.js | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js index 34cd39043..4abe31a84 100644 --- a/docs/.vuepress/config.js +++ b/docs/.vuepress/config.js @@ -224,7 +224,8 @@ module.exports = { '/how-to/websites-on-ipfs/multipage-website', '/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/static-site-generators', + '/how-to/websites-on-ipfs/gateway-redirects' ] }, { From 11b53bc055fb0c89d4d17972f439e89b1b0ab83b Mon Sep 17 00:00:00 2001 From: TMoMoreau Date: Wed, 7 Sep 2022 11:48:02 -0400 Subject: [PATCH 02/12] Very rough draft --- .../websites-on-ipfs/gateway-redirects.md | 91 +++++++++++++++++++ 1 file changed, 91 insertions(+) create mode 100644 docs/how-to/websites-on-ipfs/gateway-redirects.md diff --git a/docs/how-to/websites-on-ipfs/gateway-redirects.md b/docs/how-to/websites-on-ipfs/gateway-redirects.md new file mode 100644 index 000000000..3423e2098 --- /dev/null +++ b/docs/how-to/websites-on-ipfs/gateway-redirects.md @@ -0,0 +1,91 @@ +--- +title: Gateway redirects +description: What gateway redirects are and how to use them with a website on IPFS. +--- + +# THIS IS A DRAFT. DO NOT MERGE. + +# To do: +1. How to redirect old URL to a new place (301 and 302 redirects) +1. How to use it for PWA/SPA hosting (catch-all 200) +1. How to use it to provide custom `404 not found` pages (superceding what `ipfs-404.html` does - ideally not mention old way) + +# Gateway Redirects + +Gateway Redirects provide support for URL redirects and rewrites for websites hosted on Subdomain or DNSLink gateways. This feature enables support for single-page applications, and avoids link rot when moving to IPFS-backed hosting. + +Using Gateway Redirects, you can change the appearance of a URL, change where content is located without breaking existing links, redirect invalid URLs to a custom 404 page, and enable URL rewriting. + +# 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). +* `303` - See other (replaces PUT and POST with GET). +* `307` - Temporary redirect (preserves the body and HTTP method of the original request). +* `308` - Permanent redirect (preserves the body and HTTP method of the original request). +* `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 gateway redirects + +To use Gateway Redirects, 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 I want to redirect a page to a custom `404` page, the `_redirects` file will contain a line that looks something like this: +``` +/ /custom404.html 404 +``` + +The same format is used for all redirects. + +## Placeholders + +Placeholders are named variables that can be used to match path segments in the `from` path and inject them into the `to` path. + +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` + +## Splat + +If the `from` path ends with an asterisk (`*`), the rest of the `from` path will be slurped up into the special `:splat` placeholder, which can then be injected into the `to` path. +``` +/posts/* /articles/:splat +``` +:::note +Splat logic must only apply to a single trailing asterisk, as it is a greedy match that consumes the remainder of the path. ::: + +## Comments + +Any line in the `_redirects` file that begins with `#` will be ignored and treated as a comment. + +## Line termination + +Each line in the `_redirects` file must be terminated with either `\n` or `\r\n`. + +``` +/ /custom404.html 404 \n +/home /index.html \n +``` +# Evaluation + +Rules must only be evaluated when hosted on a subdomain or DNSLink gateway, this is to maintain same-origin isolation. + +## Order + +Rules must be evaluated in order, redirecting or rewriting using the first matching pair. + +## 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 From a86b0bf5db80a7bc63351688256d55de494f099c Mon Sep 17 00:00:00 2001 From: TMoMoreau Date: Tue, 20 Sep 2022 16:34:10 -0400 Subject: [PATCH 03/12] Updated name, addressing suggestions --- docs/.vuepress/config.js | 2 +- .../websites-on-ipfs/gateway-redirects.md | 79 ++++++++++--------- 2 files changed, 43 insertions(+), 38 deletions(-) diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js index 4abe31a84..518fdc712 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/gateway-redirects' + '/how-to/websites-on-ipfs/_redirects-file-support' ] }, { diff --git a/docs/how-to/websites-on-ipfs/gateway-redirects.md b/docs/how-to/websites-on-ipfs/gateway-redirects.md index 3423e2098..b1a839bc8 100644 --- a/docs/how-to/websites-on-ipfs/gateway-redirects.md +++ b/docs/how-to/websites-on-ipfs/gateway-redirects.md @@ -1,36 +1,27 @@ --- -title: Gateway redirects -description: What gateway redirects are and how to use them with a website on IPFS. +title: _redirects file support +description: What the _redirect file is and how to use them with a website on IPFS. --- +# `_redirects` file support -# THIS IS A DRAFT. DO NOT MERGE. +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. As well as the ability to change the appearance of a URL, change where content is located without breaking existing links, and enable URL rewriting. -# To do: -1. How to redirect old URL to a new place (301 and 302 redirects) -1. How to use it for PWA/SPA hosting (catch-all 200) -1. How to use it to provide custom `404 not found` pages (superceding what `ipfs-404.html` does - ideally not mention old way) +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/). -# Gateway Redirects - -Gateway Redirects provide support for URL redirects and rewrites for websites hosted on Subdomain or DNSLink gateways. This feature enables support for single-page applications, and avoids link rot when moving to IPFS-backed hosting. - -Using Gateway Redirects, you can change the appearance of a URL, change where content is located without breaking existing links, redirect invalid URLs to a custom 404 page, and enable URL rewriting. +For more detailed information, check out the [`_redirects` file support specs](https://github.com/ipfs/specs/pull/290). # 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). -* `303` - See other (replaces PUT and POST with GET). -* `307` - Temporary redirect (preserves the body and HTTP method of the original request). -* `308` - Permanent redirect (preserves the body and HTTP method of the original request). * `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 gateway redirects +# How to set up the `_redirects` file -To use Gateway Redirects, 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. +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 @@ -40,47 +31,61 @@ Each line contained within the `_redirects` file has 3 basic components: 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 I want to redirect a page to a custom `404` page, the `_redirects` file will contain a line that looks something like this: +For example, if for whatever reason I wanted to temporarily redirect traffic from my home page to my index page, the `_redirects` file will contain a line that looks something like this: + ``` -/ /custom404.html 404 +/home /index.html 302 \n ``` The same format is used for all redirects. -## Placeholders +# Examples -Placeholders are named variables that can be used to match path segments in the `from` path and inject them into the `to` path. +## Catch all and PWA/SPA support -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` +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). -## Splat +``` +/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. -If the `from` path ends with an asterisk (`*`), the rest of the `from` path will be slurped up into the special `:splat` placeholder, which can then be injected into the `to` path. ``` -/posts/* /articles/:splat +/index /docs.html 301 \n ``` -:::note -Splat logic must only apply to a single trailing asterisk, as it is a greedy match that consumes the remainder of the path. ::: -## Comments +The `302` status is commonly used for temporary redirects. -Any line in the `_redirects` file that begins with `#` will be ignored and treated as a comment. +``` +/home /under-construction.html 302 \n +``` -## Line termination +## Add a custom 404 page to your website -Each line in the `_redirects` file must be terminated with either `\n` or `\r\n`. +Use the `_redirects` file support to add a custom 404 page to your website. ``` -/ /custom404.html 404 \n -/home /index.html \n +/home /custom-404.html 404 \n ``` -# Evaluation -Rules must only be evaluated when hosted on a subdomain or DNSLink gateway, this is to maintain same-origin isolation. +## 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. -## Order +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` + +``` +/posts//// /articles//// \n +``` + +# Evaluation -Rules must be evaluated in order, redirecting or rewriting using the first matching pair. +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 From 486e3cf674525b9b21efd63d1ecc78b4128e49d9 Mon Sep 17 00:00:00 2001 From: TMoMoreau Date: Wed, 21 Sep 2022 14:22:23 -0400 Subject: [PATCH 04/12] Attempt to fix vuepress build --- docs/.vuepress/config.js | 2 +- docs/how-to/websites-on-ipfs/gateway-redirects.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js index 518fdc712..12ef22abe 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-file-support' ] }, { diff --git a/docs/how-to/websites-on-ipfs/gateway-redirects.md b/docs/how-to/websites-on-ipfs/gateway-redirects.md index b1a839bc8..f0edb4cfb 100644 --- a/docs/how-to/websites-on-ipfs/gateway-redirects.md +++ b/docs/how-to/websites-on-ipfs/gateway-redirects.md @@ -1,5 +1,5 @@ --- -title: _redirects file support +title: redirects file support description: What the _redirect file is and how to use them with a website on IPFS. --- # `_redirects` file support From c660fe6f39fbe02e6857fdfc2efece067eeebf82 Mon Sep 17 00:00:00 2001 From: TMoMoreau Date: Wed, 21 Sep 2022 14:31:46 -0400 Subject: [PATCH 05/12] Change file name --- .../redirects-file-support.md | 96 +++++++++++++++++++ 1 file changed, 96 insertions(+) create mode 100644 docs/how-to/websites-on-ipfs/redirects-file-support.md diff --git a/docs/how-to/websites-on-ipfs/redirects-file-support.md b/docs/how-to/websites-on-ipfs/redirects-file-support.md new file mode 100644 index 000000000..f0edb4cfb --- /dev/null +++ b/docs/how-to/websites-on-ipfs/redirects-file-support.md @@ -0,0 +1,96 @@ +--- +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. As well as 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/pull/290). + +# 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 for whatever reason I wanted to temporarily redirect traffic from my home page to my index page, the `_redirects` file will contain a line that looks something like this: + +``` +/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). + +``` +/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. + +``` +/index /docs.html 301 \n +``` + +The `302` status is commonly used for temporary redirects. + +``` +/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. + +``` +/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` + +``` +/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 From bc1208cd7a1f5f27cefd53b3da0b2ca2f600c775 Mon Sep 17 00:00:00 2001 From: T Mo <91539446+TMoMoreau@users.noreply.github.com> Date: Wed, 21 Sep 2022 14:32:29 -0400 Subject: [PATCH 06/12] Delete gateway-redirects.md --- .../websites-on-ipfs/gateway-redirects.md | 96 ------------------- 1 file changed, 96 deletions(-) delete mode 100644 docs/how-to/websites-on-ipfs/gateway-redirects.md diff --git a/docs/how-to/websites-on-ipfs/gateway-redirects.md b/docs/how-to/websites-on-ipfs/gateway-redirects.md deleted file mode 100644 index f0edb4cfb..000000000 --- a/docs/how-to/websites-on-ipfs/gateway-redirects.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. As well as 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/pull/290). - -# 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 for whatever reason I wanted to temporarily redirect traffic from my home page to my index page, the `_redirects` file will contain a line that looks something like this: - -``` -/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). - -``` -/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. - -``` -/index /docs.html 301 \n -``` - -The `302` status is commonly used for temporary redirects. - -``` -/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. - -``` -/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` - -``` -/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 From 8cb4422ee227ae7f09dfdc1fbc7dc83bdceb2434 Mon Sep 17 00:00:00 2001 From: TMoMoreau Date: Wed, 21 Sep 2022 14:37:43 -0400 Subject: [PATCH 07/12] Update link to where the spec will be --- docs/how-to/websites-on-ipfs/redirects-file-support.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/how-to/websites-on-ipfs/redirects-file-support.md b/docs/how-to/websites-on-ipfs/redirects-file-support.md index f0edb4cfb..93fd9af18 100644 --- a/docs/how-to/websites-on-ipfs/redirects-file-support.md +++ b/docs/how-to/websites-on-ipfs/redirects-file-support.md @@ -8,7 +8,7 @@ The `_redirects` file provides support for URL redirects and rewrites for websit 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/pull/290). +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 From 176bc27b320419a896988dd63564d26a017210ab Mon Sep 17 00:00:00 2001 From: TMoMoreau Date: Thu, 22 Sep 2022 11:42:22 -0400 Subject: [PATCH 08/12] Addressing Johnny's suggestions --- .../redirects-file-support.md | 48 +++++++++---------- 1 file changed, 24 insertions(+), 24 deletions(-) diff --git a/docs/how-to/websites-on-ipfs/redirects-file-support.md b/docs/how-to/websites-on-ipfs/redirects-file-support.md index 93fd9af18..6b131870d 100644 --- a/docs/how-to/websites-on-ipfs/redirects-file-support.md +++ b/docs/how-to/websites-on-ipfs/redirects-file-support.md @@ -1,37 +1,37 @@ --- -title: redirects file support +title: Redirects file support description: What the _redirect file is and how to use them with a website on IPFS. --- -# `_redirects` file support +## 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. As well as the ability to change the appearance of a URL, change where content is located without breaking existing links, and enable URL rewriting. +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 +## 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. +- `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 +## 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 +### 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.) +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 for whatever reason I wanted to temporarily redirect traffic from my home page to my index page, the `_redirects` file will contain a line that looks something like this: +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: ``` /home /index.html 302 \n @@ -39,9 +39,9 @@ For example, if for whatever reason I wanted to temporarily redirect traffic fro The same format is used for all redirects. -# Examples +## Examples -## Catch all and PWA/SPA support +### 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). @@ -49,7 +49,7 @@ The `200` status will be treated as a rewrite, returning OK without changing the /home /index.html 200 \n ``` -## Redirect an old URL to a new place +### 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. @@ -63,7 +63,7 @@ The `302` status is commonly used for temporary redirects. /home /under-construction.html 302 \n ``` -## Add a custom 404 page to your website +### Add a custom 404 page to your website Use the `_redirects` file support to add a custom 404 page to your website. @@ -71,7 +71,7 @@ Use the `_redirects` file support to add a custom 404 page to your website. /home /custom-404.html 404 \n ``` -## Placeholders +### Placeholders Placeholders are named variables that can be used to match path segments in the `from` path and inject them into the `to` path. @@ -83,14 +83,14 @@ For example, if I wanted to search for an article titled "hello world" that was /posts//// /articles//// \n ``` -# Evaluation +## 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 +### 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 +## 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 From ba3beb89da1c634d668bcccc6154115d16bcd97c Mon Sep 17 00:00:00 2001 From: TMoMoreau Date: Thu, 22 Sep 2022 12:35:19 -0400 Subject: [PATCH 09/12] Adding syntax to codeblocks --- .../websites-on-ipfs/redirects-file-support.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/how-to/websites-on-ipfs/redirects-file-support.md b/docs/how-to/websites-on-ipfs/redirects-file-support.md index 6b131870d..33729209b 100644 --- a/docs/how-to/websites-on-ipfs/redirects-file-support.md +++ b/docs/how-to/websites-on-ipfs/redirects-file-support.md @@ -33,7 +33,7 @@ Each line contained within the `_redirects` file has 3 basic components: 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 ``` @@ -45,7 +45,7 @@ The same format is used for all redirects. 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 ``` @@ -53,13 +53,13 @@ The `200` status will be treated as a rewrite, returning OK without changing the 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 ``` @@ -67,7 +67,7 @@ The `302` status is commonly used for temporary redirects. Use the `_redirects` file support to add a custom 404 page to your website. -``` +```plaintext /home /custom-404.html 404 \n ``` @@ -79,7 +79,7 @@ This is useful for redirecting users to their desired content, even if their sea 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 ``` From e0843d5a5e37654d7d89ba94eb24174f898bf3fe Mon Sep 17 00:00:00 2001 From: Marcin Rataj Date: Fri, 23 Sep 2022 20:09:38 +0200 Subject: [PATCH 10/12] Update content based on merged code Based on things provided by https://github.com/ipfs/kubo/pull/8890 --- docs/.vuepress/config.js | 2 +- .../redirects-and-custom-404s.md | 120 ++++++++++++++++++ .../redirects-file-support.md | 96 -------------- .../websites-on-ipfs/single-page-website.md | 5 + 4 files changed, 126 insertions(+), 97 deletions(-) create mode 100644 docs/how-to/websites-on-ipfs/redirects-and-custom-404s.md delete mode 100644 docs/how-to/websites-on-ipfs/redirects-file-support.md 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) + From 2a6cb1694efc22ad6aec38299054c7e8b3a382b4 Mon Sep 17 00:00:00 2001 From: TMoMoreau Date: Mon, 26 Sep 2022 09:56:15 -0400 Subject: [PATCH 11/12] Small changes to format/grammar/etc. --- .../redirects-and-custom-404s.md | 18 ++++++++---------- 1 file changed, 8 insertions(+), 10 deletions(-) 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 index e4654fe7f..b1f4d7334 100644 --- a/docs/how-to/websites-on-ipfs/redirects-and-custom-404s.md +++ b/docs/how-to/websites-on-ipfs/redirects-and-custom-404s.md @@ -20,9 +20,9 @@ Redirect logic will only be evaluated if the requested path is not in the [DAG]( ## 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. +To define rules that will be executed when the requested path is not found in the 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 +### Format of the `_redirects` file Each line contained within the `_redirects` file has 3 basic components: @@ -34,13 +34,12 @@ from to [status] 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: +For example, if you removed `home.html` and want to temporarily redirect traffic from `home.html` to `index.html`, 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). @@ -54,7 +53,7 @@ For example, if you removed `home.html` and want to temporarily redirect traffic 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 . +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` @@ -62,7 +61,7 @@ For example, if I wanted to search for an article titled "hello world" that was /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 `*`. +There is also a special catch-all placeholder named `:splat` which represents everything captured via `*`. ```plaintext /blog/* /new-blog/:splat 302 @@ -77,7 +76,6 @@ There is no overwrite/shadowing: the file is evaluated only when requested path 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 @@ -93,7 +91,7 @@ Opening `/app/this-does-not-exist` will return HTTP 200 response with content fr ### 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: +The two rules below mean the same thing: ```plaintext /old/docs.html /new/documentation.html @@ -106,12 +104,12 @@ The `302` status is commonly used for temporary redirects. /home /under-construction.html 302 ``` -For advanced and catch-all redirects, see [Placeholders](#placeholders) below. +For advanced and catch-all redirects, see [Placeholders](#placeholders). ### 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: +it is possible to define a custom 404 page for your website: ```plaintext /* /custom-404.html 404 From 0dc5504d0fe41cf311b35a307b98103c6b36245d Mon Sep 17 00:00:00 2001 From: TMoMoreau Date: Tue, 27 Sep 2022 00:03:54 -0400 Subject: [PATCH 12/12] Removed `[[toc]]` --- docs/how-to/websites-on-ipfs/redirects-and-custom-404s.md | 2 -- 1 file changed, 2 deletions(-) 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 index b1f4d7334..b4dc12968 100644 --- a/docs/how-to/websites-on-ipfs/redirects-and-custom-404s.md +++ b/docs/how-to/websites-on-ipfs/redirects-and-custom-404s.md @@ -10,8 +10,6 @@ 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.