From cd2b2f6f122cefd5c28492ff834baaa2d6e7b671 Mon Sep 17 00:00:00 2001 From: Lucy Macartney Date: Fri, 25 Sep 2026 16:01:55 +0100 Subject: [PATCH 1/2] Link docs pages by file path from the docs root (#867) Relative links like ../deploy/portability.md only resolve next to the page they are on, so they break the build as soon as one end is translated and the other is not. Paths from the docs root resolve in the translated folder first and fall back to the English one. --- .../build-for-developers/security-for-devs.md | 4 +-- docs/build/channels.md | 10 +++---- docs/build/steps/steps.md | 2 +- docs/build/triggers.md | 4 +-- docs/build/troubleshooting.md | 2 +- docs/build/workflow-snapshots.md | 4 +-- docs/build/workflows.md | 6 ++-- docs/build/working-with-branches.md | 4 +-- docs/contribute/roadmap.md | 2 +- docs/deploy/options.md | 2 +- docs/deploy/portability-v3.md | 2 +- docs/get-started/security-compliance.md | 22 +++++++------- docs/get-started/try-out.md | 2 +- docs/jobs/javascript.md | 2 +- docs/jobs/operations.md | 2 +- docs/jobs/state.md | 2 +- docs/manage-projects/collaboration.md | 4 +-- docs/manage-projects/io-data-storage.md | 2 +- docs/manage-projects/manage-credentials.md | 2 +- docs/manage-projects/oauth.md | 10 +++---- docs/manage-projects/staging-prod.md | 8 ++--- docs/manage-projects/webhook-auth.md | 2 +- docs/manage-users/api-tokens.md | 2 +- docs/manage-users/user-credentials.md | 2 +- docs/migration/converting-triggers.md | 10 +++---- docs/migration/migration-steps.md | 30 +++++++++---------- docs/monitor-history/activity-history.md | 2 +- docs/monitor-history/inspect-runs.md | 4 +-- docs/monitor-history/rerunning-workflow.md | 2 +- docs/monitor-history/status-codes.md | 2 +- docs/monitor-history/troubleshooting.md | 8 ++--- docs/tutorials/commcare-to-db.md | 6 ++-- docs/tutorials/http-to-googlesheets.md | 18 +++++------ docs/tutorials/kobo-to-dhis2.md | 24 +++++++-------- docs/tutorials/tutorial.md | 12 ++++---- 35 files changed, 111 insertions(+), 111 deletions(-) diff --git a/docs/build-for-developers/security-for-devs.md b/docs/build-for-developers/security-for-devs.md index 3cad88b21310..d278140e1931 100644 --- a/docs/build-for-developers/security-for-devs.md +++ b/docs/build-for-developers/security-for-devs.md @@ -178,6 +178,6 @@ adjusted by the OpenFn super admin. For more security considerations and best practices for all OpenFn implementers (not just developers), be sure to check out the complete -[OpenFn Security Guidebook](../get-started/security.md). For more on job-writing, -see the [job-writing guide](../jobs/job-writing-guide.md). +[OpenFn Security Guidebook](/get-started/security.md). For more on job-writing, +see the [job-writing guide](/jobs/job-writing-guide.md). ::: diff --git a/docs/build/channels.md b/docs/build/channels.md index aca39608ac50..fda27634e6bd 100644 --- a/docs/build/channels.md +++ b/docs/build/channels.md @@ -27,7 +27,7 @@ OpenFn. Channels are currently an experimental feature. To use them, enable **Experimental Features** on your -[user profile](../manage-users/user-profile.md) page. If you don't see a +[user profile](/manage-users/user-profile.md) page. If you don't see a `Channels` item in your project sidebar, this flag is the reason. ::: @@ -62,7 +62,7 @@ You need: - The **Experimental Features** flag enabled on your user profile - A **project** where you have the `Owner`, `Admin`, or `Editor` - [role](../manage-projects/user-roles-permissions.md) (Viewers can see channels + [role](/manage-projects/user-roles-permissions.md) (Viewers can see channels and their logs, but cannot create or change them) - The **URL of the destination service** you want to proxy to (a public API like `https://hacker-news.firebaseio.com/v0` works great for testing) @@ -72,12 +72,12 @@ You need: Channels use two kinds of credentials, and both are optional: - **Client credentials** control who can send requests _to your channel_. They - are the same [webhook auth methods](../manage-projects/webhook-auth.md) used + are the same [webhook auth methods](/manage-projects/webhook-auth.md) used to secure webhook triggers (Basic HTTP Authentication or API Key Authentication) and are managed under `Webhook Security` in your project settings. - A **destination credential** is how OpenFn authenticates _to the destination - service_. It is a regular [project credential](./credentials.md), and OpenFn + service_. It is a regular [project credential](/build/credentials.md), and OpenFn uses it to build the `Authorization` header on every forwarded request. Channels currently support these credential types: @@ -199,7 +199,7 @@ its **Requests** count or **Last Activity** on the Channels page. :::info Whether request and response payloads are stored follows your project's -[Data Storage](../manage-projects/io-data-storage.md) settings. If your project +[Data Storage](/manage-projects/io-data-storage.md) settings. If your project doesn't store I/O data, channel request metadata is still logged, but the payloads are wiped. diff --git a/docs/build/steps/steps.md b/docs/build/steps/steps.md index 07d30fabaaba..66fc4b397fe1 100644 --- a/docs/build/steps/steps.md +++ b/docs/build/steps/steps.md @@ -141,5 +141,5 @@ want this and to avoid the risk of accidental upgrades on live Workflows. Click the code button `` displayed on the configuration panel to write or edit a Job expression to define the "rules" or the specific tasks to be -completed by your Step. See the pages on [the Inspector](./step-editor.md) and +completed by your Step. See the pages on [the Inspector](/build/steps/step-editor.md) and [writing Jobs](/documentation/jobs/job-writing-guide) to learn more. diff --git a/docs/build/triggers.md b/docs/build/triggers.md index 8c2f4c0da04f..fa222ad17c0a 100644 --- a/docs/build/triggers.md +++ b/docs/build/triggers.md @@ -20,10 +20,10 @@ another OpenFn workflow, or manually (i.e., via cURL request). To learn about how to add an additional layer of security to your Webhook Trigger by adding authentication, head over to our -[Webhook Security](../manage-projects/webhook-auth.md) page. +[Webhook Security](/manage-projects/webhook-auth.md) page. Learn how a workflow's initial `state` gets built from a webhook trigger -[here](../jobs/state#webhook-triggered-runs). +[here](/jobs/state.md#webhook-triggered-runs). ## **Webhook Trigger Responses** diff --git a/docs/build/troubleshooting.md b/docs/build/troubleshooting.md index a037e57e09c7..48ad2fe27191 100644 --- a/docs/build/troubleshooting.md +++ b/docs/build/troubleshooting.md @@ -8,7 +8,7 @@ and complications, that might help you get to the bottom of it. :::tip -Check out the [Troubleshooting page](../monitor-history/troubleshooting.md) in +Check out the [Troubleshooting page](/monitor-history/troubleshooting.md) in the "Monitor History" section for more specific tips and common errors. ::: diff --git a/docs/build/workflow-snapshots.md b/docs/build/workflow-snapshots.md index 81e8923869a2..d19d681b0ab6 100644 --- a/docs/build/workflow-snapshots.md +++ b/docs/build/workflow-snapshots.md @@ -26,7 +26,7 @@ Click on the inspect icon in front of the step you would like to view. ![Inspect](/img/inspect.webp) -This will open the [inspector screen](../build/steps/step-editor.md) for that step in the run with all associated artifacts: logs and input/output data. On the inspector, you'll notice that you're in a read-only mode, and hovering on the workflow snapshot ID chip, you’ll see a message that reads “You are viewing a snapshot of this workflow that was taken on ….” +This will open the [inspector screen](/build/steps/step-editor.md) for that step in the run with all associated artifacts: logs and input/output data. On the inspector, you'll notice that you're in a read-only mode, and hovering on the workflow snapshot ID chip, you’ll see a message that reads “You are viewing a snapshot of this workflow that was taken on ….” ![Snapshot2](/img/snapshots2.webp) @@ -60,4 +60,4 @@ When retrying a run with a snapshot, the retry will be executed with the latest As they save a workflow as a particular set of configuration, input data and job code, snapshots are mainly tools to help administrators with auditing and dealing with errors (such as, for example, why a case hasn't been updated correctly in a database). -OpenFn offers dedicated tools for [version control](../manage-projects/link-to-gh.md) that allows you and your team to manage changes in job code for faster and safer development, debugging and revision. \ No newline at end of file +OpenFn offers dedicated tools for [version control](/manage-projects/link-to-gh.md) that allows you and your team to manage changes in job code for faster and safer development, debugging and revision. \ No newline at end of file diff --git a/docs/build/workflows.md b/docs/build/workflows.md index f22bd14d61dd..c2147cb3c84b 100644 --- a/docs/build/workflows.md +++ b/docs/build/workflows.md @@ -15,9 +15,9 @@ To create a new Workflow in your Project: 2. Click the **Create new workflow** button. 3. Give your Workflow a descriptive `Name` (e.g., `Register patients`, `Refer cases`, `Monthly payroll`). -4. Choose your [Trigger](../build/triggers.md) -5. Edit your first [Step](../build/steps/steps.md) -6. Modify the [Path Condition](../build/paths.md), if needed, to define _when_ +4. Choose your [Trigger](/build/triggers.md) +5. Edit your first [Step](/build/steps/steps.md) +6. Modify the [Path Condition](/build/paths.md), if needed, to define _when_ the Workflow should proceed to the next Step. 7. Configure more Steps as needed diff --git a/docs/build/working-with-branches.md b/docs/build/working-with-branches.md index b11814e219f3..f537e0c598a5 100644 --- a/docs/build/working-with-branches.md +++ b/docs/build/working-with-branches.md @@ -3,7 +3,7 @@ title: Manage changes with GitHub branches sidebar_label: Manage changes --- -In the [Edit Steps Locally](../build/editing-locally.md) section, we walked through +In the [Edit Steps Locally](/build/editing-locally.md) section, we walked through the process of creating and adding your changes to the `main` branch of a project. @@ -30,7 +30,7 @@ repo to your local folder. branch, managed separately from `main`. 2. To test the changes locally, check out the - [The CLI](../build-for-developers/cli-intro.md) docs. + [The CLI](/build-for-developers/cli-intro.md) docs. 3. Just as you've seen when working on `main`, when you're done check which files you changed with `git status`. diff --git a/docs/contribute/roadmap.md b/docs/contribute/roadmap.md index 386a8d8f5603..8f7b0425da8b 100644 --- a/docs/contribute/roadmap.md +++ b/docs/contribute/roadmap.md @@ -183,4 +183,4 @@ We encourage users to post their questions on the OpenFn Community at [community.openfn.org](https://community.openfn.org), or consider creating issues for bugs via product repository. You can also independently start contributing to the OpenFn software, adaptors, or documentation by getting -started [here](./writing-code.md). +started [here](/contribute/writing-code.md). diff --git a/docs/deploy/options.md b/docs/deploy/options.md index 426fe8d172b0..c5a6c435fa99 100644 --- a/docs/deploy/options.md +++ b/docs/deploy/options.md @@ -74,7 +74,7 @@ local/government-managed servers, you might: 8. **Monitor & adjust your strategy** as and when required by your country’s usage and data sovereignty requirements evolve over time. -\*Head over to the [Requirements](./requirements.md) page for more information +\*Head over to the [Requirements](/deploy/requirements.md) page for more information on recommended server specifications. ## Moving from cloud to local (v1 or v2) diff --git a/docs/deploy/portability-v3.md b/docs/deploy/portability-v3.md index 18a400bdcd58..d38af16e077e 100644 --- a/docs/deploy/portability-v3.md +++ b/docs/deploy/portability-v3.md @@ -282,7 +282,7 @@ OpenFn [CLI](https://github.com/OpenFn/kit/tree/main/packages/cli) comes with commands that can be used to pull project configurations down from a running Lightning server, and to deploy or push updates to existing projects on a Lightning server. To learn more about automated version control via pull and -deploy, head over to our [Version Control](../manage-projects/link-to-gh.md) +deploy, head over to our [Version Control](/manage-projects/link-to-gh.md) docs. :::info Don't have the CLI yet? diff --git a/docs/get-started/security-compliance.md b/docs/get-started/security-compliance.md index 4a3e4205c636..321aae7e59bc 100644 --- a/docs/get-started/security-compliance.md +++ b/docs/get-started/security-compliance.md @@ -17,7 +17,7 @@ NGOs worldwide. ✓ Build “zero-persistence” data pipelines to fully control where data is stored ✓ Security implementation training & guidance for your project teams -([read more](../get-started/security.md)) +([read more](/get-started/security.md)) See our main website to learn more about OpenFn [Security & Trust](https://www.openfn.org/trust) and @@ -41,11 +41,11 @@ In your digital ecosystem, typically **OpenFn serves as a data processing and transfer solution—not as a data storage service.** As an open source Digital Public Good, OpenFn can be deployed anywhere -([see docs](../deploy/options.md)) and workflows can be configured to adhere to +([see docs](/deploy/options.md)) and workflows can be configured to adhere to your organization's specific data sharing agreements and security policies. Consult the `Manage Projects` docs pages for more on project and -[data storage settings](../manage-projects/io-data-storage.md). +[data storage settings](/manage-projects/io-data-storage.md). See the below diagram for an example architecture where even the OpenFn Cloud can be configured as a **“zero-persistence” data pipeline** to ensure compliance @@ -56,8 +56,8 @@ before migrating to a local deployment when they’re ready to scale. ![Sample Architecture](/img/zero-persistence.webp) To delete your project data at any time, you can -[delete your project](../manage-projects/platform-mgmt.md) or -[delete your account](../manage-users/user-profile.md). +[delete your project](/manage-projects/platform-mgmt.md) or +[delete your account](/manage-users/user-profile.md). ## Encryption @@ -75,7 +75,7 @@ Learn more at [openfn.org/trust](https://www.openfn.org/trust#encryption). ## Credentials -[Credentials](../manage-projects/manage-credentials.md), used to grant OpenFn +[Credentials](/manage-projects/manage-credentials.md), used to grant OpenFn API access to your various technologies, are encrypted at rest so that, in the unlikely event of a database breach, without access to multiple, independently secured boxes an attacker would be unable to read your authentication @@ -91,7 +91,7 @@ at [github.com/OpenFn/adaptors](https://github.com/OpenFn/adaptors). Credentials can only be viewed by you (the creator), and are loaded into your private runtime for job execution. You can delete these credentials at any time and they will be purged from the system. -[See docs](../manage-users/user-credentials.md) for more on OpenFn credentials +[See docs](/manage-users/user-credentials.md) for more on OpenFn credentials management and sharing. ## User Access Management and RBAC @@ -105,19 +105,19 @@ scoped API tokens to ensure security and compliance. When new users are invited to work on your Project as Collaborators, they are assigned a role that determines their permissions. See docs on -[Collaboration](../manage-projects/collaboration.md) and -[User Roles](../manage-projects/user-roles-permissions.md) for more information. +[Collaboration](/manage-projects/collaboration.md) and +[User Roles](/manage-projects/user-roles-permissions.md) for more information. When users register for the platform, they will be prompted to create a secure password. OpenFn super administrators can also enable -[Multi-Factor Authentication](../manage-users/user-profile.md), password expiry, +[Multi-Factor Authentication](/manage-users/user-profile.md), password expiry, and stale account lockout. :::info More OpenFn Security Questions? First, be sure to consult the [Trust](https://www.openfn.org/trust) and [Compliance](https://www.openfn.org/compliance) pages on our website, as well as -[Security Implementation Guidebook](../get-started/security.md). +[Security Implementation Guidebook](/get-started/security.md). Ask questions on [Community](https://community.openfn.org/) or [contact our core team](mailto:security@openfn.org) for private queries. diff --git a/docs/get-started/try-out.md b/docs/get-started/try-out.md index db9d1ffb1c65..db46fdc09815 100644 --- a/docs/get-started/try-out.md +++ b/docs/get-started/try-out.md @@ -50,7 +50,7 @@ without limits. See our GitHub repo for developer docs: :::info Questions? Check out these docs for more details on specific features (see menu sidebar), -browse the [main docs page](./home.md), or post your questions on +browse the [main docs page](/get-started/home.md), or post your questions on [Community](https://community.openfn.org). ::: diff --git a/docs/jobs/javascript.md b/docs/jobs/javascript.md index 136170e438a2..9f3b8fe4c231 100644 --- a/docs/jobs/javascript.md +++ b/docs/jobs/javascript.md @@ -288,7 +288,7 @@ For scenarios where you have a global list of variables or mapping rules that you would like to reference throughout your workflows, you can add these to your job as a constant that can be referenced repeatedly throughout the job expression. See the documentation on -[mapping specifications](../design/mapping-specs.md) for more information on +[mapping specifications](/design/mapping-specs.md) for more information on globals. ```js diff --git a/docs/jobs/operations.md b/docs/jobs/operations.md index d20cc5643bb2..ef6404c96c32 100644 --- a/docs/jobs/operations.md +++ b/docs/jobs/operations.md @@ -127,7 +127,7 @@ post('/some-other-data', state => state.data); When `post` executes, it resolves any function arguments by calling them with the current state. This lazy evaluation pattern is fundamental to writing correct OpenFn jobs. See also the -[Lazy State operator](./lazy-state-operator.md) for a shorthand syntax. +[Lazy State operator](/jobs/lazy-state-operator.md) for a shorthand syntax. ## Callbacks and fn() diff --git a/docs/jobs/state.md b/docs/jobs/state.md index 74a29905209a..28782a842a90 100644 --- a/docs/jobs/state.md +++ b/docs/jobs/state.md @@ -51,7 +51,7 @@ the input state for a Run must be generated differently: - When manually creating a work order, you must select or generate your input manually (e.g., by creating a custom `Input` on the app or `state.json` file - if working locally [in the CLI](../build-for-developers/cli-intro.md)). + if working locally [in the CLI](/build-for-developers/cli-intro.md)). - When a work order is automatically created via a webhook trigger or cron trigger, state will be created as described below. diff --git a/docs/manage-projects/collaboration.md b/docs/manage-projects/collaboration.md index 524a3ef31aa1..997bc2c86284 100644 --- a/docs/manage-projects/collaboration.md +++ b/docs/manage-projects/collaboration.md @@ -26,7 +26,7 @@ below: | Viewer | A user with access to a project but only limited to viewing the project settings and artifacts. | You can learn more about the permissions of each role -[here](../manage-projects/user-roles-permissions.md) +[here](/manage-projects/user-roles-permissions.md) ### Add project collaborator(s) @@ -71,4 +71,4 @@ through the pop up window. The owner of a project cannot be removed. :::tip The project collaborators page is also where you can configure failure alerts and digests for your projects. Learn more about it -[in this guide](../manage-projects/notifications.md). ::: +[in this guide](/manage-projects/notifications.md). ::: diff --git a/docs/manage-projects/io-data-storage.md b/docs/manage-projects/io-data-storage.md index c415a1c7a561..4eceeeeda48a 100644 --- a/docs/manage-projects/io-data-storage.md +++ b/docs/manage-projects/io-data-storage.md @@ -37,7 +37,7 @@ sovereignty. :::tip Check out the docs page on -[Security & Compliance](../get-started/security-compliance.md) for more on data +[Security & Compliance](/get-started/security-compliance.md) for more on data storage and solution architectures that rely on OpenFn "zero-persistence" data pipelines. diff --git a/docs/manage-projects/manage-credentials.md b/docs/manage-projects/manage-credentials.md index c8dba4213376..754e41fb2f96 100644 --- a/docs/manage-projects/manage-credentials.md +++ b/docs/manage-projects/manage-credentials.md @@ -181,4 +181,4 @@ Example Raw JSON credential body or `configuration`: All credentials are stored encrypted at rest, and credential secrets can only be viewed by credential owners. See OpenFn -[Security docs](../get-started/security-compliance.md) for more information. +[Security docs](/get-started/security-compliance.md) for more information. diff --git a/docs/manage-projects/oauth.md b/docs/manage-projects/oauth.md index db6fdb725e45..ba36a53cfc7e 100644 --- a/docs/manage-projects/oauth.md +++ b/docs/manage-projects/oauth.md @@ -33,8 +33,8 @@ For every application you need to connect to OpenFn, you need to set up at least one client for your project(s). Oauth clients can be set up either on the -[project credentials page](../manage-projects/manage-credentials.md) or the -[user credentials page](../manage-users/user-credentials.md). +[project credentials page](/manage-projects/manage-credentials.md) or the +[user credentials page](/manage-users/user-credentials.md). ### Creating an OAuth client @@ -57,8 +57,8 @@ application. (Note: You should substitue `https://app.openfn.org/` with _your_ OpenFn's deployment base URL if you're not using app.openfn.org.) For app-specific guidance (e.g., how to set up an Oauth Client -[for Google Sheets](../adaptors/googlesheets)), refer to the relevant -[Adaptor documentation](../adaptors) for app-specific guidance +[for Google Sheets](/adaptors/googlesheets)), refer to the relevant +[Adaptor documentation](/adaptors) for app-specific guidance ::: @@ -150,7 +150,7 @@ be permanently deleted after 7 days. ### More on Managing Credentials Go to the docs on -[managing user credentials](../manage-users/user-credentials.md) to learn more +[managing user credentials](/manage-users/user-credentials.md) to learn more about credential management for the applications you are integrating with on OpenFn. diff --git a/docs/manage-projects/staging-prod.md b/docs/manage-projects/staging-prod.md index af1a4caf2f18..63884b31b546 100644 --- a/docs/manage-projects/staging-prod.md +++ b/docs/manage-projects/staging-prod.md @@ -4,7 +4,7 @@ sidebar_label: Staging and Production Projects slug: /staging-prod --- -It's a safe and efficient practice to use separate production and staging/testing projects to build out and test your workflows before starting to use them in production. This can be made seamless using [Version Control](../manage-projects/link-to-gh.md). This guide walks you through how to set up your OpenFn projects and GitHub repo and gives you two examples of how to manage your `Staging > Production` workflow: one for new projects, and one for existing projects where you want to add a staging project and branch. +It's a safe and efficient practice to use separate production and staging/testing projects to build out and test your workflows before starting to use them in production. This can be made seamless using [Version Control](/manage-projects/link-to-gh.md). This guide walks you through how to set up your OpenFn projects and GitHub repo and gives you two examples of how to manage your `Staging > Production` workflow: one for new projects, and one for existing projects where you want to add a staging project and branch. ### Setup for new projects @@ -16,7 +16,7 @@ It's a safe and efficient practice to use separate production and staging/testin ![Prod and Main Branches](/img/staging_prod_branches_gh.webp) -3. Connect your projects to the `main` and `staging` respectively - use [this guide](../manage-projects/link-to-gh.md) to set up the connection +3. Connect your projects to the `main` and `staging` respectively - use [this guide](/manage-projects/link-to-gh.md) to set up the connection 4. In each repo, create an empty `.js` file for your job. Make sure they have the same name and path on each repo (e.g. `upsert-contacts.js`). These will store the code for the job they'll be linked to in the next step. 5. When you connected the branches to your projects in step 3 above, there was a `spec.yaml` file automatically created on the branch after the first sync (along with two other configuration files). Open these files on GitHub, and locate your job in the file. Replace the contents of `body` with: `path: {path to the related js file}`. Do this on both your `main` and `staging` branches. @@ -57,7 +57,7 @@ Notify-CHW-upload-successful: ``` -You can find more information on this setup in our [Github docs](../manage-projects/link-to-gh.md#sync-from-github-to-openfn). +You can find more information on this setup in our [Github docs](/manage-projects/link-to-gh.md#sync-from-github-to-openfn). 2. When this is set up, create a new `staging` branch on Github based on your existing production `main` branch that stores your current project. To do this, on your Github repo click into `Branches` (where it show `1 Branch` in the screenshot below). @@ -71,7 +71,7 @@ You can find more information on this setup in our [Github docs](../manage-proje 5. Now head over to OpenFn, and create a new `Staging` project. -6. Following [this guide](../manage-projects/link-to-gh.md), set up Github connection with your `staging` branch, and click `Initiate a sync` (via the project `Settings > Sync to Github` page). This will create the necessary config files in the Github branch. +6. Following [this guide](/manage-projects/link-to-gh.md), set up Github connection with your `staging` branch, and click `Initiate a sync` (via the project `Settings > Sync to Github` page). This will create the necessary config files in the Github branch. 7. In the newly generated `spec.yaml` file on the `staging` branch on Github, link your job `.js` files as explained in Step 1. diff --git a/docs/manage-projects/webhook-auth.md b/docs/manage-projects/webhook-auth.md index f2fa3365673c..7e664d806d25 100644 --- a/docs/manage-projects/webhook-auth.md +++ b/docs/manage-projects/webhook-auth.md @@ -11,7 +11,7 @@ to your webhook. In your OpenFn projects, you can utilize webhooks to receive data from external applications using a -[Webhook Trigger](../build/triggers.md). When using a +[Webhook Trigger](/build/triggers.md). When using a webhook, you can require external applications to authenticate before sending your project data for more security. diff --git a/docs/manage-users/api-tokens.md b/docs/manage-users/api-tokens.md index 0561af575696..fd4ae83e979a 100644 --- a/docs/manage-users/api-tokens.md +++ b/docs/manage-users/api-tokens.md @@ -12,7 +12,7 @@ OpenFn provides API permission for users to build or interact with their project on the platform via the API. You need a Personal Access Token to be able to access the platform via the API. You can find out more about creating or updating your project programmatically, visit our -[Portability](../deploy/portability.md) +[Portability](/deploy/portability.md) page. Your API access provides you the same level of permission as you have as a user diff --git a/docs/manage-users/user-credentials.md b/docs/manage-users/user-credentials.md index 3c1c39a8f6f8..4c2bb556bcd6 100644 --- a/docs/manage-users/user-credentials.md +++ b/docs/manage-users/user-credentials.md @@ -14,7 +14,7 @@ The `Credentials` page of your `User Settings` allows you to add, view, edit or ![User Credentials List](/img/lightning_edit_user_credential.webp) -For guidance on how to set up a new Credential, head over to our [Manage Credentials](../manage-projects/manage-credentials.md) page. +For guidance on how to set up a new Credential, head over to our [Manage Credentials](/manage-projects/manage-credentials.md) page. You can update the name and login details of a Credential after clicking `Edit`. diff --git a/docs/migration/converting-triggers.md b/docs/migration/converting-triggers.md index 1649487b5140..865c4df21121 100644 --- a/docs/migration/converting-triggers.md +++ b/docs/migration/converting-triggers.md @@ -12,13 +12,13 @@ OpenFn v1 to v2. ### Trigger Types on v1 We use -[4 types of triggers](../../versioned_docs/version-legacy/build/triggers.md) on +[4 types of triggers](/documentation/legacy/build/triggers) on v1: Message Filters, Cron Triggers, Flow Triggers, and Fail Triggers. ### Converting Cron Triggers -Setting up a [Cron Trigger on v2](../build/triggers.md#cron-triggers) works just -the same as on [v1](../../versioned_docs/version-legacy/build/triggers.md): when +Setting up a [Cron Trigger on v2](/build/triggers.md#cron-triggers) works just +the same as on [v1](/documentation/legacy/build/triggers): when you're building a Workflow, select Cron Schedule as Trigger type, and set the frequency. @@ -28,7 +28,7 @@ With a Flow trigger, we can execute a job upon success of another specified job. With a Fail trigger, the job will run if an another specified job failed. On v2, we achieve the same conditional behavior with -[Path Conditions](../build/paths.md): a job can run (1) always, (2), on success +[Path Conditions](/build/paths.md): a job can run (1) always, (2), on success of another job, (3) on failure of another job, or (4) on a custom condition - we'll get to this last one in the next section. @@ -64,7 +64,7 @@ workflows, instead of the previous common Inbox one. #### Path Conditions Once you've configured your -[Webhook](../build/triggers.md#webhook-event-triggers), you can use a custom +[Webhook](/build/triggers.md#webhook-event-triggers), you can use a custom Path Condition that matches a JavaScript expression to decide whether a subsequent job should be executed or not. diff --git a/docs/migration/migration-steps.md b/docs/migration/migration-steps.md index 0d3ff12b93aa..ee33835cf4cf 100644 --- a/docs/migration/migration-steps.md +++ b/docs/migration/migration-steps.md @@ -16,25 +16,25 @@ decisions. For customized migration support, ask your questions on our OpenFn-hosted platform ([register here](https://www.openfn.org/pricing) for free & paid plans) or deploy your own instance of [OpenFn/lightning](https://github.com/OpenFn/lightning). -2. [Customize your Project](../manage-projects/platform-mgmt.md) with a custom +2. [Customize your Project](/manage-projects/platform-mgmt.md) with a custom name and description. 3. Think about how long you want OpenFn to retain your input and output data and configure data storage accordingly. - [See this page](../manage-projects/io-data-storage.md) to learn more. + [See this page](/manage-projects/io-data-storage.md) to learn more. 4. Migrate your v1 project's `Jobs` configuration to the v2, as `Workflows`. See the below sections to determine if you prefer to automatically (recommended) or manually migrate your OpenFn configuration from your v1 to v2 project. -5. Create [Credentials](../build/credentials.md) for your test and production +5. Create [Credentials](/build/credentials.md) for your test and production systems. **First test your Workflows using your "test" or "sandbox" credentials.** 6. Once your Workflow Steps are fully configured, add a new custom input and - [run your workflow](../build/steps/step-editor.md) to start testing. -7. Check out the [History](../monitor-history/activity-history.md) page to + [run your workflow](/build/steps/step-editor.md) to start testing. +7. Check out the [History](/monitor-history/activity-history.md) page to monitor and review your Runs to confirm your Workflows are running successfully. 8. Test and iterate. 9. Once your Workflows are tested, sync your new v2 configuration to GitHub for - version control. Follow [this guide](../manage-projects/link-to-gh.md) to + version control. Follow [this guide](/manage-projects/link-to-gh.md) to learn how it works and set it up. :::warning Turn off GitHub sync on v1 before setting it up on v2 If you're @@ -69,7 +69,7 @@ decisions. For customized migration support, ask your questions on our 11. If your Workflows use a Webhook Trigger, you can add an extra layer of security by requiring webhook authentication - ([see relevant docs](../manage-projects/webhook-auth.md)). Note that if you + ([see relevant docs](/manage-projects/webhook-auth.md)). Note that if you do this, you will need to update the webhook configuration in the external app that points to OpenFn. 12. Fine-tune your security configuration by following our @@ -80,7 +80,7 @@ decisions. For customized migration support, ask your questions on our adjusted your Project Settings. 14. When all Workflows run successfully, update each Step in your Workflows to use a "production" Credential to connect to live systems. -15. While you're testing, you may be using [Path Conditions](../build/paths.md) +15. While you're testing, you may be using [Path Conditions](/build/paths.md) to allow only test data, such as `test_case == yes`. If you then want to exclude test data from your production systems, don't forget to update edge conditions, eg. `test_case == no`. Check out [this @@ -91,7 +91,7 @@ decisions. For customized migration support, ask your questions on our locate your Workflow's new webhook endpoint URL by clicking n the Trigger). 17. You’re now done with your new v2 Project setup! You can "turn on" your Workflows and monitor usage on your - [Workflows Dashboard](../manage-projects/workflow-dashboard.md). Now time to + [Workflows Dashboard](/manage-projects/workflow-dashboard.md). Now time to shut down your v1 project. 18. Turn "off" your Jobs on v1. 19. You have the option to export some of your v1 data: `Messages` and @@ -114,7 +114,7 @@ questions or issues, post on the [Community](https://community.openfn.org). ## How to automatically migrate your OpenFn project configuration to v2 Check out our docs on -[Self-Guided Migration](../migration/automated-migration.md) to learn more about +[Self-Guided Migration](/migration/automated-migration.md) to learn more about how to _automatically_ migrate your configuration from v1 to v2. **This is the recommended process** but requires admin-level user access to both your v1 and v2 Projects. @@ -122,23 +122,23 @@ v2 Projects. ### How to manually migrate your OpenFn project configuration to v2 1. On v2, the Jobs you use for automating tasks are organized as - [Workflows](../tutorials/tutorial.md), where each Job is 1 "Step" in a + [Workflows](/tutorials/tutorial.md), where each Job is 1 "Step" in a Workflow. Build out a skeleton to get started: set up - [Triggers](../build/triggers.md) and the key + [Triggers](/build/triggers.md) and the key [Steps](https://docs.openfn.org/documentation/build/steps) to get started. 2. While configuring the Steps in your workflow, consider _which conditions_ define when the next Step should execute. On v2, you can define [Path conditions](https://docs.openfn.org/documentation/build/paths) to configure whether a Step should run "on success", "on failure", or based on custom logic. Follow - [our guide on converting your v1 "triggers" to v2 configuration](../migration/converting-triggers.md) + [our guide on converting your v1 "triggers" to v2 configuration](/migration/converting-triggers.md) to learn more. 3. Once the basic Steps and Paths are configured, copy your job code from your GitHub repository or directly from your v1 project and paste it into each Step's Inspector view. Get familiar with the revamped Job Inspector for code - editing [here](../build/steps/step-editor.md). + editing [here](/build/steps/step-editor.md). 4. Make sure the Adaptor and Adaptor Version match your v1 jobs exactly. See the - [Steps docs](../build/steps/step-editor.md) for more info on these. + [Steps docs](/build/steps/step-editor.md) for more info on these. :::info diff --git a/docs/monitor-history/activity-history.md b/docs/monitor-history/activity-history.md index f1e51664ae66..ef510a2d08d8 100644 --- a/docs/monitor-history/activity-history.md +++ b/docs/monitor-history/activity-history.md @@ -35,7 +35,7 @@ OpenFn Workflows are executed as follows: Order will be updated with a `success` status. You can also **cancel** pending runs or **retry** completed work orders directly -from the History page. See [Retry & Cancel Runs](./rerunning-workflow.md) for +from the History page. See [Retry & Cancel Runs](/monitor-history/rerunning-workflow.md) for details. ![History Page](/img/history-page-annotated.webp) diff --git a/docs/monitor-history/inspect-runs.md b/docs/monitor-history/inspect-runs.md index e63b28fa78e6..0d75d5f6b30c 100644 --- a/docs/monitor-history/inspect-runs.md +++ b/docs/monitor-history/inspect-runs.md @@ -3,13 +3,13 @@ title: Inspect Runs & Search via the History page sidebar_label: Inspect Runs --- -A [Run](../get-started/terminology.md#run) is created each time +A [Run](/get-started/terminology.md#run) is created each time OpenFn attempts to excute a Workflow for a given Work Order. All Runs can be viewed, filtered, and searched via the `History` page. In short, Runs tell us "what happened" when OpenFn tried to execute the Workflow. Runs have start times, end times, logs, and -[status codes](./status-codes.md) that indicate +[status codes](/monitor-history/status-codes.md) that indicate when they took place, what they did, and whether or not they succeeded. ## Inspect Runs diff --git a/docs/monitor-history/rerunning-workflow.md b/docs/monitor-history/rerunning-workflow.md index 3f685bed2e01..b348ed250c1a 100644 --- a/docs/monitor-history/rerunning-workflow.md +++ b/docs/monitor-history/rerunning-workflow.md @@ -68,7 +68,7 @@ To rerun your Workflow from the `Inspector` page: If runs are stuck in the queue or were created by mistake, you can cancel them. Cancelling moves runs from `available` to `cancelled` and updates the corresponding work order status from `pending` to `cancelled`. See -[Status Codes](./status-codes.md) for more on what each status means. +[Status Codes](/monitor-history/status-codes.md) for more on what each status means. There are several ways to cancel: diff --git a/docs/monitor-history/status-codes.md b/docs/monitor-history/status-codes.md index 1ef16e1d4954..304aa9bd9edc 100644 --- a/docs/monitor-history/status-codes.md +++ b/docs/monitor-history/status-codes.md @@ -33,7 +33,7 @@ Every Run has a status which indicates whether it completed successfully. | Failed | 🔴 | RangeError | No | Calling `state.patients[5]` when only 2 patients exist | | Crashed | 🟠 | SyntaxError | Yes | You've got some bad JavaScript and the worker cannot compile your job code | | Crashed | 🟠 | ReferenceError | Yes | You've got an undeclared variable in your job code | -| Cancelled | ⚪ | | Yes | The run had been enqueued but was [manually removed](./rerunning-workflow.md#cancel-pending-runs) from the queue | +| Cancelled | ⚪ | | Yes | The run had been enqueued but was [manually removed](/monitor-history/rerunning-workflow.md#cancel-pending-runs) from the queue | | Killed | 🟡 | SecurityError | Yes | Your code failed security checks, e.g. tried to use `eval` | | Killed | 🟡 | ImportError | Yes | You tried to import external module that we don't allow | | Killed | 🟡 | OomError | Yes | Your run used more memory than allowed by the Lightning instance | diff --git a/docs/monitor-history/troubleshooting.md b/docs/monitor-history/troubleshooting.md index 32f7d0a542e3..3ef361b4d8f6 100644 --- a/docs/monitor-history/troubleshooting.md +++ b/docs/monitor-history/troubleshooting.md @@ -15,16 +15,16 @@ This page provides troubleshooting tips for _OpenFn v2 platform_ users. ## Runs One of the most helpful pages for troubleshooting on OpenFn is the -[History](./activity-history.md) page. This page provides a list of all of the +[History](/monitor-history/activity-history.md) page. This page provides a list of all of the runs executed for a Work Order and their status. Project administrators can troubleshoot errors by clicking into the run to review the run details. Learn -more about runs [here](./inspect-runs.md) here. +more about runs [here](/monitor-history/inspect-runs.md) here. ### Status codes Every run will have a status code. The status code is a way for OpenFn to classify the run status and can help you troubleshoot errors. Learn more about -OpenFn status codes and what each one means [here](./status-codes.md). +OpenFn status codes and what each one means [here](/monitor-history/status-codes.md). ### The time it took for the workflow to fail @@ -111,7 +111,7 @@ to use Search. ## Sign up for email alerts You can turn on notifications to receive -[email alerts](../manage-projects/notifications.md) when a workflow fails and +[email alerts](/manage-projects/notifications.md) when a workflow fails and subscribe to digests that summarize project activity. ## More diff --git a/docs/tutorials/commcare-to-db.md b/docs/tutorials/commcare-to-db.md index 57432a272d52..006e58f7e23a 100644 --- a/docs/tutorials/commcare-to-db.md +++ b/docs/tutorials/commcare-to-db.md @@ -9,8 +9,8 @@ title: Syncing your CommCare form submissions to a PostgreSQL database minute!) - You have checked out our glossary and have an understanding of basic OpenFn and API terminology. Check out the pages below to get started - - [OpenFn Concepts](../get-started/terminology.md) - - [A glossary for data integration](../get-started/glossary.md) + - [OpenFn Concepts](/get-started/terminology.md) + - [A glossary for data integration](/get-started/glossary.md) - You have a CommCare application with at least one form configured. This is your source system. - You have a PostgreSQL database configured. This is your destination system. @@ -104,7 +104,7 @@ and will trigger your new workflow. configured the database [like this](https://docs.google.com/spreadsheets/d/1pi_oxImakhtaCCCIENkjTPZeuyWhpFEcNmH7hfvTBgo/edit?usp=sharing) to capture the CommCare form data. Check out the - [this page](../design/mapping-specs) for how to create your own + [this page](/design/mapping-specs.md) for how to create your own `mapping specification document` to map data elements to be exchanged. ![db_config](/img/db_config.webp) diff --git a/docs/tutorials/http-to-googlesheets.md b/docs/tutorials/http-to-googlesheets.md index ff1abea1c410..84143ed7d1a0 100644 --- a/docs/tutorials/http-to-googlesheets.md +++ b/docs/tutorials/http-to-googlesheets.md @@ -21,8 +21,8 @@ Here are some we assume you've looked over before you begin this process. - You have checked out our glossary and have an understanding of basic OpenFn & API concepts. Check out the pages below to get started - - [OpenFn Concepts](../get-started/terminology.md) - - [A glossary for data integration](../get-started/glossary.md) + - [OpenFn Concepts](/get-started/terminology.md) + - [A glossary for data integration](/get-started/glossary.md) - You have a Google Account. We will use it to create a credential to authorize with Google Sheets. - You have access to an OpenFn project (either on a locally installed @@ -49,8 +49,8 @@ To create a new Workflow in your Project: 1. Go to the `project dashboard` page. 2. Click `Create new workflow` button. 3. Give your Workflow a descriptive `Name` (e.g., `Sync Users List`). -4. Choose your [Trigger](../build/triggers.md) -5. Edit your first [Step](../build/steps/steps.md) +4. Choose your [Trigger](/build/triggers.md) +5. Edit your first [Step](/build/steps/steps.md) ## 2. Configure your first Step to get data from the REST API @@ -72,14 +72,14 @@ following options :::tip Need help writing job code? Check out the docs on the ["http" Adaptor](/adaptors/packages/http-readme), -[configuring Steps](../build/steps/steps.md), and -[job-writing](../jobs/job-writing-guide.md). +[configuring Steps](/build/steps/steps.md), and +[job-writing](/jobs/job-writing-guide.md). ::: **Once you are finished configuring and writing your Step, save and run it!** -- See the [Workflows section](../build/workflows.md) for more guidance on +- See the [Workflows section](/build/workflows.md) for more guidance on building & running Workflows. **Check out the `Output & Log` panel to see if your run succeeded.** If it @@ -162,8 +162,8 @@ test `Sync Users` Step. Select the input from the input panel and click 5. Finally check your spreadsheet to see the synced users data Encountering errors or getting stuck? Check out the -[Workflow](../build/workflows.md) or -[Troubleshooting](../monitor-history/troubleshooting.md) docs. +[Workflow](/build/workflows.md) or +[Troubleshooting](/monitor-history/troubleshooting.md) docs. :::tip Are you blocked? Have questions? diff --git a/docs/tutorials/kobo-to-dhis2.md b/docs/tutorials/kobo-to-dhis2.md index 118af5673a67..b998958d4285 100644 --- a/docs/tutorials/kobo-to-dhis2.md +++ b/docs/tutorials/kobo-to-dhis2.md @@ -65,7 +65,7 @@ configuration In this Step we want to be fetch form submissions from this demo form with the id `aBpweTNdaGJQFb5EBBwUeo`. To do so, open the -[Inspector Editor](../build/steps/step-editor.md) and add the following Job +[Inspector Editor](/build/steps/step-editor.md) and add the following Job code: ```javascript @@ -76,8 +76,8 @@ getSubmissions({ formId: 'aBpweTNdaGJQFb5EBBwUeo' }); ::: tip Need help writing job code? Check out the docs on the ["kobotoolbox" Adaptor](/adaptors/kobotoolbox), -[configuring Steps](../build/steps/steps.md), and -[job-writing](../jobs/job-writing-guide.md). +[configuring Steps](/build/steps/steps.md), and +[job-writing](/jobs/job-writing-guide.md). ::: @@ -90,7 +90,7 @@ Check out the docs on the ["kobotoolbox" Adaptor](/adaptors/kobotoolbox), #### Testing: Create an empty input `{}` then click `Create New Work Order` button to run the -workflow. [See docs](../build/workflows.md) for more on running Workflows +workflow. [See docs](/build/workflows.md) for more on running Workflows manually. The expected ` output` should contain 17 records in `state.data.results` @@ -105,7 +105,7 @@ Create a second Step after `Get Kobo Form Submission` as follows: - Credential: none needd In this step we are going to count all records with `"OPV0_dose_given": "yes"`. -To add this logic, open the [Inspector](../build/steps/step-editor.md) and add +To add this logic, open the [Inspector](/build/steps/step-editor.md) and add the following JOb code in the Editor: ```javascript @@ -122,8 +122,8 @@ fn(state => { :::tip Need help writing job code? Or modifying this logic? Check out the docs on the ["common" Adaptor](/adaptors/packages/common-docs), -[configuring Steps](../build/steps/steps.md), and -[job-writing](../jobs/job-writing-guide.md). +[configuring Steps](/build/steps/steps.md), and +[job-writing](/jobs/job-writing-guide.md). ::: @@ -137,7 +137,7 @@ Check out the docs on the ["common" Adaptor](/adaptors/packages/common-docs), #### Testing: Select the first step `Get Kobo Form Submission` and `Create New Work Order` -with an empty input ([see Workflow docs](../build/workflows.md) if you need help +with an empty input ([see Workflow docs](/build/workflows.md) if you need help with running and testing steps). Both steps should be executed successfully and you should see in the final state `opvDosesGivenCount: 3` added. @@ -161,7 +161,7 @@ Create a third Step after `Count OPV Dose Given` as follows: In this Step, we want to add logic to import `dataValues` to DHIS2 to "report" on the aggregated OPV0 immunization does count calculated in Step 2. -To do so, open the [Inspector](../build/steps/step-editor.md), add the following +To do so, open the [Inspector](/build/steps/step-editor.md), add the following Job code in the Editor: ```javascript @@ -183,8 +183,8 @@ create('dataValueSets', state => ({ :::tip Need help writing job code? Or modifying this logic? Check out the docs on the ["dhis2" Adaptor](/adaptors/dhis2), -[configuring Steps](../build/steps/steps.md), and -[job-writing](../jobs/job-writing-guide.md). +[configuring Steps](/build/steps/steps.md), and +[job-writing](/jobs/job-writing-guide.md). ::: @@ -201,7 +201,7 @@ Check out the docs on the ["dhis2" Adaptor](/adaptors/dhis2), Save your changes then navigate to the first step(Get Kobo Form Submission) and create an empty input `{}` then click `Create New Work Order` button to run the workflow. All steps should be executed successful and you should see the -`OPV0 doses given` updated in DHIS2. See [Workflow docs](../build/workflows.md) +`OPV0 doses given` updated in DHIS2. See [Workflow docs](/build/workflows.md) if you need help running or testing Workflows. ### Conclusion diff --git a/docs/tutorials/tutorial.md b/docs/tutorials/tutorial.md index 18f3cf78cc50..fc333cc2d3f5 100644 --- a/docs/tutorials/tutorial.md +++ b/docs/tutorials/tutorial.md @@ -6,17 +6,17 @@ sidebar_label: Workflow QuickStart # QuickStart: Creating your first workflow 1. Go to your OpenFn Project > `Workflows` -2. Create a new [Workflow](../build/workflows.md) -3. Choose your [Trigger type](../build/triggers.md): Webhook Event (for real-time integration) or Cron Expression (for timer/scheduled-based integration) -3. Name your first `Step` (e.g., "Import form submission") and open it to choose the [Adaptor](/adaptors), Adaptor `Version`, and [Credential](../build/credentials.md) -4. Click the `` code button to open the [Inspector](../build/steps/step-editor.md) and add job code to the `Editor` panel to define the specific business logic or transformation rules for this workflow +2. Create a new [Workflow](/build/workflows.md) +3. Choose your [Trigger type](/build/triggers.md): Webhook Event (for real-time integration) or Cron Expression (for timer/scheduled-based integration) +3. Name your first `Step` (e.g., "Import form submission") and open it to choose the [Adaptor](/adaptors), Adaptor `Version`, and [Credential](/build/credentials.md) +4. Click the `` code button to open the [Inspector](/build/steps/step-editor.md) and add job code to the `Editor` panel to define the specific business logic or transformation rules for this workflow 5. In the `Input` panel on the left, add a custom input (e.g., a payload from a webhook request) or simply add empty brackets (`{}`) to run a Workflow with a cron trigger. See the [Workflow docs](docs/build/workflows.md) for help with running and testing Workflow. 6. If the Step suceeds, navigate back to the Canvase view and click the `+` icon to add a second Step. -7. If you want to define conditions for if/when this second Step should execute, update the [Path condition](../build/paths.md). +7. If you want to define conditions for if/when this second Step should execute, update the [Path condition](/build/paths.md). 8. Then repeat the instruction steps #3-6 to finishing configuring this next Step, until the Workflow is complete. :::tip -Check out the video and docs on the [Workflows page](../build/workflows.md) in the `Build` docs for in-depth help, or ask your questions on [Community](https://community.openfn.org)! +Check out the video and docs on the [Workflows page](/build/workflows.md) in the `Build` docs for in-depth help, or ask your questions on [Community](https://community.openfn.org)! ::: From fd61e318319462711b579044f58b98a1a3c2ac88 Mon Sep 17 00:00:00 2001 From: Lucy Macartney Date: Fri, 25 Sep 2026 16:01:55 +0100 Subject: [PATCH 2/2] Make docs-root file paths the house style for links (#867) --- .agents/skills/translate/SKILL.md | 13 +++++-------- AGENTS.md | 8 +++++--- 2 files changed, 10 insertions(+), 11 deletions(-) diff --git a/.agents/skills/translate/SKILL.md b/.agents/skills/translate/SKILL.md index e060e87589e2..71db38613777 100644 --- a/.agents/skills/translate/SKILL.md +++ b/.agents/skills/translate/SKILL.md @@ -112,14 +112,11 @@ what to do with it. translated button name points the reader at a button that does not exist. - Keep the same structure: same headings at the same levels, same lists, same callouts, same components. -- Keep internal links as they are in the English. Do not add `/es/` or - `/fr/`; Docusaurus adds the locale when it builds the page. -- The one exception: a relative link like `../deploy/portability.md` breaks - if the page it points to has no translation yet. Write it as the page's - full address instead, like `/documentation/deploy/portability`. If the - target page sets a `slug` in its front matter, the address is - `/documentation` plus the slug: `slug: /api-tokens` gives - `/documentation/api-tokens`, not the folder path. +- Keep links exactly as they are in the English. Do not add `/es/` or + `/fr/`; Docusaurus adds the locale when it builds the page. If the English + has a relative link like `../deploy/portability.md`, it breaks the + translated build, so fix it in the English first (see the house style in + `AGENTS.md`). - Give translated headings the original English anchor so existing links still work. diff --git a/AGENTS.md b/AGENTS.md index 94a9cc028807..c2fb3d5bbea3 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -82,9 +82,11 @@ Translations go in their own PR per locale and do not count toward the 20. ## House style - Every page has a `title` in its front matter. -- Internal links start with `/documentation/`, `/adaptors/`, or `/articles/`. - Never use relative `.md` links; they break the build once a page is - translated. +- Link to another docs page by its file path from the top of `docs/`, like + `/deploy/portability.md`. Link to adaptor pages and articles by URL, starting + with `/adaptors/` or `/articles/`. Never use relative links like + `../deploy/portability.md`; they break the build once only one of the two + pages is translated. - Images live in `static/img/` and are linked as `/img/filename`, with alt text that says what the image shows. "Screenshot" does not count. - Leave a blank line after an admonition's opening line (`:::tip`, `:::note`,