Merge branch 'main' into 4686-add-section-about-emissions-dashboard-to-regions-pages

Author: Kemi-Elizabeth

.github/actions/redirection-verification/package-lock.json

@@ -12,7 +12,7 @@
   "dependencies": {
     "@actions/core": "^1.11.1",
     "@actions/github": "^6.0.0",
-    "axios": "^1.7.7",
+    "axios": "^1.8.2",
     "js-yaml": "^4.1.0"
   }
 }

.github/actions/redirection-verification/package.json

@@ -0,0 +1,62 @@
+name: Check API Docs Update
+
+on:
+  schedule:
+    - cron: '* 3 * * *'
+  workflow_dispatch:
+    #branches: [ * ]
+permissions:
+  contents: write
+env:
+  DEFAULT_BRANCH: "main"
+jobs:
+  check-and-update:
+    runs-on: ubuntu-latest
+    if: ${{ github.repository_owner == 'platformsh' }}
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Git
+        run: |
+          git config --global user.name "github-actions[bot]"
+          git config --global user.email "github-actions[bot]@users.noreply.github.com"
+
+      - name: Download redoc_static.html from GitLab
+        env:
+          GITLAB_TOKEN: ${{ secrets.GITLAB_TOKEN }}
+        run: |
+          PROJECT_PATH="devrel/docs/api-site"
+          REF="main"
+
+          # URL-encode path to the project (replace `/` by `%2F`)
+          # @todo switch this to using the python method so we're consistent?
+          PROJECT_ENCODED=$(echo "$PROJECT_PATH" | sed 's/\//%2F/g')
+
+          # Download into shared data using the GitLab API
+          # @todo should we also copy over the stylesheet? or should the version in docs be canonical?
+          curl --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
+            --output shared/pages/api.html \
+            "https://lab.plat.farm/api/v4/projects/${PROJECT_ENCODED}/repository/files/$(python3 -c "import urllib.parse; print(urllib.parse.quote('web/redoc-static.html',safe=''))")/raw?ref=${REF}"
+
+      - name: Create Pull Request if changes
+        uses: peter-evans/create-pull-request@v6
+        with:
+          token: ${{ secrets.WORKFLOW_TOKEN }}
+          commit-message: "Update API Docs"
+          body: "This PR updates the API Docs."
+
+          author: ${{ github.actor }} <${{ github.actor_id }}+${{ github.actor }}@users.noreply.github.com>
+          signoff: false
+          draft: false
+          delete-branch: true
+          branch: update-api-doc
+          title: "[API-BOT] Update API Docs"
+
+          base: main
+          labels: |
+            report
+            automated pr
+          add-paths: |
+            shared/pages

.github/workflows/check-openapi-spec-update.yaml

@@ -24,12 +24,24 @@
         # Build hooks can modify the application files on disk but not access any services like databases.
         build: |
           set -e
+          #copy API docs into correct location
+          # @todo once api docs are fully moved we can alter the template.hbs file so style.css can be in /api
+          mkdir -p "${PLATFORM_APP_DIR}/${SITE_DIR}/public/api/styles"
+          if [ -f "${PLATFORM_APP_DIR}/shared/pages/api.html" ]; then
+            cp "${PLATFORM_APP_DIR}/shared/pages/api.html" "${PLATFORM_APP_DIR}/${SITE_DIR}/public/api/index.html"
+            cp "${PLATFORM_APP_DIR}/shared/pages/api-style.css" "${PLATFORM_APP_DIR}/${SITE_DIR}/public/api/styles/style.css"
+          else
+            echo "<p>Currently under maintenance. Please check back later.</p>" >> "${PLATFORM_APP_DIR}/${SITE_DIR}/public/api/index.html"
+          fi
+
           cd $SITE_DIR
           cp ../../themes/psh-docs/postcss.config.js .
           npm install
           npm run build
           ./build_docs.sh
 
+
+
         deploy: |
             cd $SITE_DIR
             ./deploy.sh
@@ -60,6 +72,10 @@
                     \.txt$:
                       headers:
                         Content-Type: "text/plain; charset=UTF-8"
+            '/api':
+              root: 'sites/platform/public/api'
+              index: [ 'index.html' ]
+              expires: 24h
     disk: 1024
 
     mounts:
@@ -94,6 +110,15 @@
     hooks:
         # Build hooks can modify the application files on disk but not access any services like databases.
         build: |
+          #copy API docs into correct location
+          # @todo once api docs are fully moved we can alter the template.hbs file so style.css can be in /api
+          mkdir -p "${PLATFORM_APP_DIR}/${SITE_DIR}/public/api/styles"
+          if [ -f "${PLATFORM_APP_DIR}/shared/pages/api.html" ]; then
+            cp "${PLATFORM_APP_DIR}/shared/pages/api.html" "${PLATFORM_APP_DIR}/${SITE_DIR}/public/api/index.html"
+            cp "${PLATFORM_APP_DIR}/shared/pages/api-style.css" "${PLATFORM_APP_DIR}/${SITE_DIR}/public/api/styles/style.css"
+          else
+            echo "<p>Currently under maintenance. Please check back later.</p>" >> "${PLATFORM_APP_DIR}/${SITE_DIR}/public/api/index.html"
+          fi
           cd $SITE_DIR
           cp ../../themes/psh-docs/postcss.config.js .
           npm install
@@ -135,7 +160,10 @@
                     '^/favicon.ico$':
                         allow: true
                         passthru: '/images/favicon.ico'
-
+            '/api':
+              root: 'sites/upsun/public/api'
+              index: [ 'index.html' ]
+              expires: 24h
 
     disk: 1024
 

.platform/applications.yaml

@@ -17,6 +17,7 @@ This content style guide should help make sure the Platform.sh docs are clear an
   - [Use inclusive language](#use-inclusive-language)
     - [Resources for inclusive language](#resources-for-inclusive-language)
     - [Use meaningful link text](#use-meaningful-link-text)
+    - [Use imperative verbs](#use-verbs-imperatives-for-headings-and-section-titles)
     - [Link at the end of sentences in sentence case](#link-at-the-end-of-sentences-in-sentence-case)
     - [Minimize distractions](#minimize-distractions)
     - [Include alt text](#include-alt-text)
@@ -32,6 +33,7 @@ This content style guide should help make sure the Platform.sh docs are clear an
     - [Make commands work across shells](#make-commands-work-across-shells)
   - [Use notes appropriately](#use-notes-appropriately)
   - [Add short descriptions](#add-short-descriptions)
+  - [Use shortcodes for latest versions and dates](#use-shortcodes-for-versions-and-dates)
   - [Guidance enforcement](#guidance-enforcement)
 <!-- vale Platform.condescending = YES -->
 
@@ -156,6 +158,26 @@ Use                                                                     | Avoid
 To learn how to set it up, read about [services](https://example.com).  | Reading about [Services](https://example.com) shows you how to set it up.
 For more information, see how to [configure apps](https://example.com). | For more information, see [Configure apps](https://example.com).
 
+### Use verbs (imperatives) for headings and section titles
+
+To maintain a clear and authoritative tone, use imperative verbs (the base form of the verb) rather than gerunds (*-ing*) in headings and section titles.
+
+This approach helps guide the reader with direct instructions, making it immediately clear what action they should take.
+
+Do this:
+* Set up your environment  
+* Deploy your project  
+* Configure environment variables  
+* Troubleshoot common errors
+
+Not this:
+* Setting up your environment  
+* Deploying your project  
+* Configuring environment variables  
+* Troubleshooting common errors
+
+Using verbs keeps the content focused, concise, and easier to scan, while reinforcing the instructional nature of our documentation.
+
 ### Minimize distractions
 
 Adding links can often provide helpful context.
@@ -379,6 +401,31 @@ something that makes sense out of the context of the rest of the page.
 Remember to keep it short.
 If possible, it should be no more than about 160 characters.
 
+## Use shortcodes for versions and dates
+
+When referencing service or runtime versions in documentation, always use the shortcode `{{% latest "xxx" %}}` instead of hardcoding version numbers. Replace `xxx` with the name of the service or runtime exactly as it appears in the `.json` or `.yaml` file you’re referring to.
+
+For example, if you’re editing a code snippet like this:
+
+```yaml {configFile="services"}
+mariadb:
+  type: mariadb:11.4
+  disk: 2048
+```
+You should replace the hardcoded version with the shortcode:
+
+```yaml {configFile="services"}
+mariadb:
+  type: mariadb:{{% latest "mariadb" %}}
+  disk: 2048
+```
+
+In this case, `{{% latest "mariadb" %}}` automatically pulls in the most recent version of MariaDB (e.g. `11.4`) and will update automatically as new versions become available. The value inside the shortcode that follows `latest` (in this case, it is `"mariadb"`) must match how the service name is presented in the `.yaml` file. For instance, `{{% latest "mariadb" %}}` is correct, but `{{% latest "Maria DB" %}}` is wrong.
+
+Similarly, use `{{ now.Year }}` instead of hardcoding a specific year. This ensures the current year is always displayed and helps keep time references up to date.
+
+Using these shortcodes improves accuracy and reduces the need for manual updates across the documentation.
+
 ## Guidance enforcement
 
 Some of the rules are enforced with [Vale](https://docs.errata.ai/vale/about), a linter for prose.

contributing/content-style.md

@@ -29,3 +29,4 @@ ignoreerrors=
     ^https://mkyong.com/java/java-how-to-send-email/$ ^403 Forbidden
     ^https://www.baeldung.com/maven-wrapper$ ^403 Forbidden
     ^https://dzone\.com/.*$ ^403 Forbidden
+    ^https://docs\.pimcore\.com/.*$ ^403 Forbidden

linkcheckerrc

@@ -395,41 +395,6 @@
       ]
     }
   },
-  "lisp": {
-    "description": "",
-    "id": 1102,
-    "repo_name": "lisp",
-    "disk": false,
-    "docs": {
-      "relationship_name": null,
-      "service_name": null,
-      "url": "/languages/lisp.html",
-      "web": {
-        "commands": {
-          "start": "./example"
-        },
-        "locations": {
-          "/": {
-            "allow": false,
-            "passthru": true
-          }
-        }
-      }
-    },
-    "endpoint": null,
-    "min_disk_size": null,
-    "name": "Lisp",
-    "runtime": true,
-    "type": "lisp",
-    "versions": {
-      "deprecated": [],
-      "supported": [
-        "2.1",
-        "2.0",
-        "1.5"
-      ]
-    }
-  },
   "mariadb": {
     "description": "A manufacture-based container for MariaDB",
     "repo_name": "mariadb",