Merge pull request #2145 from ably/act-163-img-fix

[WEB-3531] Internal links rework image fix

.circleci/config.yml

@@ -146,6 +146,12 @@ jobs:
                 printf '.'
                 sleep 1
             done
+      - run:
+          name: Test nginx /docs rewriting
+          command: |
+            ./bin/assert-success.sh /docs
+            ./bin/assert-redirect.sh /docs/ https://localhost/docs
+            ./bin/assert-success.sh /docs/channels
       - run:
           name: Smoke test quickstart redirects
           command: |

README.md

@@ -87,6 +87,48 @@ Other one-off instances of redirects may be added to additional config files, an
 
 For how to create and include these redirects.
 
+## Images
+
+Wherever possible, images should live in `src/images` and _not_ in `static/images`. The authors of Gatsby recommend [importing images](https://www.gatsbyjs.com/docs/how-to/images-and-media/importing-assets-into-files/) into components. The `static` folder in Gatsby is an escape hatch for the rare cases where files cannot be imported.
+
+The benefit of sticking to the Gatsby approach is that our images get processed and optimized during build time. It also allows us to serve our images over a CDN which is much better for our users.
+
+### Images in components
+
+Images in components can be imported and rendered as follows:
+
+~~~typescript
+import myImage from 'src/path/to/my-image.png';
+
+export default Component => (<img src={myImage} />);
+~~~
+
+### Images in YAML data
+
+_TBD_
+
+### Images in textfile files
+
+For rendering images in Textfile we have a special convention.
+
+Firstly, place the image file in `src/images/content`. The in the textile files reference it with a special path `@content`, for example:
+
+~~~textile
+<img src="@content/path/to/image.png" />
+~~~
+
+The above will render the image at `src/images/content/path/to/image.png`.
+
+Content images in textile is powered by `ContentImagesProvider` and `useContentImages`. Templates rendering content need to add the following to their GraphQL queries to get all the images loaded before passing it to the `ContentImagesProvider`:
+
+~~~graphql
+  images: allFile(filter: { relativeDirectory: { glob: "content/**" } }) {
+    nodes {
+      ...ContentImage
+    }
+  }
+~~~
+
 ## Environment Variables
 
 Note that any env variables needed to show in the browser must be prefixed with `GATSBY_` in order to appear.

config/nginx.conf.erb

@@ -74,11 +74,12 @@ http {
 
     error_page 404 500 /404.html;
 
-    # Removes trailing slashes everywhere
+    # Removes trailing slashes everywhere (by redirecting)
     rewrite ^/(.*)/$ <%= ENV['SKIP_HTTPS'] == 'true' ? '$scheme' : 'https' %>://$host/$1 permanent;
 
-    # Strip /docs from the requests (we build with --prefix-paths)
-    rewrite ^/docs/(.*)$ /$1;
+    # Strip /docs from the requests (we build with --prefix-paths and our files are in public/)
+    rewrite ^/docs/(.*)$ /$1 last;
+    rewrite ^/docs$ / last;
 
     location ~* \.json$ {
       more_set_headers 'Access-Control-Allow-Origin: *';

content/account/control-api.textile

@@ -24,8 +24,8 @@ Repetitive operations such as creating, updating or deleting Ably apps, enumerat
 
 The following diagram illustrates an example use case:
 
-<a href="/images/screenshots/control-api/provision-and-test.png" target="_blank">
-  <img src="/images/screenshots/control-api/provision-and-test.png" style="width: 100%" alt="Provision and Test">
+<a href="@content/screenshots/control-api/provision-and-test.png" target="_blank">
+  <img src="@content/screenshots/control-api/provision-and-test.png" style="width: 100%" alt="Provision and Test">
 </a>
 
 In this use case, Control API is used to provision a sample app for review and testing purposes. Once provisioned, the "realtime":/api/realtime-sdk or "REST API":/api/rest-api can be used to test the app as needed. Once fully tested, the Control API can be used to replicate the app for users as required, using the known-good configuration.
@@ -48,14 +48,14 @@ Before you can use the Control API you must create an access token to authentica
 
 In the "Ably dashboard":https://ably.com/accounts/any, on the top menu bar, select your account from the dropdown list and then select "My Access Tokens" from the menu:
 
-<a href="/images/screenshots/control-api/my-access-tokens-menu-item.png" target="_blank">
-  <img src="/images/screenshots/control-api/my-access-tokens-menu-item.png" style="width: 40%" alt="My Settings">
+<a href="@content/screenshots/control-api/my-access-tokens-menu-item.png" target="_blank">
+  <img src="@content/screenshots/control-api/my-access-tokens-menu-item.png" style="width: 40%" alt="My Settings">
 </a>
 
 You are presented with the "My Access Tokens" area, where you can create tokens for use with the Control API:
 
-<a href="/images/screenshots/control-api/my-access-tokens.png" target="_blank">
-  <img src="/images/screenshots/control-api/my-access-tokens.png" style="width: 80%" alt="My Settings">
+<a href="@content/screenshots/control-api/my-access-tokens.png" target="_blank">
+  <img src="@content/screenshots/control-api/my-access-tokens.png" style="width: 80%" alt="My Settings">
 </a>
 
 h3(#creating-access-token). Creating an access token
@@ -66,8 +66,8 @@ To create a new token, click the "Create new access token" button. Then enter th
 2. Select the capabilities you wish the token to have, depending on your use case.
 3. Click the "Create" button to create the token.
 
-<a href="/images/screenshots/control-api/new-access-token.png" target="_blank">
-  <img src="/images/screenshots/control-api/new-access-token.png" style="width: 40%" alt="My Settings">
+<a href="@content/screenshots/control-api/new-access-token.png" target="_blank">
+  <img src="@content/screenshots/control-api/new-access-token.png" style="width: 40%" alt="My Settings">
 </a>
 
 h3(#using-access-token). Using the access token
@@ -128,14 +128,14 @@ h3(#account-id). How to find your account ID
 
 In the "Ably dashboard":https://ably.com/accounts/any, on the top menu bar, select your account from the dropdown list and then select "Account settings":
 
-<a href="/images/screenshots/control-api/account-settings-menu-item.png" target="_blank">
-  <img src="/images/screenshots/control-api/account-settings-menu-item.png" style="width: 40%" alt="Account Settings">
+<a href="@content/screenshots/control-api/account-settings-menu-item.png" target="_blank">
+  <img src="@content/screenshots/control-api/account-settings-menu-item.png" style="width: 40%" alt="Account Settings">
 </a>
 
 Your account settings are displayed. From here you can obtain your Ably account ID, as shown in the following screenshot:
 
-<a href="/images/screenshots/control-api/account-id.png" target="_blank">
-  <img src="/images/screenshots/control-api/account-id.png" style="width: 70%" alt="Account ID">
+<a href="@content/screenshots/control-api/account-id.png" target="_blank">
+  <img src="@content/screenshots/control-api/account-id.png" style="width: 70%" alt="Account ID">
 </a>
 
 You'll need your account ID for account-level Control API requests, such as listing all the apps in your Ably account.
@@ -144,8 +144,8 @@ h3(#app-id). How to find your app ID
 
 In the "Ably dashboard":https://ably.com/accounts/any select the app you want to find the app ID for. Click on the "Settings" tab:
 
-<a href="/images/screenshots/control-api/application-settings.png" target="_blank">
-  <img src="/images/screenshots/control-api/application-settings.png" style="width: 70%" alt="Application Settings">
+<a href="@content/screenshots/control-api/application-settings.png" target="_blank">
+  <img src="@content/screenshots/control-api/application-settings.png" style="width: 70%" alt="Application Settings">
 </a>
 
 The "App ID" is displayed under "Application settings". It is also the first part of your API key for that app. For example, if your API key is @28AB6c.DEFi0Q@, then the App ID is @28AB6c@. You can find out more in the Ably Help Center article "what is an app API key?":/auth#api-key.
@@ -681,26 +681,26 @@ A convenient way to try out the Control API is by importing the OpenAPI document
 
 2. Start Postman and select "File > Import" from the main menu. The import dialog is displayed:
 
-<a href="/images/screenshots/control-api/postman-import-dialog.png" target="_blank">
-  <img src="/images/screenshots/control-api/postman-import-dialog.png" style="width: 100%" alt="Postman import dialog">
+<a href="@content/screenshots/control-api/postman-import-dialog.png" target="_blank">
+  <img src="@content/screenshots/control-api/postman-import-dialog.png" style="width: 100%" alt="Postman import dialog">
 </a>
 
 3. Click the "Link" tab, and paste in the following URL: @https://raw.githubusercontent.com/ably/open-specs/main/definitions/control-v1.yaml@, then click "Continue":
 
-<a href="/images/screenshots/control-api/postman-link.png" target="_blank">
-  <img src="/images/screenshots/control-api/postman-link.png" style="width: 100%" alt="Link to OpenAPI document">
+<a href="@content/screenshots/control-api/postman-link.png" target="_blank">
+  <img src="@content/screenshots/control-api/postman-link.png" style="width: 100%" alt="Link to OpenAPI document">
 </a>
 
 4. In the Import dialog, use the default settings and click "Import":
 
-<a href="/images/screenshots/control-api/postman-import-default.png" target="_blank">
-  <img src="/images/screenshots/control-api/postman-import-default.png" style="width: 100%" alt="Postman import default">
+<a href="@content/screenshots/control-api/postman-import-default.png" target="_blank">
+  <img src="@content/screenshots/control-api/postman-import-default.png" style="width: 100%" alt="Postman import default">
 </a>
 
 5. The imported document now appears in your Postman collections:
 
-<a href="/images/screenshots/control-api/imported-collection.png" target="_blank">
-  <img src="/images/screenshots/control-api/imported-collection.png" style="width: 80%" alt="Postman imported collection">
+<a href="@content/screenshots/control-api/imported-collection.png" target="_blank">
+  <img src="@content/screenshots/control-api/imported-collection.png" style="width: 80%" alt="Postman imported collection">
 </a>
 
 You have now imported the OpenAPI document into Postman.
@@ -715,30 +715,30 @@ Now that you have obtained the token and IDs, you can learn how to send a reques
 
 1. Expand the collection to the @Lists account apps@ request. The following screenshot shows the parameters for the request:
 
-<a href="/images/screenshots/control-api/app-list-request.png" target="_blank">
-  <img src="/images/screenshots/control-api/app-list-request.png" style="width: 100%" alt="App list request">
+<a href="@content/screenshots/control-api/app-list-request.png" target="_blank">
+  <img src="@content/screenshots/control-api/app-list-request.png" style="width: 100%" alt="App list request">
 </a>
 
 2. The @Lists account apps@ request is an account-level operation and therefore requires your account ID in the @account_id@ path variable. This path variable is highlighted with the green box in the previous screenshot. Paste your Ably account ID into the "VALUE" field.
 
 3. You also need to enter your Control API token as a @Bearer Token@ in the "Authorization" tab. Paste your Ably Control API token into the token field marked with the placeholder text @<Bearer Token>@, as shown in the following screenshot:
 
-<a href="/images/screenshots/control-api/bearer-token.png" target="_blank">
-  <img src="/images/screenshots/control-api/bearer-token.png" style="width: 100%" alt="Bearer token">
+<a href="@content/screenshots/control-api/bearer-token.png" target="_blank">
+  <img src="@content/screenshots/control-api/bearer-token.png" style="width: 100%" alt="Bearer token">
 </a>
 
 *Note:* If you don't supply this token, your request will fail to authenticate.
 
 4. Now that this request is configured, you can send the request by clicking the "Send" button:
 
-<a href="/images/screenshots/control-api/send-request.png" target="_blank">
-  <img src="/images/screenshots/control-api/send-request.png" style="width: 100%" alt="Send request">
+<a href="@content/screenshots/control-api/send-request.png" target="_blank">
+  <img src="@content/screenshots/control-api/send-request.png" style="width: 100%" alt="Send request">
 </a>
 
 5. The server returns a response, listing your Ably apps:
 
-<a href="/images/screenshots/control-api/list-apps-response.png" target="_blank">
-  <img src="/images/screenshots/control-api/list-apps-response.png" style="width: 70%" alt="Response">
+<a href="@content/screenshots/control-api/list-apps-response.png" target="_blank">
+  <img src="@content/screenshots/control-api/list-apps-response.png" style="width: 70%" alt="Response">
 </a>
 
 You can now try out other requests. You need to set the necessary parameters and authentication token as required by that specific request. Consult the "API Reference":/api/control-api for further information.