@md-plugins/quasar-app-extension-q-press 0.1.0-alpha.10

package/src/templates/init/src/markdown/quasar-app-extensions/vitemdpluginappext/overview.md

@@ -0,0 +1,103 @@
+---
+title: ViteMdPluginAppExt App Extension
+desc: Overview of the ViteMdPluginAppExt for Quasar.
+related:
+  - vite-plugins/vitemdplugin/overview
+  - quasar-app-extensions/qpress/overview
+---
+
+The `viteMdPluginAppExt` is a [Quasar App Extension](https://quasar.dev/app-extensions/introduction) that integrates the `viteMdPlugin` into your Quasar project. This extension allows you to use Markdown files as Vue components, enabling a seamless integration of Markdown content into your Quasar application.
+
+## Key Features
+
+- **Markdown as Vue Components**: Transform Markdown files into Vue components, allowing you to write and manage content in Markdown while leveraging the power of Vue and Quasar.
+- **Automatic Configuration**: Automatically configures your Quasar project to handle Markdown files, reducing the need for manual setup.
+- **Seamless Integration**: Integrates with Quasar's build system and Vue Router, ensuring smooth navigation and rendering of Markdown content.
+- **Customizable**: Provides options to customize the integration, allowing you to tailor the behavior to your specific needs.
+
+## How It Works
+
+The `viteMdPluginAppExt` extension leverages the `viteMdPlugin` to transform Markdown content into Vue components. It automatically updates your Quasar configuration to include the necessary settings for handling Markdown files.
+
+### Automatic Configuration
+
+When you install and configure the `viteMdPluginAppExt` extension, it makes the following changes to your Quasar configuration:
+
+- **Vue Router Mode**: Sets the `vueRouterMode` to `'history'` to ensure proper hash link handling.
+- **Vite Plugin Options**: Includes Markdown files in the `viteVuePluginOptions.include` array to ensure they are transpiled correctly.
+- **Auto Import Extensions**: Adds `'md'` and `'vue'` to the `framework.autoImportVueExtensions` array to enable auto-import for Markdown extensions.
+
+### Example Configuration
+
+Here is an example of how the `viteMdPluginAppExt` extension updates your Quasar configuration:
+
+```javascript
+build: {
+  vueRouterMode: 'history', // Required for proper hash link handling
+  viteVuePluginOptions.include: [/\.(vue|md)$/], // Include Markdown files
+},
+framework: {
+  framework.autoImportVueExtensions: ['md', 'vue'], // Include Markdown files
+}
+```
+
+## Installation
+
+To install the `viteMdPluginAppExt` extension, use the following command:
+
+```bash
+pnpm add @md-plugins/vite-md-plugin-app-ext
+```
+
+## Usage
+
+After installing the extension, you need to configure it in your Quasar project. Here are the steps to get started:
+
+1. **Import `@md-plugins/vite-md-plugin`:**
+
+   Update your `quasar.config.js` or `quasar.config.ts` to include the `@md-plugins/vite-md-plugin` extension:
+
+   ```js
+   import { viteMdPlugin, type MenuItem } from '@md-plugins/vite-md-plugin'
+   ```
+
+2. **Import Your Sidebar Menu:**
+
+   ```js
+   import siteConfig from './src/siteConfig'
+   const { sidebar } = siteConfig
+   ```
+
+3. **Add the `viteMdPlugin` to the `vitePlugins` array:**
+
+   ```js
+   vitePlugins: [
+     viteMdPlugin(ctx.appPaths.srcDir + '/markdown', sidebar as MenuItem[]),
+     // ...
+   ]
+   ```
+
+## MenuItem Interface
+
+The `MenuItem` interface defines the structure of the sidebar menu items. It includes the following properties:
+
+```ts
+interface MenuItem {
+  name: string
+  path?: string
+  icon?: string
+  iconColor?: string
+  rightIcon?: string
+  rightIconColor?: string
+  badge?: string
+  children?: MenuItem[] | undefined
+  external?: boolean
+  expanded?: boolean
+}
+```
+
+## Conclusion
+
+The `viteMdPluginAppExt` extension provides a convenient way to integrate Markdown content into your Quasar project. By transforming Markdown files into Vue components and automatically configuring your project, it simplifies the process of managing and rendering Markdown content. Whether you're building a documentation site, a blog, or any other content-rich application, the `viteMdPluginAppExt` extension offers a powerful and flexible solution.
+
+Happy coding!

package/src/templates/init/src/markdown/vite-plugins/index.md

@@ -0,0 +1,6 @@
+---
+title: Vite Plugins
+related:
+  - vite-plugins/vitemdplugin/overview
+  - vite-plugins/viteexamplesplugin/overview
+---

package/src/templates/init/src/markdown/vite-plugins/viteexamplesplugin/advanced.md

@@ -0,0 +1,138 @@
+---
+title: ViteExamplesPlugin Advanced Topics
+desc: ViteExamplesPlugin advanced topics for Vite.
+related:
+  - vite-plugins/vitemdplugin/advanced
+---
+
+## ViteExamplesPlugin
+
+The `viteExamplesPlugin` is a powerful tool for integrating example code snippets and demos into your Vite project. This section will cover how the plugin works, the available options for customization, and examples of how to use it effectively with both Vite and Quasar with Vite.
+
+### Type Information
+
+```ts
+import { Plugin } from 'vite'
+
+/**
+ * Creates a Vite plugin for handling Markdown examples.
+ *
+ * This function sets up the target folder for example files and returns a function
+ * that creates the actual Vite plugin. The returned plugin resolves and loads
+ * example code based on the production or development environment.
+ *
+ * @param isProd - A boolean indicating whether the Vite build is in production mode.
+ *                 This parameter determines whether the plugin will use the `prodLoad` or `devLoad` function for loading example code.
+ *
+ * @param path - The path to the directory containing the example files.
+ *               This path will be used as the target folder for resolving examples.
+ *               The `targetFolder` variable is set to this value before creating the Vite plugin.
+ *
+ * @returns A function that creates a Vite plugin.
+ *          The returned function takes a boolean parameter `isProd` and returns a Vite plugin object.
+ *          The plugin object has a `name`, `enforce`, `resolveId`, and `load` property.
+ *          The `resolveId` property resolves module IDs starting with "examples:" and returns a resolved ID.
+ *          The `load` property loads example code based on the production or development environment.
+ */
+declare function viteExamplesPlugin({ isProd, path }: { isProd: boolean; path: string }): Plugin
+
+/**
+ * A function to determine the manual chunk name for a given module ID.
+ *
+ * @param id - The module ID to analyze.
+ * @returns A string representing the chunk name or `undefined`.
+ */
+declare function viteManualChunks(id: string): string | undefined
+
+export { viteExamplesPlugin, viteManualChunks }
+```
+
+### How It Works
+
+The `viteExamplesPlugin` processes example code snippets and demos in your Vite project, transforming them into interactive components. It supports various features to enhance the development and presentation of example code.
+
+### Plugin Options
+
+The `viteExamplesPlugin` provides several options for customization. Here are the available options and their descriptions:
+
+#### `isProd`
+
+- **Type**: `boolean`
+- **Description**: A flag indicating whether the build is for production. This parameter determines whether the plugin will use the `prodLoad` or `devLoad` function for loading example code.
+
+#### `path`
+
+- **Type**: `string`
+- **Description**: The absolute path to the directory containing example code snippets and demos.
+
+### Vite Configuration
+
+Here is an example of how you can configure the `viteExamplesPlugin` with custom options:
+
+```typescript
+import { defineConfig } from 'vite'
+import vue from '@vitejs/plugin-vue'
+import { viteExamplesPlugin } from 'vite-examples-plugin'
+
+export default defineConfig(({ mode }) => {
+  const isProduction = mode === 'production'
+
+  return {
+    plugins: [
+      vue(),
+      viteExamplesPlugin({ isProd: isProduction, path: '/absolute/path/to/examples' }),
+    ],
+    build: {
+      chunkSizeWarningLimit: 650,
+      rollupOptions: {
+        output: {
+          manualChunks: {
+            vendor: ['vue', 'vite'],
+          },
+        },
+      },
+    },
+  }
+})
+```
+
+### Quasar Framework Configuration
+
+If you’re using the Quasar Framework with Vite, additional configuration is needed to enable support for example code snippets and demos:
+
+1. **Update `quasar.config.(js|ts)`**:
+
+```typescript
+import { viteExamplesPlugin } from 'vite-examples-plugin'
+
+export default defineConfig(({ mode }) => {
+  const isProduction = mode === 'production'
+
+  return {
+    build: {
+      vueRouterMode: 'history', // Required for proper hash link handling
+
+      viteVuePluginOptions: {
+        include: [/\.(vue|md)$/], // Include Markdown files
+      },
+
+      vitePlugins: [
+        viteExamplesPlugin({ isProd: isProduction, path: '/absolute/path/to/examples' }),
+        // ...
+      ],
+    },
+
+    framework: {
+      autoImportVueExtensions: ['vue', 'md'], // Enable auto-import for Markdown extensions
+    },
+  }
+})
+```
+
+2. **Ensure that your routes and hash links are compatible with Vue Router's history mode.**
+
+### Conclusion
+
+The `viteExamplesPlugin` is a versatile tool for integrating example code snippets and demos into your Vite project. By customizing the plugin options, including the `isProd` flag, you can tailor the behavior of the plugin to fit your specific needs. Whether you are using Vite or Quasar with Vite, the `viteExamplesPlugin` provides a flexible and powerful solution for handling example code. Experiment with different configurations and find the one that works best for you.
+
+Happy coding!

package/src/templates/init/src/markdown/vite-plugins/viteexamplesplugin/overview.md

@@ -0,0 +1,88 @@
+---
+title: Vite Examples Plugin
+desc: Vite Examples plugin for enhanced functionality.
+related:
+  - vite-plugins/vitemdplugin/overview
+---
+
+Welcome to the Vite Examples Plugin documentation! This guide will provide you with an overview of the Vite Examples plugins and their features.
+
+## What is the Vite Examples Plugins?
+
+The Vite Examples Plugin is a powerful tool that enhances the standard Vite functionality by providing custom chunking and example file handling. They integrate seamlessly with Vite to provide a flexible and customizable way to manage your Vite build process.
+
+## Key Features
+
+- **Manual Chunking**: Customize the chunking strategy for your Vite build.
+- **Example Handling**: Easily include and manage examples in your Vite project.
+
+## Installation
+
+You can install the Vite Examples plugin using npm, yarn, or pnpm. Choose your preferred method below:
+
+```tabs
+<<| bash npm |>>
+npm install @md-plugins/vite-examples-plugin
+<<| bash yarn |>>
+yarn add @md-plugins/vite-examples-plugin
+<<| bash pnpm |>>
+pnpm add @md-plugins/vite-examples-plugin
+```
+
+## Quasar Configuration
+
+To use the Vite Examples plugin with Quasar, you can extend the Vite configuration as follows:
+
+```typescript
+import { viteExamplesPlugin, viteManualChunks } from '@md-plugins/vite-examples-plugin'
+
+extendViteConf(viteConf, { isClient }) {
+  if (ctx.prod && isClient) {
+    viteConf.build = viteConf.build || {}
+    viteConf.build.chunkSizeWarningLimit = 650
+    viteConf.build.rollupOptions = {
+      output: { manualChunks: viteManualChunks },
+    }
+  }
+}
+
+vitePlugins: [
+  viteExamplesPlugin({ isProd: ctx.prod, path: ctx.appPaths.srcDir + '/examples' }),
+  // other plugins...
+]
+```
+
+## Vite Configuration
+
+To use the Vite Examples plugin with Vite, you can configure it as follows:
+
+```typescript
+import { defineConfig } from 'vite'
+import vue from '@vitejs/plugin-vue'
+import { viteExamplesPlugin, viteManualChunks } from 'vite-examples-plugin'
+
+export default defineConfig(({ mode }) => {
+  const isProduction = mode === 'production'
+
+  return {
+    plugins: [
+      vue(),
+      viteExamplesPlugin({ isProd: isProduction, path: '/absolute/path/to/examples' }),
+    ],
+    build: {
+      chunkSizeWarningLimit: 650,
+      rollupOptions: {
+        output: {
+          manualChunks: viteManualChunks,
+        },
+      },
+    },
+  }
+})
+```
+
+## Support
+
+If you have any questions or need assistance, please refer to the FAQ or reach out to our support team.
+
+Happy coding!

package/src/templates/init/src/markdown/vite-plugins/vitemdplugin/advanced.md

@@ -0,0 +1,226 @@
+---
+title: ViteMdPlugin Advanced Topics
+desc: ViteMdPlugin advanced topics for Markdown.
+related:
+  - vite-plugins/viteexamplesplugin/advanced
+---
+
+The `viteMdPlugin` is a powerful tool for integrating Markdown processing into your Vite project. This section will cover how the plugin works, the available options for customization, and examples of how to use it effectively with both Vite and Quasar with Vite.
+
+### Type Information
+
+```ts
+import { Plugin } from 'vite'
+
+interface MenuItem {
+  name: string
+  path?: string
+  icon?: string
+  iconColor?: string
+  rightIcon?: string
+  rightIconColor?: string
+  badge?: string
+  children?: MenuItem[] | undefined
+  external?: boolean
+  expanded?: boolean
+}
+interface MenuNode {
+  name: string
+  path?: string
+  external?: boolean
+  children?: MenuNode[]
+}
+interface FlatMenuEntry {
+  name: string
+  category: string | null
+  path: string
+  prev?: FlatMenuEntry
+  next?: FlatMenuEntry
+}
+type FlatMenu = Record<string, FlatMenuEntry>
+interface NavItem extends FlatMenuEntry {
+  classes: string
+}
+interface RelatedItem {
+  name: string
+  category: string
+  path: string
+}
+interface UserConfig {
+  path: string
+  menu: MenuItem[]
+}
+
+/**
+ * Creates a Vite plugin for processing Markdown files based on the provided user configuration.
+ * This function configures and returns a plugin that transforms Markdown content into Vue Single File Components (SFCs).
+ *
+ * @param userConfig - The configuration object for the Vite Markdown plugin.
+ * @param userConfig.path - The base path prefix to be used for routing or file resolution.
+ * @param userConfig.menu - An array of MenuItem objects representing the navigation menu structure.
+ * @returns A Vite Plugin object pre-configured with the provided settings for Markdown processing.
+ */
+declare function viteMdPlugin(userConfig: UserConfig): Plugin
+
+export {
+  type FlatMenu,
+  type FlatMenuEntry,
+  type MenuItem,
+  type MenuNode,
+  type NavItem,
+  type RelatedItem,
+  type UserConfig,
+  viteMdPlugin,
+}
+```
+
+### How It Works
+
+The `viteMdPlugin` processes Markdown files in your Vite project, transforming them into Vue Single File Components (SFCs). It supports various plugins to enhance the Markdown content, such as handling frontmatter, headers, containers, code blocks, and more.
+
+### Default Behavior
+
+By default, the `viteMdPlugin` processes Markdown files and applies the configured plugins to enhance the content. Here is an example of a basic configuration:
+
+```typescript
+import { defineConfig } from 'vite'
+import vue from '@vitejs/plugin-vue'
+import { viteMdPlugin, type MenuItem } from '@md-plugins/vite-md-plugin'
+
+const menu = [] // Define your navigation menu structure here
+const basePath = '/docs' // Base path prefix
+
+export default defineConfig({
+  plugins: [vue(), viteMdPlugin({ path: basePath, menu })],
+})
+```
+
+### Quasar Framework Configuration
+
+If you’re using the Quasar Framework with Vite, additional configuration is needed to enable support for `.md` files:
+
+1. Update `quasar.config.(js|ts)`:
+
+```typescript
+import { viteMdPlugin } from '@md-plugins/vite-md-plugin';
+import { menu } from './src/assets/menu'; // be sure to create this file
+
+export default defineConfig((ctx) => {
+  // ...
+  build: {
+    vueRouterMode: 'history', // Required for proper hash link handling
+
+    viteVuePluginOptions: {
+      include: [/\.(vue|md)$/], // Include Markdown files
+    },
+
+    vitePlugins: [
+      [
+        viteMdPlugin,
+        {
+          path: ctx.appPaths.srcDir + '/markdown',
+          menu: sidebar as MenuItem[],
+        },
+      ],
+      // ...
+    ],
+  },
+
+  framework: {
+    autoImportVueExtensions: ['vue', 'md'], // Enable auto-import for Markdown extensions
+  },
+})
+```
+
+2. Ensure that your routes and hash links are compatible with Vue Router's history mode.
+
+### Navigation Menu Integration
+
+The `viteMdPlugin` allows you to define a navigation structure that can be updated dynamically based on the Markdown files in your project:
+
+```typescript
+const menu = [
+  { title: 'Home', path: '/home' },
+  { title: 'About', path: '/about' },
+]
+```
+
+This menu is passed as a parameter to the plugin and can be used to build a dynamic sidebar or navigation bar in your application.
+
+### Plugin Options
+
+The `viteMdPlugin` provides several options for customization. Here are the available options and their descriptions:
+
+#### `path`
+
+- **Type**: `string`
+- **Description**: The base path prefix to be used for routing or file resolution.
+
+#### `menu`
+
+- **Type**: `MenuItem[]`
+- **Description**: An array of `MenuItem` objects representing the navigation menu structure.
+
+```ts
+export interface MenuItem {
+  name: string
+  path?: string
+  icon?: string
+  iconColor?: string
+  rightIcon?: string
+  rightIconColor?: string
+  badge?: string
+  children?: MenuItem[] | undefined
+  external?: boolean
+  expanded?: boolean
+}
+```
+
+### Example Configuration
+
+Here is an example of how you can configure the `viteMdPlugin` with custom options:
+
+```typescript
+import { defineConfig } from 'vite'
+import vue from '@vitejs/plugin-vue'
+import { viteMdPlugin } from '@md-plugins/vite-md-plugin'
+
+const menu = [
+  { title: 'Home', path: '/' },
+  { title: 'Guide', path: '/guide/' },
+  { title: 'API', path: '/api/' },
+]
+const basePath = '/docs'
+
+export default defineConfig({
+  plugins: [vue(), viteMdPlugin(basePath, menu)],
+})
+```
+
+### Using the Plugin
+
+Once the `viteMdPlugin` is configured, you can use it to process Markdown files in your Vite project. Here is an example of a Markdown file:
+
+```markdown
+---
+title: My Awesome Post
+date: 2023-10-01
+tags: [vite, markdown, plugin]
+---
+
+# My Awesome Post
+
+This is the content of my awesome post.
+```
+
+When you build your project, the `viteMdPlugin` will process this Markdown file and generate a Vue Single File Component (SFC) that can be used in your application.
+
+## Advanced
+
+If you need to change the behavior of `viteMdPlugin`, you can create your own Vite plugin and use that instead. Look at the source to see how it can be done.
+
+## Conclusion
+
+The `viteMdPlugin` is a versatile tool for integrating Markdown processing into your Vite project. By customizing the plugins and options, you can tailor the Markdown content to fit your specific needs. Whether you are using Vite or Quasar with Vite, the `viteMdPlugin` provides a flexible and powerful solution for handling Markdown files. Experiment with different configurations and find the one that works best for you.
+
+Happy coding!

package/src/templates/init/src/markdown/vite-plugins/vitemdplugin/index.md

@@ -0,0 +1,6 @@
+---
+title: Vite Plugins
+related:
+  - vite-plugins/vitemdplugin/overview
+  - vite-plugins/vitemdplugin/advanced
+---