@mehdad67/apitogo 0.1.24

package/docs/guides/transforming-examples.md

@@ -0,0 +1,156 @@
+---
+title: Transforming Operation Examples
+sidebar_icon: git-compare-arrows
+---
+
+APIToGo allows you to transform operation examples in both request and response sections of your API
+documentation. This feature is particularly useful when you need to:
+
+- Modify example data before displaying it
+- Add dynamic values to examples
+- Format examples in a specific way
+- Filter or transform example content based on certain conditions
+
+## Configuration
+
+To use this feature, you need to configure the `transformExamples` function in your
+`apitogo.config.tsx` file. Here's how to do it:
+
+```tsx
+import type { ApitogoConfig } from "@lukoweb/apitogo";
+
+const config: ApitogoConfig = {
+  // ... other config options ...
+  defaults: {
+    apis: {
+      transformExamples: (options) => {
+        // Transform the content here
+        return options.content;
+      },
+    },
+  },
+};
+```
+
+## The Transform Function
+
+The `transformExamples` function receives an options object with the following properties:
+
+1. `content`: An array of Content objects containing the example data
+1. `operation`: The operation being displayed
+1. `type`: Either "request" or "response" indicating which type of example is being transformed
+1. `auth`: The current authentication state
+1. `context`: `ApitogoContext` (runtime context from `@lukoweb/apitogo`)
+
+The function should return an array of Content objects with the transformed examples.
+
+## Example Usage
+
+Here's a practical example showing how to transform examples:
+
+```tsx
+const config: ApitogoConfig = {
+  defaults: {
+    apis: {
+      transformExamples: ({ content, type }) => {
+        // Example: Add a timestamp to all examples
+        const timestamp = new Date().toISOString();
+
+        return content.map((contentItem) => ({
+          ...contentItem,
+          example: {
+            ...contentItem.example,
+            timestamp,
+            // You can modify other example properties here
+          },
+        }));
+      },
+    },
+  },
+};
+```
+
+## Use Cases
+
+### Adding Dynamic Values
+
+```tsx
+transformExamples: ({ content, auth }) => {
+  const apiKey = auth.accessToken;
+
+  return content.map((contentItem) => ({
+    ...contentItem,
+    example: {
+      ...contentItem.example,
+      headers: {
+        ...contentItem.example.headers,
+        Authorization: `Bearer ${apiKey}`,
+      },
+    },
+  }));
+};
+```
+
+### Formatting Examples
+
+```tsx
+transformExamples: ({ content }) => {
+  return content.map((contentItem) => ({
+    ...contentItem,
+    example: {
+      ...contentItem.example,
+      // Format dates in a specific way
+      createdAt: new Date(contentItem.example.createdAt).toLocaleDateString(),
+      // Format numbers with specific precision
+      amount: Number(contentItem.example.amount).toFixed(2),
+    },
+  }));
+};
+```
+
+### Conditional Transformation
+
+```tsx
+transformExamples: ({ content, auth, type }) => {
+  const isAuthenticated = auth.isAuthenticated;
+
+  return content.map((contentItem) => ({
+    ...contentItem,
+    example: isAuthenticated
+      ? contentItem.example // Show full example for authenticated users
+      : { ...contentItem.example, sensitiveData: undefined }, // Hide sensitive data for unauthenticated users
+  }));
+};
+```
+
+### Using JWT Claims
+
+```tsx
+transformExamples: async ({ content, auth, context }) => {
+  const token = await context.authentication.getAccessToken();
+
+  // Decode the JWT (this is a simple example - in production you might want to use a proper JWT library)
+  const [, payload] = token.split(".");
+  const decodedPayload = JSON.parse(atob(payload));
+
+  return content.map((contentItem) => ({
+    ...contentItem,
+    example: {
+      ...contentItem.example,
+      // Add user-specific data from the JWT
+      userId: decodedPayload.sub,
+      organizationId: decodedPayload.org_id,
+      // You can add any other claims from the JWT
+      role: decodedPayload.role,
+    },
+  }));
+};
+```
+
+## Best Practices
+
+1. Always return an array of Content objects, even if you're not transforming the content
+2. Preserve the original content structure while making your modifications
+3. Handle errors gracefully to prevent breaking the documentation
+4. Consider performance implications when transforming large examples
+5. Use the provided options object to access relevant information for your transformations

package/docs/guides/using-multiple-apis.md

@@ -0,0 +1,87 @@
+---
+title: Multiple APIs
+sidebar_icon: file-stack
+---
+
+APIToGo supports creating documentation and API references for multiple APIs and can work with as
+many OpenAPI documents as you need.
+
+In order to do this you will need to modify the
+[APIToGo Configuration](../configuration/overview.md) file to include additional APIs.
+
+## Configuration
+
+Using multiple APIs is a configuration setting that you can add in the
+[APIToGo Configuration](../configuration/overview.md) file.
+
+### Step 1: Add your APIs
+
+First, create a new array in your configuration file that lists each API you want to include:
+
+```typescript
+const apis = [
+  {
+    type: "file",
+    input: "apis/my-first-api.json",
+    path: "/my-first-api",
+  },
+  {
+    type: "file",
+    input: "apis/my-second-api.json",
+    path: "/my-second-api",
+  },
+] as const;
+```
+
+### Step 2: Add navigation
+
+Create a navigation array for your sidebar:
+
+```typescript
+const navigation = [
+  {
+    type: "link",
+    label: "My First API",
+    to: "/my-first-api",
+  },
+  {
+    type: "link",
+    label: "My Second API",
+    to: "/my-second-api",
+  },
+] as const;
+```
+
+### Step 3: Update your config
+
+Modify your [APIToGo Configuration](../configuration/overview.md) file to include these arrays:
+
+```typescript
+import type { ApitogoConfig } from "@lukoweb/apitogo";
+
+const config: ApitogoConfig = {
+  navigation: [
+    {
+      type: "category",
+      label: "Overview",
+      items: navigation,
+    },
+  ],
+  redirects: [{ from: "/", to: "/overview" }],
+  apis,
+  docs: {
+    files: "/pages/**/*.{md,mdx}",
+  },
+};
+
+export default config;
+```
+
+Make sure that:
+
+1. The `path` in each API config matches the `href` in the navigation
+2. Your OpenAPI files are placed in the correct location as specified in the `input` field
+3. The `label` in navigation matches what you want to display in the sidebar
+
+You don't necessarily need to add the APIs to your sidebar, you can also put them into the top
+navigation or link to them from your docs.

package/docs/markdown/admonitions.md

@@ -0,0 +1,128 @@
+---
+title: Admonitions
+sidebar_icon: rectangle-horizontal
+description:
+  Learn how to use admonitions (callouts) in Markdown, including syntax, types, titles, and
+  formatting tips for compatibility with Prettier.
+---
+
+In addition to the basic Markdown syntax, we have a special admonitions syntax by wrapping text with
+a set of 3 colons, followed by a label denoting its type.
+
+:::note
+
+Admonitions are also commonly referred to as "Callouts". For programmatic usage, see the
+[Callout component](/docs/components/callout).
+
+:::
+
+Example:
+
+```markdown
+:::note
+
+Some **content** with _Markdown_ `syntax`. Check [this `api`](#).
+
+:::
+
+:::tip
+
+Some **content** with _Markdown_ `syntax`. Check [this `api`](#).
+
+:::
+
+:::info
+
+Some **content** with _Markdown_ `syntax`. Check [this `api`](#).
+
+:::
+
+:::warning
+
+Some **content** with _Markdown_ `syntax`. Check [this `api`](#).
+
+:::
+
+:::danger
+
+Some **content** with _Markdown_ `syntax`. Check [this `api`](#).
+
+:::
+```
+
+:::note
+
+Some **content** with _Markdown_ `syntax`. Check [this `api`](#).
+
+:::
+
+:::tip
+
+Some **content** with _Markdown_ `syntax`. Check [this `api`](#).
+
+:::
+
+:::info
+
+Some **content** with _Markdown_ `syntax`. Check [this `api`](#).
+
+:::
+
+:::warning
+
+Some **content** with _Markdown_ `syntax`. Check [this `api`](#).
+
+:::
+
+:::danger
+
+Some **content** with _Markdown_ `syntax`. Check [this `api`](#).
+
+:::
+
+## With title
+
+You can also add a title to the admonition by adding it after the type:
+
+```markdown
+:::warning{title="Warning of the day"}
+
+The path of the righteous man is beset on all sides by the iniquities of the selfish and the tyranny
+of evil men.
+
+:::
+```
+
+:::warning{title="Warning of the day"}
+
+The path of the righteous man is beset on all sides by the iniquities of the selfish and the tyranny
+of evil men.
+
+:::
+
+## Usage with Prettier
+
+If you use Prettier to format your Markdown files, Prettier might auto-format your code to invalid
+admonition syntax. To avoid this problem, add empty lines around the starting and ending directives.
+This is also why the examples we show here all have empty lines around the content.
+
+<!-- prettier-ignore -->
+```markdown
+<!-- Prettier doesn't change this -->
+
+:::note
+
+Hello world
+
+:::
+
+<!-- Prettier changes this -->
+
+:::note 
+Hello world 
+:::
+
+<!-- to this -->
+
+::: note Hello world:::
+```

package/docs/markdown/code-blocks.md

@@ -0,0 +1,196 @@
+---
+title: Code Blocks
+sidebar_icon: braces
+description:
+  Learn how to use code blocks, syntax highlighting, and advanced features like line highlighting
+  and ANSI output in APIToGo Markdown with Shiki.
+---
+
+APIToGo supports code blocks in Markdown using the [Shiki](https://shiki.style/) syntax highlighting
+library.
+
+See examples for all supported languages in the
+[Syntax Highlighting](../components/syntax-highlight#supported-languages) section.
+
+## Syntax Highlighting
+
+Code blocks are text blocks wrapped around by strings of 3 backticks. You may check out this
+reference for the specifications of MDX.
+
+````md
+```js
+console.log("Every repo must come with a mascot.");
+```
+````
+
+The code block above will render as:
+
+```js
+console.log("Every repo must come with a mascot.");
+```
+
+:::note
+
+You can also use the [`SyntaxHighlight` component](../components/syntax-highlight) to render code
+blocks in TypeScript directly.
+
+:::
+
+## Inline Code
+
+You can highlight inline code using either:
+
+Regular backticks without language specification:
+
+```md
+`console.log("Hello World")`
+```
+
+Result: `console.log("Hello World")`
+
+or with the [tailing curly colon syntax](https://shiki.matsu.io/packages/rehype#inline-code):
+
+```md
+`console.log("Hello World"){:js}`
+```
+
+Result: `console.log("Hello World"){:js}`
+
+For more details, see the
+[Shiki Rehype documentation](https://shiki.style/packages/rehype#inline-code).
+
+You can add a title to code blocks by adding a title attribute after the backticks:
+
+````md
+```tsx title="hello.tsx"
+console.log("Hello, World!");
+```
+````
+
+Result:
+
+```tsx title="hello.tsx"
+console.log("Hello, World!");
+```
+
+For a complete list of supported languages and their aliases, see the
+[Shiki Languages documentation](https://shiki.style/languages#bundled-languages).
+
+## Advanced Syntax Highlighting
+
+There are multiple ways to enhance syntax highlighting:
+
+- [Line highlighting](https://shiki.style/packages/transformers#transformermetahighlight)
+- [Word highlighting](https://shiki.style/packages/transformers#transformermetawordhighlight)
+- Line numbers: `showLineNumbers`
+- Title: `title`
+
+Example:
+
+````
+```tsx {4-6} /react/ title="Example.tsx" showLineNumbers
+import { useEffect } from "react";
+
+function Example() {
+  useEffect(() => {
+    console.log("Mounted");
+  }, []);
+
+  return <div>Hello</div>;
+}
+```
+````
+
+Result:
+
+```tsx {4-6} /react/ title="Example.tsx" showLineNumbers
+import { useEffect } from "react";
+
+function Example() {
+  useEffect(() => {
+    console.log("Mounted");
+  }, []);
+
+  return <div>Hello</div>;
+}
+```
+
+## Configuration
+
+You can configure syntax highlighting in your `apitogo.config.tsx`:
+
+:::info
+
+Changes to the syntax `highlighting` configuration require a restart of APIToGo to take effect.
+
+:::
+
+```tsx {5-15} title=apitogo.config.ts
+import { defaultLanguages, type ApitogoConfig } from "@lukoweb/apitogo";
+
+const config: ApitogoConfig = {
+  // ...
+  syntaxHighlighting: {
+    themes: {
+      light: "vitesse-light",
+      dark: "vitesse-dark",
+    },
+    // Extend default languages with additional ones
+    // Aliases like "lisp" are resolved automatically
+    languages: [...defaultLanguages, "rust", "ruby", "php", "powershell"],
+  },
+};
+```
+
+For a complete list of available themes and languages, see the list of
+[Shiki themes](https://shiki.style/themes) and [Shiki languages](https://shiki.style/languages).
+
+## Default Supported Languages
+
+By default, APIToGo supports the following languages for syntax highlighting:
+
+- Shell - `shellscript`, `bash`, `sh`, `zsh`
+- JavaScript/TypeScript - `javascript`, `typescript`, `jsx`, `tsx`
+- Data formats - `json`, `jsonc`, `yaml`
+- HTML/CSS/XML - `html`, `css`, `xml`
+- Markdown - `markdown`, `mdx`
+- Python - `python`
+- Java - `java`
+- Go - `go`
+- GraphQL - `graphql`
+
+Additional languages can be added via `syntaxHighlighting.languages` in your config. Languages not
+in the list fall back to plain text with a console warning. You can use aliases (e.g. `lisp` for
+`common-lisp`) and they will resolve automatically.
+
+## ANSI Code Blocks
+
+You can use the `ansi` language to highlight terminal outputs with ANSI escape sequences. This is
+useful for displaying colored terminal output, styled text, and other terminal-specific formatting.
+
+```ansi title="Terminal Output"
+colored foreground
+bold text
+dimmed text
+underlined text
+reversed text
+strikethrough text
+underlined + strikethrough text
+```
+
+Usage:
+
+````md
+```ansi title="Terminal Output"
+colored foreground
+bold text
+dimmed text
+underlined text
+reversed text
+strikethrough text
+underlined + strikethrough text
+```
+````
+
+For more details on ANSI highlighting, see the
+[Shiki documentation](https://shiki.style/languages#ansi).