Skip to content

Commit b9ae73e

Browse files
hillary-mutisyahillary-mutisya
authored
Update docs folder structure (#1164)
- Move the markdown files under /docs/content. This will enable us to add /docs/blog and other paths in future as needed - Updated the eleventy link processing logic to handle arbitrary nesting of the markdown folders.
1 parent 8d61c03 commit b9ae73e

File tree

16 files changed

+249
-197
lines changed

16 files changed

+249
-197
lines changed

‎docs/.eleventy.js‎

Lines changed: 68 additions & 50 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ module.exports = function (eleventyConfig) {
1212
eleventyConfig.addPassthroughCopy("_includes");
1313
eleventyConfig.addPassthroughCopy("assets");
1414
eleventyConfig.addPassthroughCopy("content/imgs");
15-
eleventyConfig.addPassthroughCopy("tutorial/imgs");
15+
eleventyConfig.addPassthroughCopy("content/tutorial/imgs");
1616

1717
eleventyConfig.addShortcode("version", function () {
1818
return String(Date.now());
@@ -31,32 +31,33 @@ module.exports = function (eleventyConfig) {
3131
linkify: true,
3232
};
3333

34-
// Add a shortcode for repository links
35-
eleventyConfig.addShortcode("repo", function(path, text) {
36-
const repoUrl = process.env.GITHUB_REPOSITORY ?
37-
`https://github.com/${process.env.GITHUB_REPOSITORY}` :
38-
this.ctx?.site?.github || 'https://github.com/microsoft/TypeAgent';
39-
40-
const defaultBranch = process.env.GITHUB_DEFAULT_BRANCH || 'main';
41-
42-
const normalizedPath = path.replace(/^\.\.\/|^\//g, '');
43-
34+
// Add a shortcode for repository links
35+
eleventyConfig.addShortcode("repo", function (path, text) {
36+
const repoUrl = process.env.GITHUB_REPOSITORY
37+
? `https://github.com/${process.env.GITHUB_REPOSITORY}`
38+
: this.ctx?.site?.github || "https://github.com/microsoft/TypeAgent";
39+
40+
const defaultBranch = process.env.GITHUB_DEFAULT_BRANCH || "main";
41+
42+
const normalizedPath = path.replace(/^\.\.\/|^\//g, "");
43+
4444
// Determine the correct GitHub URL based on whether it's a file or directory
45-
const githubUrl = isDirectory ?
46-
`${repoUrl}/tree/${defaultBranch}/${normalizedPath}` :
47-
`${repoUrl}/blob/${defaultBranch}/${normalizedPath}`;
48-
45+
const isDirectory = !normalizedPath.includes(".");
46+
const githubUrl = isDirectory
47+
? `${repoUrl}/tree/${defaultBranch}/${normalizedPath}`
48+
: `${repoUrl}/blob/${defaultBranch}/${normalizedPath}`;
49+
4950
// Return markdown link
5051
return `[${text || normalizedPath}](${githubUrl})`;
5152
});
52-
53+
5354
// Add debugging shortcode to show the current URL
54-
eleventyConfig.addShortcode("debugUrl", function() {
55+
eleventyConfig.addShortcode("debugUrl", function () {
5556
return `
5657
<div style="background: #f8d7da; padding: 10px; margin: 10px 0; border: 1px solid #f5c6cb;">
5758
<p><strong>Debug Path Information:</strong></p>
5859
<p>Path Prefix: ${pathPrefix}</p>
59-
<p>Full Base URL: ${this.page ? this.page.url : 'No page context'}</p>
60+
<p>Full Base URL: ${this.page ? this.page.url : "No page context"}</p>
6061
</div>
6162
`;
6263
});
@@ -90,7 +91,7 @@ module.exports = function (eleventyConfig) {
9091
// construct a path relative to the site root
9192

9293
if (dir.includes("/tutorial") && link.startsWith("imgs/")) {
93-
return `/TypeAgent/tutorial/imgs/${link.substring(5)}`;
94+
return `/TypeAgent/content/tutorial/imgs/${link.substring(5)}`;
9495
}
9596

9697
if (dir.includes("/content")) {
@@ -112,41 +113,58 @@ module.exports = function (eleventyConfig) {
112113
.filter((item) => !item.filePathStem.includes("index"));
113114
});
114115

115-
// Import the link updating script
116-
const { updateLinks } = require('./scripts/update-links');
117-
118-
// Add a transform to update external links in markdown files
119-
eleventyConfig.addTransform("updateLinks", function(content, outputPath) {
120-
const repoUrl = process.env.GITHUB_REPOSITORY ?
121-
`https://github.com/${process.env.GITHUB_REPOSITORY}` :
122-
this.ctx?.site?.github || 'https://github.com/microsoft/TypeAgent';
123-
124-
const defaultBranch = process.env.GITHUB_DEFAULT_BRANCH || 'main';
125-
126-
if (outputPath && outputPath.endsWith(".html")) {
127-
// For HTML files, we don't need to update links - they were already processed
128-
// during markdown conversion
129-
return content;
130-
} else if (outputPath && outputPath.endsWith(".md")) {
131-
// For markdown files, update external links
132-
return updateLinks(content, outputPath, repoUrl, defaultBranch);
116+
// Store a map of input paths to output paths
117+
const pageMap = new Map();
118+
eleventyConfig.addTransform("recordPaths", function (content, outputPath) {
119+
const inputPath = this.inputPath;
120+
121+
if (inputPath && outputPath) {
122+
pageMap.set(outputPath, inputPath);
133123
}
124+
134125
return content;
135126
});
136-
127+
128+
const { updateLinks } = require("./scripts/update-links");
129+
130+
eleventyConfig.addTransform("updateLinks", function (content, outputPath) {
131+
if (!outputPath || !outputPath.endsWith(".html")) {
132+
return content; // Only process HTML files
133+
}
134+
135+
// Get the original input path for this file
136+
const inputPath = pageMap.get(outputPath) || this.inputPath;
137+
138+
if (!inputPath) {
139+
console.warn(
140+
`No input path found for ${outputPath}, skipping link transformation`
141+
);
142+
return content;
143+
}
144+
145+
const repoUrl = process.env.GITHUB_REPOSITORY
146+
? `https://github.com/${process.env.GITHUB_REPOSITORY}`
147+
: this.ctx?.site?.github || "https://github.com/microsoft/TypeAgent";
148+
149+
const defaultBranch = process.env.GITHUB_DEFAULT_BRANCH || "main";
150+
151+
console.log(`Transforming links in: ${outputPath} (from ${inputPath})`);
152+
return updateLinks(content, outputPath, inputPath, repoUrl, defaultBranch);
153+
});
154+
137155
// Add a filter for GitHub repository URLs
138-
eleventyConfig.addFilter("githubUrl", function(path, isDirectory = false) {
139-
const repoUrl = process.env.GITHUB_REPOSITORY ?
140-
`https://github.com/${process.env.GITHUB_REPOSITORY}` :
141-
this.ctx?.site?.github || 'https://github.com/microsoft/TypeAgent';
142-
143-
const defaultBranch = process.env.GITHUB_DEFAULT_BRANCH || 'main';
144-
145-
const normalizedPath = path.replace(/^\.\.\/|^\//g, '');
146-
147-
return isDirectory ?
148-
`${repoUrl}/tree/${defaultBranch}/${normalizedPath}` :
149-
`${repoUrl}/blob/${defaultBranch}/${normalizedPath}`;
156+
eleventyConfig.addFilter("githubUrl", function (path, isDirectory = false) {
157+
const repoUrl = process.env.GITHUB_REPOSITORY
158+
? `https://github.com/${process.env.GITHUB_REPOSITORY}`
159+
: this.ctx?.site?.github || "https://github.com/microsoft/TypeAgent";
160+
161+
const defaultBranch = process.env.GITHUB_DEFAULT_BRANCH || "main";
162+
163+
const normalizedPath = path.replace(/^\.\.\/|^\//g, "");
164+
165+
return isDirectory
166+
? `${repoUrl}/tree/${defaultBranch}/${normalizedPath}`
167+
: `${repoUrl}/blob/${defaultBranch}/${normalizedPath}`;
150168
});
151169

152170
return {

‎docs/_data/navigation.js‎

Lines changed: 19 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -9,45 +9,50 @@ module.exports = {
99
},
1010
{
1111
title: "Getting Started",
12-
url: "/setup/setup-Windows/",
12+
url: "/content/setup/setup-Windows/",
1313
children: [
1414
{
15-
title: "Windows",
16-
url: "/setup/setup-Windows/"
17-
},
18-
{
19-
title: "WSL",
20-
url: "/setup/setup-WSL2/"
15+
title: "Linux",
16+
url: "/content/setup/setup-Linux/"
2117
}
2218
,
2319
{
24-
title: "Linux",
25-
url: "/setup/setup-Linux/"
20+
title: "MacOS",
21+
url: "/content/setup/setup-MacOS/"
2622
}
2723
,
24+
25+
{
26+
title: "Windows",
27+
url: "/content/setup/setup-Windows/"
28+
},
29+
{
30+
title: "WSL",
31+
url: "/content/setup/setup-WSL2/"
32+
}
2833
]
2934
},
3035
{
3136
title: "Architecture",
32-
url: "/architecture/memory/",
37+
url: "/content/architecture/memory/",
3338
children: [
3439
{
3540
title: "Memory",
36-
url: "/architecture/memory/"
41+
url: "/content/architecture/memory/"
3742
},
3843
{
3944
title: "Dispatcher",
40-
url: "/architecture/dispatcher/"
45+
url: "/content/architecture/dispatcher/"
4146
}
4247
]
4348
},
4449
{
4550
title: "Tutorials",
46-
url: "/tutorial/agent/",
51+
url: "/content/tutorial/agent/",
4752
children: [
4853
{
4954
title: "Creating an Agent",
50-
url: "/tutorial/agent/"
55+
url: "/content/tutorial/agent/"
5156
}
5257
]
5358
}

docs/architecture/dispatcher.md renamed to docs/content/architecture/dispatcher.md

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -5,19 +5,19 @@ title: TypeAgent Dispatcher Architecture
55

66
## Overview
77

8-
[TypeAgent Dispatcher](../../ts/packages/dispatcher) is the core component used to build a **personal agent** implementation with _natural language interfaces_. The component's purpose is to understand user requests and translate it into actions using structured prompting and LLM and dispatch them to the appropriate TypeAgent to execute.
8+
[TypeAgent Dispatcher](../../../ts/packages/dispatcher) is the core component used to build a **personal agent** implementation with _natural language interfaces_. The component's purpose is to understand user requests and translate it into actions using structured prompting and LLM and dispatch them to the appropriate TypeAgent to execute.
99

1010
## Design Goals
1111

1212
Here are the design goals of the dispatcher:
1313

1414
- Dispatcher processes user requests and use LLM to translate them into actions based on schemas provided by application agents. It automatically finds and switches between different agents to provide a seamless experience in a extensible and scalable way. It aids the user to clarify and complete missing details needed to perform the actions.
15-
- Dispatcher component can be hosted by different client front ends. [TypeAgent Shell](../../ts/packages/shell) and [TypeAgent CLI](../../ts/packages/cli) are two example of clients built using dispatcher to show case the **personal agent** experience.
16-
- Dispatcher has extensible [application agents](../../ts/packages/agentSdk/README.md) architecture that allow new agents to be developed and plugin to the **personal agent** experience, scaling up to thousands and more actions.
17-
- Dispatcher leverage an [agent cache](../../ts/packages/cache/README.md) to lower cost and latency.
18-
- Dispatcher memorize conversation history by integrating with [KnowPro](../../ts/packages/knowPro) to store past memory and recall for future use.
15+
- Dispatcher component can be hosted by different client front ends. [TypeAgent Shell](../../../ts/packages/shell) and [TypeAgent CLI](../../../ts/packages/cli) are two example of clients built using dispatcher to show case the **personal agent** experience.
16+
- Dispatcher has extensible [application agents](../../../ts/packages/agentSdk/README.md) architecture that allow new agents to be developed and plugin to the **personal agent** experience, scaling up to thousands and more actions.
17+
- Dispatcher leverage an [agent cache](../../../ts/packages/cache/README.md) to lower cost and latency.
18+
- Dispatcher memorize conversation history by integrating with [KnowPro](../../../ts/packages/knowPro) to store past memory and recall for future use.
1919

20-
The current implementation of the [dispatcher](../../ts/packages/dispatcher) is a work in progress toward these goal and have explored most of the pieces described here.
20+
The current implementation of the [dispatcher](../../../ts/packages/dispatcher) is a work in progress toward these goal and have explored most of the pieces described here.
2121

2222
## Definitions
2323

docs/architecture/memory.md renamed to docs/content/architecture/memory.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,7 @@ Structured RAG is defined as the following steps:
2525

2626
Structured RAG can use simple language models to extract entities and topics.  This enables Structured RAG to index large conversations, like sets of meeting transcripts.  With fine tuning, simple models deliver indices with only a small loss of precision and recall relative to indices built with large language models.
2727

28-
The current Structured RAG implementation in the [KnowPro](../../ts/packages/knowPro/README.md) package uses secondary indices for scope expressions such as document range and time range.  The implementation also uses secondary indices for related terms, such as "novel" for "book".  During query, the memory system discovers related terms and caches them.  Models also offer related terms during information extraction.
28+
The current Structured RAG implementation in the [KnowPro](../../../ts/packages/knowPro/README.md) package uses secondary indices for scope expressions such as document range and time range.  The implementation also uses secondary indices for related terms, such as "novel" for "book".  During query, the memory system discovers related terms and caches them.  Models also offer related terms during information extraction.
2929

3030
Structured RAG has the following advantages over state-of-the-art memory using classic RAG:
3131

@@ -38,7 +38,7 @@ Structured RAG has the following advantages over state-of-the-art memory using c
3838

3939
## Implementations
4040

41-
- The [KnowPro](../../ts/packages//knowPro/README.md) package (in-development) contains the most recent implementation exploring the ideas of Structured RAG.
41+
- The [KnowPro](../../../ts/packages//knowPro/README.md) package (in-development) contains the most recent implementation exploring the ideas of Structured RAG.
4242

4343
## Demos
4444

docs/help/cheatSheet.html renamed to docs/content/help/cheatSheet.html

File renamed without changes.

docs/help/commandReference.md renamed to docs/content/help/commandReference.md

File renamed without changes.

docs/help/dev.md renamed to docs/content/help/dev.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,4 +9,4 @@ Here are some tips when working with the TypeAgent repo listed in no particular
99

1010
- When syncing with the [TypeAgent](/) repo it's always a good idea to run `pnpm i` first. This can help resolve some very common build issues or address updated dependency/references within the project hierarchy.
1111
- If there are issue during `pnpm i` or build, it's a good idea to try resetting the repo to a clean state. Make sure you save all your uncommitted changes (commit them or stash them) and use `git clean` to reset the repo, then try to install and build again.
12-
- There are two process models for agents: **in-proc** and **out-of-proc** with the [dispatcher](../../ts/packages/dispatcher/). It is recommended to run agents out of process from the dispatcher for system stability possible future isolation. However, this can on occasion make debugging more difficult. Therefore if you are chasing a troublesome issue, try running agents in process the same process as the dispatcher until the issue has been resolved by setting the environment variable `TYPEAGENT_EXECMODE=0`
12+
- There are two process models for agents: **in-proc** and **out-of-proc** with the [dispatcher](../../../ts/packages/dispatcher/). It is recommended to run agents out of process from the dispatcher for system stability possible future isolation. However, this can on occasion make debugging more difficult. Therefore if you are chasing a troublesome issue, try running agents in process the same process as the dispatcher until the issue has been resolved by setting the environment variable `TYPEAGENT_EXECMODE=0`

docs/help/faq.md renamed to docs/content/help/faq.md

File renamed without changes.

docs/setup/setup-Linux.md renamed to docs/content/setup/setup-Linux.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,7 @@ Instructions tested with Ubuntu 24.04.1 LTS and Debian 12.8.0
2929

3030
## Configure Services
3131

32-
- Setup Service Keys (See instructions [here](../../ts/README.md#service-keys))
32+
- Setup Service Keys (See instructions [here](../../../ts/README.md#service-keys))
3333

3434
## Run
3535

docs/setup/setup-WSL2.md renamed to docs/content/setup/setup-WSL2.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,7 @@ This is a list of step-by-step instructions to set up a WSL2 environment from _s
2626

2727
## Configure Services
2828

29-
- Setup Service Keys (See instructions [here](../../ts/README.md#service-keys))
29+
- Setup Service Keys (See instructions [here](../../../ts/README.md#service-keys))
3030

3131
## Run
3232

0 commit comments

Comments
 (0)