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

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

@@ -0,0 +1,166 @@
+---
+title: Vite Markdown Plugin
+desc: Vite plugin for transforming Markdown content into Vue Single File Components.
+related:
+  - vite-plugins/viteexamplesplugin/overview
+  - quasar-app-extensions/vitemdpluginappext/overview
+---
+
+Welcome to the Vite Markdown Plugin documentation! This guide will provide you with an overview of the Vite Markdown plugin and its features.
+
+## What is the Vite Markdown Plugin?
+
+The Vite Markdown Plugin is a powerful tool that transforms Markdown content into Vue Single File Components (SFCs). It integrates seamlessly with Vite to provide a flexible and customizable way to handle Markdown files in your Vue projects.
+
+## Key Features
+
+- **Markdown to Vue SFC Transformation**: Converts Markdown files into Vue Single File Components, enabling dynamic content rendering.
+- **Navigation Menu Integration**: Supports generating a navigation structure based on your Markdown files.
+- **Configurable Path Prefix**: Allows setting a base path for routing or file resolution.
+- **Opinionated and Minimal**: Focuses on simplicity, leveraging the power of Vue and Markdown for content-driven applications.
+
+## md-plugins Used
+
+The `viteMdPlugin` is built on top of the following plugins:
+
+| Plugin                              | Description                                                             | Readme                                             | Docs                                     |
+| ----------------------------------- | ----------------------------------------------------------------------- | -------------------------------------------------- | ---------------------------------------- |
+| `@md-plugins/md-plugin-codeblocks`  | Enhances code block rendering with syntax highlighting, tabs, and more. | [README](packages/md-plugin-codeblocks/README.md)  | [Docs](/md-plugins/codeblocks/overview)  |
+| `@md-plugins/md-plugin-blockquote`  | Adds customizable CSS classes to blockquotes.                           | [README](packages/md-plugin-blockquote/README.md)  | [Docs](/md-plugins/blockquote/overview)  |
+| `@md-plugins/md-plugin-headers`     | Extracts and processes headers for generating ToCs or managing headers. | [README](packages/md-plugin-headers/README.md)     | [Docs](/md-plugins/headers/overview)     |
+| `@md-plugins/md-plugin-inlinecode`  | Adds a custom class to inline code blocks for styling.                  | [README](packages/md-plugin-inlinecode/README.md)  | [Docs](/md-plugins/inline-code/overview) |
+| `@md-plugins/md-plugin-imports`     | Extracts and processes `<script import>` blocks from Markdown.          | [README](packages/md-plugin-imports/README.md)     | [Docs](/md-plugins/imports/overview)     |
+| `@md-plugins/md-plugin-link`        | Converts Markdown links into Vue components for SPA-friendly routing.   | [README](packages/md-plugin-link/README.md)        | [Docs](/md-plugins/link/overview)        |
+| `@md-plugins/md-plugin-table`       | Adds custom classes and attributes to Markdown tables.                  | [README](packages/md-plugin-table/README.md)       | [Docs](/md-plugins/table/overview)       |
+| `@md-plugins/md-plugin-title`       | Extracts the first header in Markdown as the page title.                | [README](packages/md-plugin-title/README.md)       | [Docs](/md-plugins/title/overview)       |
+| `@md-plugins/md-plugin-frontmatter` | Extracts and processes frontmatter content from Markdown files.         | [README](packages/md-plugin-frontmatter/README.md) | [Docs](/md-plugins/frontmatter/overview) |
+| `@md-plugins/md-plugin-containers`  | Adds custom containers for callouts, warnings, and more.                | [README](packages/md-plugin-containers/README.md)  | [Docs](/md-plugins/containers/overview)  |
+| `@md-plugins/shared`                | Shared utilities and types for the plugins.                             | [README](packages/shared/README.md)                | [Docs](/md-plugins/shared/overview)      |
+
+## Installation
+
+You can install the Vite MD plugin using npm, yarn, or pnpm. Choose your preferred method below:
+
+```tabs
+<<| bash npm |>>
+npm install @md-plugins/vite-md-plugin
+<<| bash yarn |>>
+yarn add @md-plugins/vite-md-plugin
+<<| bash pnpm |>>
+pnpm add @md-plugins/vite-md-plugin
+```
+
+## Usage
+
+### Basic Setup with Vite
+
+To use the `viteMdPlugin`, configure it in your Vite project:
+
+```typescript
+import { defineConfig } from 'vite'
+import vue from '@vitejs/plugin-vue'
+import { viteMdPlugin } from '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, 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) => {
+  // ...
+```
+
+2. Add the following configuration:
+
+```typescript
+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
+},
+```
+
+3. 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.
+
+## Options
+
+The `viteMdPlugin` accepts the following parameters:
+
+| Parameter | Type       | Description                                                                                |
+| --------- | ---------- | ------------------------------------------------------------------------------------------ |
+| path      | string     | The base path prefix for routing or file resolution.                                       |
+| menu      | MenuItem[] | An array representing the navigation menu structure. Each item should have title and path. |
+
+## MenuItem Type
+
+The `menu` parameter should conform to the following structure:
+
+```typescript
+export interface MenuItem {
+  name: string
+  path?: string
+  icon?: string
+  iconColor?: string
+  rightIcon?: string
+  rightIconColor?: string
+  badge?: string
+  children?: MenuItem[]
+  external?: boolean
+  expanded?: boolean
+}
+```
+
+## Testing
+
+To run the tests for this plugin, use the following command:
+
+```bash
+pnpm test
+```
+
+## License
+
+This project is licensed under the MIT License. See the LICENSE file for details.

package/src/templates/init/src/q-press.globals.d.ts

@@ -0,0 +1,36 @@
+declare module '*.md'
+
+// Define types for headers
+interface TocMenuItem {
+  id: string
+  level: number
+  title: string
+  link?: string
+  deep?: boolean
+  sub?: boolean
+  onClick?: () => void
+  children?: TocMenuItem[]
+}
+
+// Define types for Markdown modules
+interface MarkdownModule {
+  title?: string
+  headers?: TocMenuItem[]
+  frontmatter?: Record<string, unknown>
+  filename?: string
+  render: (...args: unknown[]) => unknown
+}
+
+// Define types for menu items
+interface MenuItem {
+  name: string
+  path?: string
+  icon?: string
+  iconColor?: string
+  rightIcon?: string
+  rightIconColor?: string
+  badge?: string
+  children?: MenuItem[] | undefined
+  external?: boolean
+  expanded?: boolean
+}

package/src/templates/init/src/siteConfig/index.ts

@@ -0,0 +1,440 @@
+import { fabGithub, fabXTwitter } from '@quasar/extras/fontawesome-v6'
+import { slugify } from '@md-plugins/shared'
+import { version, productName } from '../../package.json'
+
+export interface SocialLink {
+  name: string
+  icon: string
+  path: string
+  external?: boolean
+}
+
+export interface SiteMenuItem extends MenuItem {
+  about?: string
+  expanded?: boolean
+  external?: boolean
+  children?: SiteMenuItem[]
+  separator?: boolean
+  header?: string
+  mq?: number
+  extract?: string
+  image?: string
+  maxWidth?: string
+}
+
+export interface LinksConfig {
+  primaryHeaderLinks: SiteMenuItem[]
+  secondaryHeaderLinks: SiteMenuItem[]
+  moreLinks: SiteMenuItem[]
+  footerLinks: SiteMenuItem[]
+  socialLinks: SocialLink[]
+  ecoSystemLinks?: SiteMenuItem[]
+}
+
+export interface LogoConfig {
+  showLogo: boolean
+  logoLight: string
+  logoDark: string
+  logoAlt: string
+}
+
+export interface versionConfig {
+  showTitle: boolean
+  showVersion: boolean
+  showOnHeader: boolean
+  showOnSidebar: boolean
+}
+
+export interface UIConfig {
+  usePrimaryHeader: boolean // typically 72px
+  useSecondaryHeader: boolean // typically 55px
+  headerHeightHint: number // typically 128 for both headers
+  useMoreLinks: boolean
+  useFooter: boolean
+  useSidebar: boolean
+  useToc: boolean
+}
+
+export interface CopyrightConfig {
+  line1: string
+  line2: string
+}
+
+export interface LicenseConfig {
+  label: string
+  link: string
+}
+
+export interface PrivacyConfig {
+  label: string
+  link: string
+}
+
+export interface SiteConfig {
+  lang: string
+  title: string
+  description: string
+  theme: string
+  version: string
+  copyright: CopyrightConfig
+  githubEditRoot: string
+  license: LicenseConfig
+  privacy: PrivacyConfig
+  logoConfig: LogoConfig
+  versionConfig: versionConfig
+  config: UIConfig
+  links: LinksConfig
+  sidebar: MenuItem[]
+}
+
+function processMenuItem(item: MenuItem): MenuItem {
+  return {
+    name: item.name,
+    path: slugify(item.name),
+    expanded: item.expanded ?? false,
+    children: item.children ? item.children.map(processMenuItem) : undefined,
+  }
+}
+
+const socialLinks = {
+  name: 'Social',
+  mq: 1400, // media query breakpoint
+  children: [
+    {
+      name: 'GitHub',
+      icon: fabGithub,
+      path: 'https://github.com/md-plugins/md-plugins/tree/dev',
+      external: true,
+    },
+    {
+      name: 'X (Twitter)',
+      icon: fabXTwitter,
+      path: 'https://twitter.com/md_plugins',
+      external: true,
+    },
+  ],
+}
+
+const netlifyLink = {
+  path: 'https://www.netlify.com',
+  external: true,
+  image: 'https://www.netlify.com/img/global/badges/netlify-color-accent.svg',
+  name: 'Deploys by Netlify',
+  maxWidth: '120px',
+}
+
+const SponsorsLinks = {
+  name: 'Sponsors',
+  children: [
+    {
+      name: netlifyLink.name,
+      path: netlifyLink.path,
+      external: netlifyLink.external,
+      image: netlifyLink.image,
+    },
+  ],
+}
+
+const footerLinks = [
+  {
+    name: SponsorsLinks.name,
+    children: [...SponsorsLinks.children],
+  },
+  {
+    name: socialLinks.name,
+    children: [...socialLinks.children],
+  },
+]
+
+const gettingStartedMenu = {
+  name: 'Getting Started',
+  mq: 470, // media query breakpoint
+  children: [{ name: 'Introduction', path: '/getting-started/introduction' }],
+}
+
+const mdPluginsMenu = {
+  name: 'MD Plugins',
+  mq: 600, // media query breakpoint
+  children: [
+    {
+      name: 'Blockquote',
+      children: [
+        { name: 'Overview', path: '/md-plugins/blockquote/overview' },
+        { name: 'Advanced', path: '/md-plugins/blockquote/advanced' },
+      ],
+    },
+    {
+      name: 'Codeblocks',
+      children: [
+        { name: 'Overview', path: '/md-plugins/codeblocks/overview' },
+        { name: 'Advanced', path: '/md-plugins/codeblocks/advanced' },
+      ],
+    },
+    {
+      name: 'Containers',
+      children: [
+        { name: 'Overview', path: '/md-plugins/containers/overview' },
+        { name: 'Advanced', path: '/md-plugins/containers/advanced' },
+      ],
+    },
+    {
+      name: 'Frontmatter',
+      children: [
+        { name: 'Overview', path: '/md-plugins/frontmatter/overview' },
+        { name: 'Advanced', path: '/md-plugins/frontmatter/advanced' },
+      ],
+    },
+    {
+      name: 'Headers',
+      children: [
+        { name: 'Overview', path: '/md-plugins/headers/overview' },
+        { name: 'Advanced', path: '/md-plugins/headers/advanced' },
+      ],
+    },
+    {
+      name: 'Image',
+      children: [
+        { name: 'Overview', path: '/md-plugins/image/overview' },
+        { name: 'Advanced', path: '/md-plugins/image/advanced' },
+      ],
+    },
+    {
+      name: 'Imports',
+      children: [
+        { name: 'Overview', path: '/md-plugins/imports/overview' },
+        { name: 'Advanced', path: '/md-plugins/imports/advanced' },
+      ],
+    },
+    {
+      name: 'Inline Code',
+      children: [
+        { name: 'Overview', path: '/md-plugins/inlinecode/overview' },
+        { name: 'Advanced', path: '/md-plugins/inlinecode/advanced' },
+      ],
+    },
+    {
+      name: 'Link',
+      children: [
+        { name: 'Overview', path: '/md-plugins/link/overview' },
+        { name: 'Advanced', path: '/md-plugins/link/advanced' },
+      ],
+    },
+    {
+      name: 'Table',
+      children: [
+        { name: 'Overview', path: '/md-plugins/table/overview' },
+        { name: 'Advanced', path: '/md-plugins/table/advanced' },
+      ],
+    },
+    {
+      name: 'Title',
+      children: [
+        { name: 'Overview', path: '/md-plugins/title/overview' },
+        { name: 'Advanced', path: '/md-plugins/title/advanced' },
+      ],
+    },
+    {
+      name: 'Shared',
+      children: [{ name: 'Overview', path: '/md-plugins/shared/overview' }],
+    },
+  ],
+}
+
+const vitePluginsMenu = {
+  name: 'Vite Plugins',
+  mq: 780, // media query breakpoint
+  children: [
+    {
+      name: 'viteMdPlugin',
+      children: [
+        { name: 'Overview', path: '/vite-plugins/vitemdplugin/overview' },
+        { name: 'Advanced', path: '/vite-plugins/vitemdplugin/advanced' },
+      ],
+    },
+    {
+      name: 'viteExamplesPlugin',
+      children: [
+        { name: 'Overview', path: '/vite-plugins/viteexamplesplugin/overview' },
+        { name: 'Advanced', path: '/vite-plugins/viteexamplesplugin/advanced' },
+      ],
+    },
+  ],
+}
+
+const QuasarAppExts = {
+  name: 'Quasar App Extensions',
+  mq: 1020, // media query breakpoint
+  children: [
+    {
+      name: 'viteMdPluginAppExt',
+      children: [
+        { name: 'Overview', path: '/quasar-app-extensions/vitemdpluginappext/overview' },
+        { name: 'Advanced', path: '/quasar-app-extensions/vitemdpluginappext/advanced' },
+      ],
+    },
+    {
+      name: 'QPress',
+      children: [
+        { name: 'Overview', path: '/quasar-app-extensions/qpress/overview' },
+        { name: 'Advanced', path: '/quasar-app-extensions/qpress/advanced' },
+        { name: 'Themes', path: '/quasar-app-extensions/qpress/themes' },
+        { name: 'Components', path: '/quasar-app-extensions/qpress/components' },
+      ],
+    },
+  ],
+}
+
+const guidesMenu = {
+  name: 'Guides',
+  mq: 1100, // media query breakpoint
+  children: [
+    {
+      name: 'FAQ',
+      path: '/guides/faq',
+    },
+    {
+      name: 'Contributing',
+      path: '/guides/contributing',
+    },
+  ],
+}
+
+const otherMenu = {
+  name: 'Other',
+  mq: 1190, // media query breakpoint
+  children: [
+    {
+      name: 'Releases',
+      path: '/other/release-notes',
+    },
+  ],
+}
+
+const processedMdPluginsMenu = {
+  name: mdPluginsMenu.name,
+  path: slugify(mdPluginsMenu.name),
+  expanded: false,
+  children: mdPluginsMenu.children.map(processMenuItem),
+}
+
+const processedVitePluginsMenu = {
+  name: vitePluginsMenu.name,
+  path: slugify(vitePluginsMenu.name),
+  expanded: false,
+  children: vitePluginsMenu.children.map(processMenuItem),
+}
+
+const processedQuasarAppExts = {
+  name: QuasarAppExts.name,
+  path: slugify(QuasarAppExts.name),
+  expanded: false,
+  children: QuasarAppExts.children.map(processMenuItem),
+}
+
+const processedGuidesMenu = {
+  name: guidesMenu.name,
+  path: slugify(guidesMenu.name),
+  expanded: false,
+  children: guidesMenu.children.map(processMenuItem),
+}
+
+const secondaryToolbarLinks = [
+  gettingStartedMenu,
+  mdPluginsMenu,
+  vitePluginsMenu,
+  QuasarAppExts,
+  guidesMenu,
+  otherMenu,
+]
+
+export const moreLinks = [
+  {
+    name: 'More',
+    // children: [...primaryToolbarLinks, { separator: true }, ...secondaryToolbarLinks, socialLinks],
+    children: [...secondaryToolbarLinks, socialLinks],
+  },
+]
+
+export const sidebar = [
+  {
+    name: gettingStartedMenu.name,
+    path: slugify(gettingStartedMenu.name),
+    expanded: false,
+    children: gettingStartedMenu.children.map((item) => ({
+      name: item.name,
+      path: slugify(item.name),
+    })),
+  },
+  processedMdPluginsMenu,
+  processedVitePluginsMenu,
+  processedQuasarAppExts,
+  processedGuidesMenu,
+]
+
+const config = {
+  lang: 'en-US',
+  title: productName,
+  description:
+    'MD-Plugins is a collection of Markdown and Vite plugins that make it easy to build markdown user interfaces in Vue and Quasar applications.',
+  theme: 'doc',
+  version: version,
+  copyright: {
+    line1: `Copyright © 2024-${new Date().getFullYear()} MD-PLUGINS`,
+    line2: '',
+  } as CopyrightConfig,
+  githubEditRoot: 'https://github.com/md-plugins/md-plugins/edit/dev/packages/docs/src/markdown/',
+  license: {
+    label: 'MIT License',
+    link: 'https://github.com/md-plugins/md-plugins/blob/dev/LICENSE.md',
+  } as LicenseConfig,
+  privacy: {
+    label: 'Privacy Policy',
+    link: '/privacy-policy',
+  } as PrivacyConfig,
+  logoConfig: {
+    showLogo: true,
+    logoLight:
+      'https://raw.githubusercontent.com/md-plugins/md-plugins/refs/heads/main/media/markdown-1024x1024.png',
+    logoDark:
+      'https://raw.githubusercontent.com/md-plugins/md-plugins/refs/heads/main/media/markdown-1024x1024.png',
+    logoAlt: '@md-plugins',
+  } as LogoConfig,
+  versionConfig: {
+    showTitle: true,
+    showVersion: true,
+    showOnHeader: false,
+    showOnSidebar: true,
+  } as versionConfig,
+  config: {
+    usePrimaryHeader: false,
+    useSecondaryHeader: true,
+    headerHeightHint: 55,
+    useMoreLinks: true,
+    useFooter: true,
+    // useFooterLinks: true,
+    useSidebar: true,
+    useSidebarVersion: true,
+    useToc: true,
+  } as UIConfig,
+  links: {
+    primaryHeaderLinks: [] as SiteMenuItem[], // [...primaryToolbarLinks],
+    secondaryHeaderLinks: [...secondaryToolbarLinks] as SiteMenuItem[],
+    moreLinks: [
+      {
+        name: 'More',
+        children: [
+          // ...primaryToolbarLinks,
+          // { separator: true },
+          ...secondaryToolbarLinks,
+          socialLinks,
+        ],
+      },
+    ] as SiteMenuItem[],
+    footerLinks: [...footerLinks] as SiteMenuItem[],
+    socialLinks: [...socialLinks.children] as SocialLink[],
+  },
+  sidebar,
+} as SiteConfig
+
+export { sidebar as menu }
+export default config

package/src/templates/update/src/_q-press/api/components/DarkModeToggle.json

@@ -0,0 +1,37 @@
+{
+  "type": "component",
+  "meta": {
+    "docsUrl": "https://path-to-your-docs/dark-mode-toggle"
+  },
+  "props": {
+    "darkIcon": {
+      "type": "String",
+      "desc": "Icon name for dark mode",
+      "examples": [
+        "mdiMoonWaningCrescent"
+      ],
+      "default": "mdiMoonWaningCrescent",
+      "category": "content"
+    },
+    "lightIcon": {
+      "type": "String",
+      "desc": "Icon name for light mode",
+      "examples": [
+        "mdiWhiteBalanceSunny"
+      ],
+      "default": "mdiWhiteBalanceSunny",
+      "category": "content"
+    }
+  },
+  "events": {
+    "update:mode": {
+      "desc": "Emitted when the mode is toggled",
+      "params": {
+        "mode": {
+          "type": "String",
+          "desc": "The current mode ('dark' or 'light')"
+        }
+      }
+    }
+  }
+}