Change repo links to absolute file paths (n8n-io#2829)

Co-authored-by: Nick Veitch <[email protected]>

Author: imchairmanm

_doctools/change_link_style.py

@@ -0,0 +1,54 @@
+#!/usr/bin/env python3
+from pathlib import Path
+import argparse
+import re
+
+def find_markdown_files(directory):
+	"""Return a list of path objects for all markdown files in the given directory."""
+	return list(Path(directory).rglob("*.[mM][dD]"))
+
+def map_urls_to_files(path_list, root_dir):
+	"""Return a dictionary mapping URL link targets to file targets."""
+	path_maps = dict()
+	for path in path_list:
+		# Here, we convert file paths to absolute paths from the root_dir
+		md_link_target = "/" / path.relative_to(root_dir)
+		url_link_target = get_url_path_from_file_path(md_link_target)
+		path_maps[url_link_target] = str(md_link_target)
+
+	return path_maps
+
+def get_url_path_from_file_path(file_path):
+	"""Return the URL path for a given file path."""
+	if file_path.name == "index.md":
+		return str(file_path.parent)
+	else:
+		return str(file_path.parent / file_path.stem)
+
+def main(directory):
+	"""
+	Finds Markdown files, calculates URL paths associated with them, then finds and
+	replaces URL paths with file paths in links throughout the repo.
+	"""
+	markdown_files = find_markdown_files(directory)
+	snippet_files = find_markdown_files("../_snippets")
+	link_maps = map_urls_to_files(markdown_files, directory)
+
+	for file in markdown_files + snippet_files:
+		text = file.read_text()
+
+		for url_target, file_target in link_maps.items():
+			find_pattern = fr"]\({url_target}/?(#[0-9A-Za-z-]+)?\)"
+			replace_pattern = fr"]({file_target}\1)"
+			text = re.sub(find_pattern, replace_pattern, text)
+
+		file.write_text(text)
+
+
+if __name__ == "__main__":
+	parser = argparse.ArgumentParser(description="Replace URL style link targets with markdown file targets")
+	parser.add_argument("--dir", type=str, default="../docs", help="Directory to scan (default: '../docs')")
+
+	args = parser.parse_args()
+	main(args.dir)
+

_snippets/code/tournament-notes.md

@@ -2,5 +2,5 @@
 If you have issues with expressions in 1.9.0:
 
 * Please report the issue on the [forums](https://community.n8n.io/){:target=_blank .external-link}.
-* Self-hosted users can switch back to RiotTmpl: set `N8N_EXPRESSION_EVALUATOR` to `tmpl`.  Refer to [Environment variables](/hosting/configuration/environment-variables/) for more information on configuring self-hosted n8n.  
+* Self-hosted users can switch back to RiotTmpl: set `N8N_EXPRESSION_EVALUATOR` to `tmpl`.  Refer to [Environment variables](/hosting/configuration/environment-variables/index.md) for more information on configuring self-hosted n8n.  
 /// 

_snippets/data/data-mapping/item-linking-code-node.md

@@ -1,4 +1,4 @@
-Use n8n's item linking to access data from items that precede the current item. It also has implications when using the Code node. Most nodes link every output item to an input item. This creates a chain of items that you can work back along to access previous items. For a deeper conceptual overview of this topic, refer to [Item linking concepts](/data/data-mapping/data-item-linking/item-linking-concepts). This document focuses on practical usage examples.
+Use n8n's item linking to access data from items that precede the current item. It also has implications when using the Code node. Most nodes link every output item to an input item. This creates a chain of items that you can work back along to access previous items. For a deeper conceptual overview of this topic, refer to [Item linking concepts](/data/data-mapping/data-item-linking/item-linking-concepts.md). This document focuses on practical usage examples.
 
 When using the Code node, there are some scenarios where you need to manually supply item linking information if you want to be able to use `$("<node-name>").item` later in the workflow. All these scenarios only apply if you have more than one incoming item. n8n automatically handles item linking for single items.
 
@@ -8,7 +8,7 @@ These scenarios are when you:
 * Return new items.
 * Want to manually control the item linking.
 
-[n8n's automatic item linking](/data/data-mapping/data-item-linking/item-linking-concepts/) handles the other scenarios.
+[n8n's automatic item linking](/data/data-mapping/data-item-linking/item-linking-concepts.md) handles the other scenarios.
 
 To control item linking, set `pairedItem` when returning data. For example, to link to the item at index 0:
 

_snippets/data/data-mapping/item-linking-node-creators.md

@@ -4,9 +4,9 @@ This guidance applies to programmatic-style nodes. If you're using declarative s
 
 Use n8n's item linking to access data from items that precede the current item. n8n needs to know which input item a given output item comes from. If this information is missing, expressions in other nodes may break. As a node developer, you must ensure any items returned by your node support this. 
 
-This applies to programmatic nodes (including trigger nodes). You don't need to consider item linking when building a declarative-style node. Refer to [Choose your node building approach](/integrations/creating-nodes/plan/choose-node-method/) for more information on node styles.
+This applies to programmatic nodes (including trigger nodes). You don't need to consider item linking when building a declarative-style node. Refer to [Choose your node building approach](/integrations/creating-nodes/plan/choose-node-method.md) for more information on node styles.
 
-Start by reading [Item linking concepts](/data/data-mapping/data-item-linking/item-linking-concepts/), which provides a conceptual overview of item linking, and details of the scenarios where n8n can handle the linking automatically.
+Start by reading [Item linking concepts](/data/data-mapping/data-item-linking/item-linking-concepts.md), which provides a conceptual overview of item linking, and details of the scenarios where n8n can handle the linking automatically.
 
 If you need to handle item linking manually, do this by setting `pairedItem` on each item your node returns:
 

_snippets/flow-logic/subworkflow-usage.md

@@ -4,12 +4,12 @@
 1. Create a new workflow.
 
     /// note | Create sub-workflows from existing workflows
-    You can optionally create a sub-workflow directly from an existing parent workflow using the [Execute Sub-workflow](/integrations/builtin/core-nodes/n8n-nodes-base.executeworkflow/) node. In the node, select the **Database** and **From list** options and select **Create a sub-workflow** in the list.
+    You can optionally create a sub-workflow directly from an existing parent workflow using the [Execute Sub-workflow](/integrations/builtin/core-nodes/n8n-nodes-base.executeworkflow.md) node. In the node, select the **Database** and **From list** options and select **Create a sub-workflow** in the list.
     ///
 
 1. **Optional**: configure which workflows can call the sub-workflow:
 	1. Select the **Options** <span class="inline-image">![Options menu](/_images/common-icons/three-dot-options-menu.png){.off-glb}</span> menu > **Settings**. n8n opens the **Workflow settings** modal.
-	1. Change the **This workflow can be called by** setting.	Refer to [Workflow settings](/workflows/settings/) for more information on configuring your workflows.
+	1. Change the **This workflow can be called by** setting.	Refer to [Workflow settings](/workflows/settings.md) for more information on configuring your workflows.
 1. Add the **Execute Sub-workflow** trigger node (if you are searching under trigger nodes, this is also titled **When Executed by Another Workflow**).
 1. Set the **Input data mode** to choose how you will define the sub-workflow's input data:
 	* **Define using fields below**: Choose this mode to define individual input names and data types that the calling workflow needs to provide.
@@ -22,15 +22,15 @@
 If there are errors in the sub-workflow, the parent workflow can't trigger it.
 ///
 /// note | Load data into sub-workflow before building
-This requires the ability to [load data from previous executions](/workflows/executions/debug/), which is available on n8n Cloud and registered Community plans.
+This requires the ability to [load data from previous executions](/workflows/executions/debug.md), which is available on n8n Cloud and registered Community plans.
 
 If you want to load data into your sub-workflow to use while building it:
 
 1. Create the sub-workflow and add the **Execute Sub-workflow Trigger**. 
 1. Set the node's **Input data mode** to **Accept all data** or define the input items using fields or JSON if they're already known.
-1. In the sub-workflow [settings](/workflows/settings/), set **Save successful production executions** to **Save**. 
+1. In the sub-workflow [settings](/workflows/settings.md), set **Save successful production executions** to **Save**. 
 1. Skip ahead to setting up the parent workflow, and run it.
-1. Follow the steps to [load data from previous executions](/workflows/executions/debug/).
+1. Follow the steps to [load data from previous executions](/workflows/executions/debug.md).
 1. Adjust the **Input data mode** to match the input sent by the parent workflow if necessary.
 
 You can now pin example data in the trigger node, enabling you to work with real data while configuring the rest of the workflow.

_snippets/integrations/builtin/app-nodes/operation-not-supported.md

@@ -1,11 +1,11 @@
 ## What to do if your operation isn't supported
 
-If this node doesn't support the operation you want to do, you can use the [HTTP Request node](/integrations/builtin/core-nodes/n8n-nodes-base.httprequest/) to call the service's API.
+If this node doesn't support the operation you want to do, you can use the [HTTP Request node](/integrations/builtin/core-nodes/n8n-nodes-base.httprequest/index.md) to call the service's API.
 
 You can use the credential you created for this service in the HTTP Request node: 
 
 1. In the HTTP Request node, select **Authentication** > **Predefined Credential Type**.
 1. Select the service you want to connect to.
 1. Select your credential.
 
-Refer to [Custom API operations](/integrations/custom-operations/) for more information.
+Refer to [Custom API operations](/integrations/custom-operations.md) for more information.

_snippets/integrations/builtin/cluster-nodes/langchain-overview-link.md

@@ -1 +1 @@
-View n8n's [Advanced AI](/advanced-ai/) documentation.
+View n8n's [Advanced AI](/advanced-ai/index.md) documentation.

_snippets/integrations/builtin/cluster-nodes/langchain-root-nodes/langchaincode/builtin-methods.md

@@ -1,7 +1,7 @@
 | Method | Description |
 | ------ | ----------- |
-| `this.addInputData(inputName, data)` | Populate the data of a specified non-main input. Useful for mocking data.<ul><li>`inputName` is the input connection type, and must be one of: `ai_agent`, `ai_chain`, `ai_document`, `ai_embedding`, `ai_languageModel`, `ai_memory`, `ai_outputParser`, `ai_retriever`, `ai_textSplitter`, `ai_tool`, `ai_vectorRetriever`, `ai_vectorStore`</li><li>`data` contains the data you want to add. Refer to [Data structure](/data/data-structure/) for information on the data structure expected by n8n.</li></ul> |
-| `this.addOutputData(outputName, data)` | Populate the data of a specified non-main output. Useful for mocking data.<ul><li>`outputName` is the input connection type, and must be one of: `ai_agent`, `ai_chain`, `ai_document`, `ai_embedding`, `ai_languageModel`, `ai_memory`, `ai_outputParser`, `ai_retriever`, `ai_textSplitter`, `ai_tool`, `ai_vectorRetriever`, `ai_vectorStore`</li><li>`data` contains the data you want to add. Refer to [Data structure](/data/data-structure/) for information on the data structure expected by n8n.</li></ul> |
+| `this.addInputData(inputName, data)` | Populate the data of a specified non-main input. Useful for mocking data.<ul><li>`inputName` is the input connection type, and must be one of: `ai_agent`, `ai_chain`, `ai_document`, `ai_embedding`, `ai_languageModel`, `ai_memory`, `ai_outputParser`, `ai_retriever`, `ai_textSplitter`, `ai_tool`, `ai_vectorRetriever`, `ai_vectorStore`</li><li>`data` contains the data you want to add. Refer to [Data structure](/data/data-structure.md) for information on the data structure expected by n8n.</li></ul> |
+| `this.addOutputData(outputName, data)` | Populate the data of a specified non-main output. Useful for mocking data.<ul><li>`outputName` is the input connection type, and must be one of: `ai_agent`, `ai_chain`, `ai_document`, `ai_embedding`, `ai_languageModel`, `ai_memory`, `ai_outputParser`, `ai_retriever`, `ai_textSplitter`, `ai_tool`, `ai_vectorRetriever`, `ai_vectorStore`</li><li>`data` contains the data you want to add. Refer to [Data structure](/data/data-structure.md) for information on the data structure expected by n8n.</li></ul> |
 | `this.getInputConnectionData(inputName, itemIndex, inputIndex?)` | Get data from a specified non-main input.<ul><li>`inputName` is the input connection type, and must be one of: `ai_agent`, `ai_chain`, `ai_document`, `ai_embedding`, `ai_languageModel`, `ai_memory`, `ai_outputParser`, `ai_retriever`, `ai_textSplitter`, `ai_tool`, `ai_vectorRetriever`, `ai_vectorStore`</li><li>`itemIndex` should always be `0` (this parameter will be used in upcoming functionality)</li><li>Use `inputIndex` if there is more than one node connected to the specified input.</li></ul> |
 | `this.getInputData(inputIndex?, inputName?)` | Get data from the main input. |
 | `this.getNode()` | Get the current node. |

_snippets/integrations/builtin/cluster-nodes/langchain-root-nodes/output-format.md

@@ -1,5 +1,5 @@
 This parameter controls whether you want the node to require a specific output format. When turned on, n8n prompts you to connect one of these output parsers to the node:
 
-* [Auto-fixing Output Parser](/integrations/builtin/cluster-nodes/sub-nodes/n8n-nodes-langchain.outputparserautofixing/)
-* [Item List Output Parser](/integrations/builtin/cluster-nodes/sub-nodes/n8n-nodes-langchain.outputparseritemlist/)
-* [Structured Output Parser](/integrations/builtin/cluster-nodes/sub-nodes/n8n-nodes-langchain.outputparserstructured/)
+* [Auto-fixing Output Parser](/integrations/builtin/cluster-nodes/sub-nodes/n8n-nodes-langchain.outputparserautofixing.md)
+* [Item List Output Parser](/integrations/builtin/cluster-nodes/sub-nodes/n8n-nodes-langchain.outputparseritemlist.md)
+* [Structured Output Parser](/integrations/builtin/cluster-nodes/sub-nodes/n8n-nodes-langchain.outputparserstructured/index.md)

_snippets/integrations/builtin/cluster-nodes/langchain-root-nodes/vector-store-metadata-filter.md

@@ -2,4 +2,4 @@ Available in **Get Many** mode. When searching for data, use this to match with
 
 This is an `AND` query. If you specify more than one metadata filter field, all of them must match.
 
-When inserting data, the metadata is set using the document loader. Refer to [Default Data Loader](/integrations/builtin/cluster-nodes/sub-nodes/n8n-nodes-langchain.documentdefaultdataloader/) for more information on loading documents.
+When inserting data, the metadata is set using the document loader. Refer to [Default Data Loader](/integrations/builtin/cluster-nodes/sub-nodes/n8n-nodes-langchain.documentdefaultdataloader.md) for more information on loading documents.

_snippets/integrations/builtin/cluster-nodes/use-with-chat-trigger.md

@@ -1 +1 @@
-You can use this agent with the [Chat Trigger](/integrations/builtin/core-nodes/n8n-nodes-langchain.chattrigger/) node. Attach a memory sub-node so that users can have an ongoing conversation with multiple queries. Memory doesn't persist between sessions.
+You can use this agent with the [Chat Trigger](/integrations/builtin/core-nodes/n8n-nodes-langchain.chattrigger/index.md) node. Attach a memory sub-node so that users can have an ongoing conversation with multiple queries. Memory doesn't persist between sessions.