@mehdad67/apitogo 0.1.24

package/docs/markdown/frontmatter.md

@@ -0,0 +1,173 @@
+---
+sidebar_icon: scissors-line-dashed
+title: Frontmatter
+description:
+  Learn how to use YAML frontmatter in APIToGo markdown files to customize page titles,
+  descriptions, navigation, and other document properties.
+---
+
+Frontmatter is metadata written in [YAML](https://yaml.org/) format at the beginning of markdown
+files, enclosed between triple dashes (`---`). It allows you to configure various aspects of your
+pages without affecting the visible content.
+
+In APIToGo, frontmatter enables you to customize page titles, descriptions, navigation settings, and
+other document properties. Here are all the supported properties:
+
+## Properties
+
+### `title`
+
+Sets the page title that appears in the browser tab and as the document title.
+
+```md
+---
+title: My Page Title
+---
+```
+
+### `description`
+
+Provides a description for the page, which can be used for SEO and content summaries.
+
+```md
+---
+description: This page explains how to use APIToGo's markdown features.
+---
+```
+
+### `category`
+
+Assigns the page to a specific category for organizational purposes. This will be shown above the
+main heading of the document.
+
+```md
+---
+category: Getting Started
+---
+```
+
+### `navigation_label`
+
+_Deprecated (`sidebar_label`)_
+
+Sets a custom label for the page in the sidebar navigation, allowing you to use a shorter or
+different title than the main page title.
+
+```md
+---
+title: My Very Long Documentation Page Title
+navigation_label: Short Title
+---
+```
+
+### `navigation_icon`
+
+_Deprecated (`sidebar_icon`)_
+
+Specifies a [Lucide icon](https://lucide.dev/icons) to display next to the page in the sidebar
+navigation.
+
+```md
+---
+navigation_icon: compass
+---
+```
+
+### `navigation_display`
+
+Specifies the display property of the navigation item. See the
+[Navigation guide](/docs/configuration/navigation#display-control)
+
+```md
+---
+navigation_display: auth
+---
+```
+
+### `toc`
+
+Controls whether the table of contents is displayed for the page. Set to `false` to hide the table
+of contents.
+
+```md
+---
+toc: false
+---
+```
+
+### `disable_pager`
+
+Controls whether the previous/next page navigation is displayed at the bottom of the page. Set to
+`true` to disable it.
+
+```md
+---
+disable_pager: true
+---
+```
+
+### `draft`
+
+Marks a document as a draft. Draft documents are only visible when running in development mode and
+are excluded from production builds. This is useful for working on content that isn't ready to be
+published.
+
+```md
+---
+draft: true
+---
+```
+
+:::info
+
+When `draft: true` is set:
+
+- The document will be visible when running `apitogo dev`
+- The document will be excluded from builds created with `apitogo build`
+- The document won't appear in the navigation or be accessible via URL in production
+
+:::
+
+### `lastModifiedTime`
+
+The last modified timestamp for the page. This property is automatically set by APIToGo during the
+build process based on the Git commit history. You generally should not set this manually.
+
+If you need to override the automatically detected date, you can set it explicitly:
+
+```md
+---
+lastModifiedTime: 2025-11-20T10:30:00.000Z
+---
+```
+
+::if{mode=opensource}
+
+:::info
+
+For accurate last modified dates in deployment environments, ensure full Git history is available
+during builds. See the [Vercel deployment guide](/docs/deploy/vercel#accurate-last-modified-dates)
+for configuration details.
+
+:::
+
+::
+
+## Complete Example
+
+Here's an example showing multiple frontmatter properties used together:
+
+```md title=documentation.md
+---
+title: Advanced Configuration Guide
+description: Learn how to configure advanced features in APIToGo
+category: Configuration
+navigation_label: Advanced Config
+navigation_icon: settings
+toc: true
+disable_pager: false
+draft: false
+---
+
+This page content follows the frontmatter...
+```

package/docs/markdown/mdx.md

@@ -0,0 +1,68 @@
+---
+title: MDX
+sidebar_icon: notebook-pen
+description:
+  Learn how to use MDX in APIToGo to create rich documentation pages with markdown and custom React
+  components.
+---
+
+APIToGo supports MDX files for creating rich content pages. MDX is a markdown format that allows you
+to include JSX components in your markdown files.
+
+## Getting Started
+
+To use MDX in your documentation, simply create files with the `.mdx` extension instead of `.md`.
+These files work exactly like regular markdown files but with all MDX features unlocked - you can
+write normal markdown content and add JSX components whenever needed.
+
+```
+docs/
+├── my-page.md      # Regular markdown
+├── my-mdx-page.mdx # MDX with JSX support
+```
+
+## Custom Components
+
+APIToGo supports the use of custom components in your MDX files. This allows you to create reusable
+components that can be used across multiple pages.
+
+You can create a custom component in your project and reference it in the
+[APIToGo Configuration](./overview.md) file.
+
+For example, create the `<MyCustomComponent />` component in a file called `MyCustomComponent.tsx`
+in the `src` directory at the root of your project.
+
+```tsx
+export default function MyCustomComponent() {
+  return <div>My Custom Component</div>;
+}
+```
+
+In [APIToGo Configuration](./overview.md) you will need to import the component and add it to the
+`customComponents` option in the configuration.
+
+```ts title=apitogo.config.ts
+import MyCustomComponent from "./src/MyCustomComponent";
+
+const config: ApitogoConfig = {
+  // ...
+  mdx: {
+    components: {
+      MyCustomComponent,
+    },
+  },
+  // ...
+};
+
+export default config;
+```
+
+## JSX in Headings
+
+JSX components in headings render in both the sidebar navigation and table of contents:
+
+```mdx
+# My Page <Badge>New</Badge>
+```
+
+Components must be registered via [`mdx.components`](#custom-components) to work in headings.

package/docs/markdown/overview.md

@@ -0,0 +1,275 @@
+---
+title: Markdown
+navigation_icon: align-left
+description:
+  Comprehensive guide to using Markdown and MDX in APIToGo, including formatting, frontmatter,
+  syntax highlighting, tables, lists, task lists, collapsible sections, and advanced documentation
+  features.
+---
+
+APIToGo supports
+[GitHub Flavored Markdown](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax)
+(GFM) with additional features for creating rich documentation.
+
+## Basic Formatting
+
+### Headers
+
+Use `#` to create headers. The number of `#` symbols determines the header level:
+
+```md
+# H1 Header
+
+## H2 Header
+
+### H3 Header
+
+#### H4 Header
+
+##### H5 Header
+
+###### H6 Header
+```
+
+### Text Formatting
+
+<!-- prettier-ignore -->
+```mdx
+**Bold text**
+_Italic text_
+~~Strikethrough text~~
+`Inline code`
+```
+
+**Bold text**  
+_Italic text_  
+~~Strikethrough text~~  
+`Inline code`
+
+### Lists
+
+**Unordered lists:**
+
+```md
+- Item 1
+- Item 2
+  - Nested item
+  - Another nested item
+```
+
+**Ordered lists:**
+
+```md
+1. First item
+2. Second item
+   1. Nested item
+   2. Another nested item
+```
+
+<details>
+<summary>See list examples</summary>
+
+**Unordered list:**
+
+- Item 1
+- Item 2
+  - Nested item
+  - Another nested item
+
+**Ordered list:**
+
+1. First item
+2. Second item
+   1. Nested item
+   2. Another nested item
+
+</details>
+
+### Links and Images
+
+```md
+[Link text](https://example.com)
+
+![Image alt text](image.jpg)
+```
+
+<details>
+<summary>See link and image examples</summary>
+
+[Link text](https://example.com)
+
+![Image alt text](https://images.unsplash.com/photo-1588083066783-8828e623bad7?q=75&w=400&auto=format&fit=crop)
+
+</details>
+
+### Tables
+
+```md
+| Header 1 | Header 2 | Header 3 |
+| -------- | -------- | -------- |
+| Cell 1   | Cell 2   | Cell 3   |
+| Cell 4   | Cell 5   | Cell 6   |
+```
+
+<details>
+<summary>See table example</summary>
+
+| Header 1 | Header 2 | Header 3 |
+| -------- | -------- | -------- |
+| Cell 1   | Cell 2   | Cell 3   |
+| Cell 4   | Cell 5   | Cell 6   |
+
+</details>
+
+### Blockquotes
+
+```md
+> This is a blockquote
+>
+> It can span multiple lines
+```
+
+<details>
+<summary>See blockquote example</summary>
+
+> This is a blockquote
+>
+> It can span multiple lines
+
+</details>
+
+## Frontmatter
+
+Frontmatter allows you to configure page metadata using YAML at the beginning of your markdown
+files:
+
+```md
+---
+title: My Page Title
+description: Page description for SEO
+navigation_icon: book
+category: Getting Started
+---
+
+Your markdown content starts here...
+```
+
+Common frontmatter properties include `title`, `description`, `sidebar_icon`, and `category`. For a
+complete list of supported properties, see the [Frontmatter documentation](./frontmatter).
+
+## MDX Support
+
+APIToGo supports [MDX](./mdx), allowing you to use JSX components within your markdown:
+
+```mdx title=my-page.mdx
+import MyCustomComponent from "./MyCustomComponent";
+
+# Regular Markdown
+
+This is regular markdown content.
+
+<MyCustomComponent prop="value" />
+
+You can mix markdown and JSX seamlessly.
+```
+
+MDX enables you to create interactive documentation with custom React components. Learn more in the
+[MDX documentation](./mdx).
+
+## Syntax Highlighting
+
+APIToGo uses [Shiki](https://shiki.style/) for syntax highlighting in code blocks:
+
+````md
+```javascript
+function greet(name) {
+  console.log(`Hello, ${name}!`);
+}
+```
+````
+
+**Advanced features:**
+
+- Line highlighting: `{1,3-5}`
+- Word highlighting: `/keyword/`
+- Line numbers: `showLineNumbers`
+- Titles: `title="filename.js"`
+
+````
+```tsx {4-5} /useState/ title="Counter.tsx" showLineNumbers
+import { useState } from "react";
+
+function Counter() {
+  const [count, setCount] = useState(0);
+  return <button onClick={() => setCount(count + 1)}>{count}</button>;
+}
+```
+````
+
+<details>
+<summary>See advanced features example</summary>
+
+```tsx {4-5} /useState/ title="Counter.tsx" showLineNumbers
+import { useState } from "react";
+
+function Counter() {
+  const [count, setCount] = useState(0);
+  return <button onClick={() => setCount(count + 1)}>{count}</button>;
+}
+```
+
+</details>
+
+For complete syntax highlighting documentation, see [Code Blocks](./code-blocks).
+
+## Additional Features
+
+APIToGo also supports:
+
+- [Admonitions](./admonitions) - Callout boxes for notes, warnings, and tips
+- Task lists with checkboxes
+- Automatic link detection
+
+### Task Lists
+
+```md
+- [x] Completed task
+- [ ] Incomplete task
+- [ ] Another task
+```
+
+<details>
+<summary>See task list example</summary>
+
+- [x] Completed task
+- [ ] Incomplete task
+- [ ] Another task
+
+</details>
+
+### Collapsible Sections
+
+You can create collapsible content using HTML `<details>` and `<summary>` tags:
+
+```html
+<details>
+  <summary>Click to expand</summary>
+
+  This content is hidden by default and can be expanded by clicking the summary. You can include any
+  markdown content here: - Lists - **Bold text** - Code blocks - Images
+</details>
+```
+
+<details>
+<summary>Click to expand</summary>
+
+This content is hidden by default and can be expanded by clicking the summary.
+
+You can include any markdown content here:
+
+- Lists
+- **Bold text**
+- Code blocks
+- Images
+
+</details>

package/docs/plugins.md

@@ -0,0 +1,5 @@
+---
+title: APIToGo Plugins
+---
+
+APIToGo can be extended using plugins.

package/docs/quickstart.md

@@ -0,0 +1,87 @@
+---
+title: Quickstart
+description:
+  Get started with APIToGo by creating a new APIToGo app using the `@lukoweb/create-apitogo` tool.
+sidebar_icon: circle-play
+zuplo: false
+---
+
+Ready to build beautiful API documentation and developer portals in minutes? APIToGo's CLI tool will
+have you up and running with a modern, customizable site that your developers will love.
+
+## Prerequisites
+
+- **Node.js** `22.7.0+` (or `20.19+`) - [Download here](https://nodejs.org/)
+- A terminal or command prompt
+- Your favorite code editor
+
+## Getting Started
+
+<Stepper>
+
+1. **Create your new APIToGo project:**
+
+   ```bash
+   npm create @lukoweb/apitogo@latest
+   ```
+
+   The CLI will walk you through setting up your project with interactive prompts. Choose from
+   templates like API documentation, developer portals, or start from scratch.
+
+1. **Navigate to your project:**
+
+   ```bash
+   cd your-project-name
+   ```
+
+1. **Launch the development server:**
+
+   ```bash
+   npm run dev
+   ```
+
+   🎉 **That's it!** Your APIToGo site is now running at `http://localhost:3000`. You'll see hot
+   reloading as you make changes, so you can iterate quickly.
+
+1. **What's next?**
+   - Customize your [theme and colors](./customization/colors-theme.mdx)
+   - Add your [OpenAPI specifications](./configuration/api-reference.md)
+   - Set up [authentication](./configuration/authentication.md)
+   - [Deploy your site](./deployment.md) when you're ready to go live
+
+</Stepper>
+
+## Use an existing folder (Markdown and OpenAPI)
+
+If you already have **`.md` / `.mdx`** files and an **OpenAPI** spec in a project directory, you can
+add APIToGo without starting from `create-apitogo`:
+
+1. **Lay out content in a predictable way** — Put docs under a single folder (default name
+   **`pages/`**). Place your OpenAPI file where the tooling can find it, for example
+   **`apis/openapi.json`** or **`openapi.json`** in the project root.
+
+2. **Install the CLI** (once per machine), then run **`make-config`** from that project root:
+
+   ```bash
+   npm install -g @lukoweb/apitogo@latest
+   apitogo make-config
+   ```
+
+   This can create **`package.json`**, **`tsconfig.json`**, and **`apitogo.config.tsx`** when
+   missing, add an **`apis`** entry when a spec is detected, and generate **`navigation`** and
+   **`redirects`** from your Markdown tree.
+
+3. **Install dependencies and start dev** (if `package.json` was just created):
+
+   ```bash
+   npm install
+   npm run dev
+   ```
+
+For options (for example `--pages-dir` if your docs are not under `pages/`) and full behavior, see
+**[Make config (CLI)](./configuration/make-config.mdx)**.
+
+## 🚀 Pro Tips
+
+- Use `npm run build` to create a production build
+- Join our [Discord community](https://apitogo.com) for support and tips

package/docs/writing.mdx

@@ -0,0 +1,72 @@
+---
+title: Writing
+sidebar_icon: book-open-text
+description: A guide to writing documentation in APIToGo using Markdown and MDX.
+---
+
+Get started with creating rich documentation in APIToGo using Markdown and MDX. This guide covers
+the essentials to help you begin documenting your project.
+
+## Quick Start
+
+1. **Create a markdown file** in your `pages` directory
+2. **Add frontmatter** with title and metadata
+3. **Configure navigation** to make it discoverable
+4. **Write content** using Markdown or MDX
+
+### Basic Document Structure
+
+```md
+---
+title: My Document
+sidebar_icon: file-text
+---
+
+Your content goes here using standard Markdown syntax.
+```
+
+## Adding to Navigation
+
+To make your documentation discoverable, add it to the navigation configuration. Documents are
+referenced by their file path:
+
+```ts title="apitogo.config.ts"
+const config = {
+  navigation: [
+    {
+      type: "doc",
+      file: "my-document",
+      label: "My Document",
+    },
+  ],
+};
+```
+
+Learn more about configuring navigation at
+[Navigation → Documents](/docs/configuration/navigation#type-doc).
+
+## File Organization
+
+Organize your documentation files in logical directories:
+
+```
+pages/
+├── getting-started/
+│   ├── installation.md
+│   └── quick-start.md
+├── guides/
+│   ├── authentication.md
+│   └── deployment.md
+└── api/
+    └── reference.md
+```
+
+## What's Next?
+
+Explore the detailed guides to enhance your documentation:
+
+- **[Markdown Overview](/docs/markdown/overview)** - Complete markdown syntax reference
+- **[Frontmatter](/docs/markdown/frontmatter)** - Document metadata and configuration
+- **[MDX](/docs/markdown/mdx)** - Interactive components in markdown
+- **[Admonitions](/docs/markdown/admonitions)** - Callouts and alerts
+- **[Code Blocks](/docs/markdown/code-blocks)** - Syntax highlighting and features