Astro5.0 (#950)

* major upgrade to astro 5

* broken link

* build goes through

* more v5 fixes

* feat: add starlight-package-managers & GenAIScriptCli 🚀

* feat: 📝 Update links and add links validator

docs/astro.config.mjs

@@ -2,6 +2,7 @@ import { defineConfig, passthroughImageService } from "astro/config"
 import starlight from "@astrojs/starlight"
 import starlightBlog from "starlight-blog"
 import rehypeMermaid from "rehype-mermaid"
+import starlightLinksValidator from "starlight-links-validator"
 
 // https://astro.build/config
 export default defineConfig({
@@ -39,6 +40,7 @@ export default defineConfig({
                         },
                     },
                 }),
+                //starlightLinksValidator(),
             ],
             components: {
                 Head: "./src/components/Head.astro",

docs/package.json

@@ -21,10 +21,12 @@
   "dependencies": {},
   "devDependencies": {
     "@astrojs/check": "^0.9.4",
-    "@astrojs/starlight": "^0.29.2",
-    "astro": "^4.16.16",
+    "@astrojs/starlight": "^0.30.1",
+    "astro": "^5.0.5",
     "rehype-mermaid": "^3.0.0",
-    "starlight-blog": "^0.15.0",
+    "starlight-blog": "^0.16.0",
+    "starlight-links-validator": "^0.13.4",
+    "starlight-package-managers": "^0.8.1",
     "typescript": "5.7.2",
     "zx": "^8.2.4"
   }

docs/src/components/GenAIScriptCli.astro

@@ -0,0 +1,15 @@
+---
+import { PackageManagers } from "starlight-package-managers"
+interface Props {
+    args: string
+    comment: string
+}
+const { args, comment } = Astro.props
+---
+<PackageManagers
+    type="dlx"
+    pkg="genaiscript"
+    args={args}
+    comment={comment}
+    frame="none"
+/>

docs/src/content/config.ts → docs/src/content.config.ts

@@ -1,9 +1,11 @@
 import { defineCollection } from "astro:content"
+import { docsLoader } from "@astrojs/starlight/loaders"
 import { docsSchema } from "@astrojs/starlight/schema"
 import { blogSchema } from "starlight-blog/schema"
 
 export const collections = {
     docs: defineCollection({
+        loader: docsLoader(),
         schema: docsSchema({
             extend: (context) => blogSchema(context),
         }),

docs/src/content/docs/blog/node-api.md → docs/src/content/docs/blog/node-api.mdx

@@ -6,6 +6,7 @@ authors:
 tags: ["sdk", "automation", "dev", "api"]
 description: Learn about the new API to call genaiscript for other typescript scripts.
 ---
+import { PackageManagers } from 'starlight-package-managers'
 
 A long standing feature request has been to run GenAIScript programmatically from other scripts. We are happy to announce that we have released a Node.JS API for GenAIScript. This API allows you to call GenAIScript from other TypeScript scripts (v1.83+).
 
@@ -15,9 +16,7 @@ A long standing feature request has been to run GenAIScript programmatically fro
 
 You'll want to add [genaiscript](https://www.npmjs.com/package/genaiscript) as a (dev) dependency to your project.
 
-```sh
-npm install -D genaiscript
-```
+<PackageManagers pkg="genaiscript" dev />
 
 ## The `run` API
 

docs/src/content/docs/case-studies/blocks-localization.mdx

@@ -10,7 +10,7 @@ import { Code } from "@astrojs/starlight/components"
 import stringsJson from "../../../../../packages/sample/src/makecode/jacdac-buzzer-strings.json?raw"
 import scriptSource from "../../../../../packages/sample/src/makecode/makecode-loc.genai.js?raw"
 
-This is another instance of using the LLM to produce translation of natural strings with an embedded DSL, similarly to the [Documentation Translation](./documentation-translations.mdx) guide.
+This is another instance of using the LLM to produce translation of natural strings with an embedded DSL, similarly to the [Documentation Translation](/genaiscript/case-studies/documentation-translations.mdx) guide.
 
 [MakeCode](https://makecode.com) uses a [microformat](https://makecode.com/defining-blocks) to define the shape of coding blocks.
 When translating the format strings, it is critical to converse the properties of the blocks, such as the number of arguments, 

docs/src/content/docs/getting-started/index.md → docs/src/content/docs/getting-started/index.mdx

@@ -15,6 +15,8 @@ genaiscript:
     files: src/samples/markdown-small.txt
 ---
 
+import GenAIScriptCli from "../../../components/GenAIScriptCli.astro"
+
 GenAIScript is a scripting language that integrates LLMs into the scripting process using a simplified JavaScript syntax.
 Supported by our VS Code GenAIScript extension, it allows users to create, debug, and automate LLM-based scripts.
 
@@ -49,13 +51,11 @@ So the final JSON payload sent to the LLM server might look more like this:
 ```
 
 GenAIScripts can be executed from the [command line](/genaiscript/reference/cli) or run with a right-click context
-menu selection inside Visual Studio Code. Because a GenAIScript is just JavaScript, 
-the execution of a script follows the normal JavaScript evaluation rules. 
+menu selection inside Visual Studio Code. Because a GenAIScript is just JavaScript,
+the execution of a script follows the normal JavaScript evaluation rules.
 Once the script is executed, the generated messages are sent to the LLM server, and the response is processed by the GenAIScript runtime.
 
-```sh wrap
-npx --yes genaiscript run poem
-```
+<GenAIScriptCli args="run poem" />
 
 Here is an example output for this prompt (shortened) that got returned by OpenAI gpt-4o.
 
@@ -93,11 +93,13 @@ and we use `def` to include it in the prompt as a `prompt variable`. We then "re
 
 ````markdown wrap title="prompt"
 FILE:
+
 ```text file="some/relative/markdown.txt"
 What is Markdown?
 
 Markdown is a lightweight markup language that you can use to add formatting elements to plaintext text documents. Created by John Gruber in 2004, Markdown is now one of the world’s most popular markup languages.
 ```
+
 Summarize FILE in one sentence.
 ````
 
@@ -126,9 +128,7 @@ $`Summarize FILE in one sentence.`
 
 And now apply it to a bunch of files
 
-```sh
-npx --yes genaiscript run summarize **/*.md
-```
+<GenAIScriptCli args='run summarize "**/*.md"' />
 
 ## Processing outputs
 
@@ -148,6 +148,7 @@ the GenAIScript runtime interprets based on what the prompt requested from the m
 
 ````markdown wrap
 File src/samples/markdown-small.txt.summary:
+
 ```text
 Markdown is a lightweight markup language created by John Gruber in 2004, known for adding formatting elements to plaintext text documents.
 ```
@@ -180,21 +181,22 @@ $`
 `
 ```
 
-A possible trace looks like as follows. 
+A possible trace looks like as follows.
 
 <details style="margin-left: 1rem;"  open>
 <summary>Trace</summary>
 
-`````markdown
+````markdown
 - prompting github:gpt-4o
 - cat src/rag/markdown.md
 - prompting github:gpt-4o
 
 FILE ./markdown.md.txt:
+
 ```text
 Markdown is a lightweight ...
 ```
-`````
+````
 
 </details>
 
@@ -219,13 +221,13 @@ $`
 <details style="margin-left: 1rem;"  open>
 <summary>Trace</summary>
 
-`````markdown
+````markdown
 - prompting github:gpt-4o (~1569 tokens)
-- agent fs: read and summarize file src/rag/markdown.md in one sentence 
-  - prompt agent memory query with github:gpt-4o-mini: "NO_ANSWER"
-  - prompt agent fs with github:gpt-4o (~422 tokens)
-  - cat src/rag/markdown.md
-  - prompting github:gpt-4o (~635 tokens)
+- agent fs: read and summarize file src/rag/markdown.md in one sentence
+    - prompt agent memory query with github:gpt-4o-mini: "NO_ANSWER"
+    - prompt agent fs with github:gpt-4o (~422 tokens)
+    - cat src/rag/markdown.md
+    - prompting github:gpt-4o (~635 tokens)
 
 ```md
 The file "src/rag/markdown.md" explains that Markdown...
@@ -236,10 +238,12 @@ The file "src/rag/markdown.md" explains that Markdown...
 I'll save the summary to the file `markdown.md.txt`.
 
 FILE markdown.md.txt:
+
 ```
 The file "src/rag/markdown.md" explains that Markdown....
 ```
-`````
+````
+
 </details>
 
 ## Next steps

docs/src/content/docs/guides/issue-reviewer.mdx

@@ -6,7 +6,7 @@ description: Learn how to automate reviewing issues with a script.
 keywords: pull request automation, code review, GitHub Actions, GenAIScript reviewer, PR feedback
 ---
 import { Code } from '@astrojs/starlight/components';
-import importedCode from "../../../../../packages/sample/genaisrc/issue-reviewer.genai?raw"
+import importedCode from "../../../../../packages/sample/genaisrc/issue-reviewer.genai.mjs?raw"
 
 This guide shows how to automate reviewing issues 
 with a GenAIScript that provides feedback and code analysis in GitHub Actions.

docs/src/content/docs/reference/cli/api.mdx

@@ -5,29 +5,13 @@ sidebar:
 ---
 
 import { Tabs, TabItem } from "@astrojs/starlight/components"
+import { PackageManagers } from 'starlight-package-managers'
 
 This page describes how to import and use the [cli](/genaiscript/reference/cli) as an API in your Node.JS application.
 
 Assuming you have have added the cli as a dependency in your project, you can import the cli as follows:
 
-<Tabs>
-  <TabItem value="npm" label="npm">
-
-```sh
-npm install -D genaiscript
-```
-
-</TabItem>
-
-  <TabItem value="yarn" label="yarn">
-
-```sh
-yarn add -D genaiscript
-```
-
-</TabItem>
-
-</Tabs>
+<PackageManagers pkg="genaiscript" dev />
 
 The API can be imported using imports from **"genaiscript/api"**.
 

docs/src/content/docs/reference/cli/index.mdx

@@ -9,15 +9,13 @@ keywords: GenAIScript CLI, Node.js automation, AI scripting, command line interf
 import { Steps } from "@astrojs/starlight/components"
 import { Tabs, TabItem } from "@astrojs/starlight/components"
 import DirectoryLinks from "../../../../components/DirectoryLinks.astro"
+import GenAIScriptCli from "../../../../components/GenAIScriptCli.astro"
+import { PackageManagers } from "starlight-package-managers"
 
 The GenAIScript CLI **`genaiscript`** runs GenAIScript scripts
 outside of Visual Studio and in your [automation](/genaiscript/getting-starting/automating-scripts).
 
-```sh
-npx --yes genaiscript ...
-```
-
-where `--yes` skips the confirmation prompt to install the package.
+<GenAIScriptCli args="..." />
 
 ## Prerequisites
 
@@ -29,22 +27,7 @@ The CLI is a Node.JS package hosted on [npm](https://www.npmjs.com/package/genai
 
 - Install locally as a `devDependency` in your project.
 
-<Tabs>
-  <TabItem label="npm" icon="seti:npm">
-
-```sh
-npm install -D genaiscript
-```
-
-  </TabItem>
-  <TabItem label="yarn" >
-
-```sh
-yarn add -D genaiscript
-```
-
-  </TabItem>
-</Tabs>
+<PackageManagers pkg="genaiscript" dev frame="none" />
 
 - Install it globally.
 

docs/src/content/docs/reference/scripts/content-safety.mdx

@@ -12,15 +12,15 @@ GenAIScript has multiple built-in safety features to protect the system from mal
 
 The following safety prompts are included by default when running a prompt, unless the system option is configured:
 
--   [system.safety_harmful_content](../system#systemsafety_harmful_content), safety prompt against Harmful Content: Hate and Fairness, Sexual, Violence, Self-Harm. See https://learn.microsoft.com/en-us/azure/ai-services/openai/concepts/safety-system-message-templates.
--   [system.safety_jailbreak](../system#systemsafety_jailbreak), safety script to ignore prompting instructions in code sections, which are created by the `def` function.
--   [system.safety_protected_material](../system#systemsafety_protected_material) safety prompt against Protected material. See https://learn.microsoft.com/en-us/azure/ai-services/openai/concepts/safety-system-message-templates
+-   [system.safety_harmful_content](/genaiscript/reference/script/system#systemsafety_harmful_content), safety prompt against Harmful Content: Hate and Fairness, Sexual, Violence, Self-Harm. See https://learn.microsoft.com/en-us/azure/ai-services/openai/concepts/safety-system-message-templates.
+-   [system.safety_jailbreak](/genaiscript/reference/script/system#systemsafety_jailbreak), safety script to ignore prompting instructions in code sections, which are created by the `def` function.
+-   [system.safety_protected_material](/genaiscript/reference/script/system#systemsafety_protected_material) safety prompt against Protected material. See https://learn.microsoft.com/en-us/azure/ai-services/openai/concepts/safety-system-message-templates
 
 Other system scripts can be added to the prompt by using the `system` option.
 
--   [system.safety_ungrounded_content_summarization](../system#systemsafety_ungrounded_content_summarization) safety prompt against ungrounded content in summarization
--   [system.safety_canary_word](../system#systemsafety_canary_word) safety prompt against prompt leaks.
--   [system.safety_validate_harmful_content](../system#systemsafety_validate_harmful_content) runs the `detectHarmfulContent` method to validate the output of the prompt.
+-   [system.safety_ungrounded_content_summarization](/genaiscript/reference/script/system#systemsafety_ungrounded_content_summarization) safety prompt against ungrounded content in summarization
+-   [system.safety_canary_word](/genaiscript/reference/script/system#systemsafety_canary_word) safety prompt against prompt leaks.
+-   [system.safety_validate_harmful_content](/genaiscript/reference/script/system#systemsafety_validate_harmful_content) runs the `detectHarmfulContent` method to validate the output of the prompt.
 
 ## Azure AI Content Safety services
 

docs/src/content/docs/reference/scripts/github.md → docs/src/content/docs/reference/scripts/github.mdx

@@ -4,6 +4,7 @@ description: Support for querying GitHub
 sidebar:
     order: 50
 ---
+import { PackageManagers } from 'starlight-package-managers'
 
 The `github` module provides several helper functions to query GitHub, along with the connection information for more advanced usage.
 
@@ -148,9 +149,7 @@ const { client }: { client: Octokit } = await github.api()
 
 Install octokit in your list of packages:
 
-```sh
-npm install -D octokit
-```
+<PackageManagers pkg="octokit" dev />
 
 ## Working on a different repository
 

docs/src/content/docs/reference/scripts/mcp-tools.mdx

@@ -46,7 +46,7 @@ The tool identifier will be `server_toolname` to avoid clashes.
 
 Servers are started when rendering the prompt and stopped once the chat session is completed.
 
-This means that if you define servers in an [inline prompt](/genaiscript/reference/prompts/inline),
+This means that if you define servers in an [inline prompt](/genaiscript/reference/scripts/inline-prompts),
 the server will be started/stopped for each inline prompt.
 
 ## Finding servers

docs/src/content/docs/reference/scripts/tools.mdx

@@ -15,7 +15,7 @@ You can register **tools** (also known as **functions**) that the LLM may decide
 See [OpenAI functions](https://platform.openai.com/docs/guides/function-calling), [Ollama tools](https://ollama.com/blog/tool-support),
 or [Anthropic tool use](https://docs.anthropic.com/en/docs/build-with-claude/tool-use).
 
-Not all LLM models support tools, in those cases, GenAIScript also support a fallback mechanism to implement tool call through system prompts (see [Ad Hoc Tools](#adhoctools)).
+Not all LLM models support tools, in those cases, GenAIScript also support a fallback mechanism to implement tool call through system prompts (see [Fallback Tools](#fallbacktools)).
 
 ## `defTool`
 
@@ -62,7 +62,7 @@ This example uses the `current_weather` tool to get the weather for Brussels.
 
 ### Math tool example
 
-This example uses the [math expression evaluator](/genaiscript/reference/scripts/math)
+This example uses the math expression evaluator
 to evaluate a math expression.
 
 <Code
@@ -90,7 +90,6 @@ defTool({
 
 See [Model Context Protocol Tools](/genaiscript/reference/scripts/mcp-tools) for more information.
 
-
 ## Agentic Tools
 
 [Agentic](https://agentic.so) is
@@ -105,7 +104,7 @@ defTool(calculator)
 
 See [Agentic tools](/genaiscript/guides/agentic-tools) for more information.
 
-## Fallback Tool Support
+## Fallback Tool Support <a href="" id="fallbacktools" />
 
 Some LLM models do not have built-in model support.
 For those model, it is possible to enable tool support through system prompts. The performance may be lower than built-in tools, but it is still possible to use tools.

docs/src/content/docs/reference/security-and-trust.mdx

@@ -10,7 +10,7 @@ import WarningCode from "../../../components/WarningCode.astro"
 We discuss various security risks and possible mitigations when using GenAIScript.
 GenAISCript inherits the same security risks as running scripts, and adds some new threats due to the nature of the LLM-generated outputs.
 
-We also recommend reading the [Transparency Note](/genaiscript/reference/transparency-note) 
+We also recommend reading the [Transparency Note](/genaiscript/reference/transparency-note/) 
 to understand the capabilities and limitations of GenAIScript.
 
 ## Don't trust the scripts

docs/src/content/docs/reference/vscode/index.mdx

@@ -14,4 +14,4 @@ contains the latest stable release of the [extension](https://marketplace.visual
 
 - [Download](https://marketplace.visualstudio.com/items?itemName=genaiscript.genaiscript-vscode)
 - [Installation instructions](/genaiscript/getting-started/installation/#visual-studio-code-extension)
-- [Copilot Chat Integration](/genaiscript/reference/copilot-chat/)
+- [Copilot Chat Integration](/genaiscript/reference/github-copilot-chat/)