@md-plugins/quasar-app-extension-q-press 0.1.0-beta.2 → 0.1.0-beta.21

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

@@ -11,7 +11,7 @@ The `viteMdPlugin` is a powerful tool for integrating Markdown processing into y
 
 ```ts
 import { Plugin } from 'vite'
-import { Options } from 'markdown-it'
+import MarkdownIt, { Options } from 'markdown-it'
 import { BlockquotePluginOptions } from '@md-plugins/md-plugin-blockquote'
 import { CodeblockPluginOptions } from '@md-plugins/md-plugin-codeblocks'
 import { FrontmatterPluginOptions } from '@md-plugins/md-plugin-frontmatter'
@@ -19,21 +19,27 @@ import { HeadersPluginOptions } from '@md-plugins/md-plugin-headers'
 import { ImagePluginOptions } from '@md-plugins/md-plugin-image'
 import { InlineCodePluginOptions } from '@md-plugins/md-plugin-inlinecode'
 import { LinkPluginOptions } from '@md-plugins/md-plugin-link'
+import { MermaidPluginOptions } from '@md-plugins/md-plugin-mermaid'
 import { TablePluginOptions } from '@md-plugins/md-plugin-table'
 
+type MarkdownItPlugin = (md: MarkdownIt, ...params: any[]) => void
+type MarkdownItPluginEntry = MarkdownItPlugin | [MarkdownItPlugin, ...any[]]
+
 interface MarkdownOptions extends Options {
   html?: boolean
   linkify?: boolean
   typographer?: boolean
   breaks?: boolean
-  blockquote?: BlockquotePluginOptions
-  codeblocks?: CodeblockPluginOptions
-  frontmatter?: FrontmatterPluginOptions
-  headers?: HeadersPluginOptions | boolean
-  image?: ImagePluginOptions
-  inlinecode?: InlineCodePluginOptions
-  link?: LinkPluginOptions
-  table?: TablePluginOptions
+  blockquotePlugin?: BlockquotePluginOptions
+  codeblockPlugin?: CodeblockPluginOptions
+  frontmatterPlugin?: FrontmatterPluginOptions
+  headersPlugin?: HeadersPluginOptions | boolean
+  imagePlugin?: ImagePluginOptions
+  inlineCodePlugin?: InlineCodePluginOptions
+  linkPlugin?: LinkPluginOptions
+  mermaidPlugin?: MermaidPluginOptions
+  tablePlugin?: TablePluginOptions
+  markdownItPlugins?: MarkdownItPluginEntry[]
 }
 
 interface MenuItem {
@@ -128,6 +134,59 @@ export default defineConfig({
 })
 ```
 
+### Using Other Markdown-It Plugins
+
+The `viteMdPlugin` already includes the md-plugins used by Q-Press, plus inserted text support for `++text++`. If you need additional Markdown-it syntax, install the plugin and pass it through `config.markdownItPlugins`.
+
+```tabs
+<<| bash pnpm |>>
+pnpm add markdown-it-mark markdown-it-sub markdown-it-sup markdown-it-footnote
+<<| bash bun |>>
+bun add markdown-it-mark markdown-it-sub markdown-it-sup markdown-it-footnote
+<<| bash yarn |>>
+yarn add markdown-it-mark markdown-it-sub markdown-it-sup markdown-it-footnote
+<<| bash npm |>>
+npm install markdown-it-mark markdown-it-sub markdown-it-sup markdown-it-footnote
+```
+
+```ts
+import { defineConfig } from 'vite'
+import vue from '@vitejs/plugin-vue'
+import markdownItFootnote from 'markdown-it-footnote'
+import markdownItMark from 'markdown-it-mark'
+import markdownItSub from 'markdown-it-sub'
+import markdownItSup from 'markdown-it-sup'
+import { viteMdPlugin } from '@md-plugins/vite-md-plugin'
+
+export default defineConfig({
+  plugins: [
+    vue(),
+    viteMdPlugin({
+      path: './src/markdown',
+      menu: [],
+      config: {
+        markdownItPlugins: [
+          markdownItMark, // ==highlight==
+          markdownItSub, // H~2~O
+          markdownItSup, // E=mc^2^
+          markdownItFootnote, // footnote references
+        ],
+      },
+    }),
+  ],
+})
+```
+
+If you own a raw MarkdownIt instance instead of using `viteMdPlugin`, wire the plugins directly:
+
+```ts
+import MarkdownIt from 'markdown-it'
+import markdownItMark from 'markdown-it-mark'
+
+const md = new MarkdownIt()
+md.use(markdownItMark)
+```
+
 ### Quasar Framework Configuration
 
 If you’re using the Quasar Framework with Vite, additional configuration is needed to enable support for `.md` files:
@@ -210,55 +269,26 @@ export interface MenuItem {
 #### `config`
 
 - **Type**: `MarkdownOptions`
-- **Description**: Additional configuration options for the Markdown processing.
-
-````ts
-import { Options } from 'markdown-it';
-import { BlockquotePluginOptions } from '@md-plugins/md-plugin-blockquote';
-import { CodeblockPluginOptions } from '@md-plugins/md-plugin-codeblocks';
-import { FrontmatterPluginOptions } from '@md-plugins/md-plugin-frontmatter';
-import { HeadersPluginOptions } from '@md-plugins/md-plugin-headers';
-import { ImagePluginOptions } from '@md-plugins/md-plugin-image';
-import { InlineCodePluginOptions } from '@md-plugins/md-plugin-inlinecode';
-import { LinkPluginOptions } from '@md-plugins/md-plugin-link';
-import { TablePluginOptions } from '@md-plugins/md-plugin-table';
-
-interface MarkdownOptions extends Options {
-    html?: boolean;
-    linkify?: boolean;
-    typographer?: boolean;
-    breaks?: boolean;
-    blockquote?: BlockquotePluginOptions;
-    codeblocks?: CodeblockPluginOptions;
-    frontmatter?: FrontmatterPluginOptions;
-    headers?: HeadersPluginOptions | boolean;
-    image?: ImagePluginOptions;
-    inlinecode?: InlineCodePluginOptions;
-    link?: LinkPluginOptions;
-    table?: TablePluginOptions;
-}
-```
+- **Description**: Additional configuration options for the Markdown processor and bundled md-plugins.
 
-### Example Configuration
+Use `config.markdownItPlugins` for extra Markdown-it syntax that md-plugins does not bundle by default. Use `config.mermaidPlugin` to customize Mermaid rendering.
 
-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'
+```ts
 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)],
+import markdownItMark from 'markdown-it-mark'
+
+viteMdPlugin({
+  path: './src/markdown',
+  menu: [],
+  config: {
+    markdownItPlugins: [markdownItMark],
+    mermaidPlugin: {
+      renderMode: 'component',
+      componentName: 'MarkdownMermaid',
+    },
+  },
 })
-````
+```
 
 ### Using the Plugin
 

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

@@ -31,19 +31,22 @@ The `viteMdPlugin` is built on top of the following plugins:
 | `@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-mermaid`     | Renders Mermaid fenced code blocks as diagrams.                         | [README](packages/md-plugin-mermaid/README.md)     | [Docs](/md-plugins/mermaid/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)      |
+| `@md-plugins/shared`                | Internal shared utilities and types used by the bundled 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:
+You can install the Vite MD plugin using npm, yarn, pnpm, or bun. Choose your preferred method below:
 
 ```tabs
 <<| bash pnpm |>>
 pnpm add @md-plugins/vite-md-plugin
+<<| bash bun |>>
+bun add @md-plugins/vite-md-plugin
 <<| bash yarn |>>
 yarn add @md-plugins/vite-md-plugin
 <<| bash npm |>>
@@ -136,7 +139,7 @@ The `viteMdPlugin` accepts the following parameters:
 
 The `menu` parameter should conform to the following structure:
 
-```typescript
+```typescript [twoslash]
 export interface MenuItem {
   name: string
   path?: string
@@ -149,6 +152,19 @@ export interface MenuItem {
   external?: boolean
   expanded?: boolean
 }
+
+const menu = [
+  {
+    name: 'Getting Started',
+    children: [{ name: 'Introduction', path: '/getting-started/introduction' }],
+  },
+] satisfies MenuItem[]
+
+const firstMenuItem = menu[0]
+//    ^?
+
+type FirstMenuItem = (typeof menu)[number]
+//   ^?
 ```
 
 ## Testing

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

@@ -1,6 +1,6 @@
-import { fabGithub, fabXTwitter } from '@quasar/extras/fontawesome-v6'
-import { slugify } from '@md-plugins/shared'
+import { fabGithub, fabXTwitter } from '@quasar/extras/fontawesome-v7'
 import { version, productName } from '../../package.json'
+import { slugify } from '../.q-press/components/markdown-utils'
 
 export interface SocialLink {
   name: string
@@ -70,6 +70,19 @@ export interface PrivacyConfig {
   link: string
 }
 
+export interface CodepenConfig {
+  cssExternal?: string[]
+  jsExternal?: string[]
+  jsSetup?: string
+  jsPreProcessor?: string
+  titleSuffix?: string
+  head?: string
+  globalPackages?: {
+    packageName: string
+    globalName: string
+  }[]
+}
+
 export interface SiteConfig {
   lang: string
   title: string
@@ -78,6 +91,8 @@ export interface SiteConfig {
   version: string
   copyright: CopyrightConfig
   githubEditRootSrc: string // src folder for github edit links (appended with 'markdown' and 'examples')
+  githubSourceRootSrc?: string // src folder for GitHub source links (appended with 'markdown' and 'examples')
+  codepen?: CodepenConfig
   license: LicenseConfig
   privacy: PrivacyConfig
   logoConfig: LogoConfig
@@ -220,6 +235,13 @@ const mdPluginsMenu: SiteMenuItem = {
         { name: 'Advanced', path: '/md-plugins/link/advanced' },
       ],
     },
+    {
+      name: 'Mermaid',
+      children: [
+        { name: 'Overview', path: '/md-plugins/mermaid/overview' },
+        { name: 'Advanced', path: '/md-plugins/mermaid/advanced' },
+      ],
+    },
     {
       name: 'Table',
       children: [
@@ -286,32 +308,39 @@ const QuasarAppExts: SiteMenuItem = {
   ],
 }
 
-const guidesMenu: SiteMenuItem = {
-  name: 'Guides',
+const otherMenu: SiteMenuItem = {
+  name: 'Other',
   mq: 1100, // media query breakpoint
   children: [
+    {
+      name: 'Releases',
+      path: '/other/releases',
+    },
     {
       name: 'Upgrade Guide',
-      path: '/guides/upgrade-guide',
+      path: '/other/upgrade-guide',
     },
     {
       name: 'FAQ',
-      path: '/guides/faq',
+      path: '/other/faq',
     },
     {
-      name: 'Contributing',
-      path: '/guides/contributing',
+      name: 'Contact',
+      path: '/other/contact',
     },
-  ],
-}
-
-const otherMenu: SiteMenuItem = {
-  name: 'Other',
-  mq: 1190, // media query breakpoint
-  children: [
     {
-      name: 'Releases',
-      path: '/other/release-notes',
+      name: 'Contributing',
+      children: [
+        { name: 'Overview', path: '/other/contributing/overview' },
+        {
+          name: 'Bugs and Feature Requests',
+          path: '/other/contributing/bugs-and-feature-requests',
+        },
+        { name: 'Packages', path: '/other/contributing/packages' },
+        { name: 'Documentation', path: '/other/contributing/documentation' },
+        { name: 'Call to Action', path: '/other/contributing/call-to-action' },
+        { name: 'Sponsor', path: '/other/contributing/sponsor' },
+      ],
     },
   ],
 }
@@ -337,11 +366,11 @@ const processedQuasarAppExts = {
   children: QuasarAppExts.children ? QuasarAppExts.children.map(processMenuItem) : [],
 }
 
-const processedGuidesMenu = {
-  name: guidesMenu.name,
-  path: slugify(guidesMenu.name),
+const processedOtherMenu = {
+  name: otherMenu.name,
+  path: slugify(otherMenu.name),
   expanded: false,
-  children: guidesMenu.children ? guidesMenu.children.map(processMenuItem) : [],
+  children: otherMenu.children ? otherMenu.children.map(processMenuItem) : [],
 }
 
 const secondaryToolbarLinks = [
@@ -349,7 +378,6 @@ const secondaryToolbarLinks = [
   mdPluginsMenu,
   vitePluginsMenu,
   QuasarAppExts,
-  guidesMenu,
   otherMenu,
 ]
 
@@ -376,7 +404,7 @@ export const sidebar = [
   processedMdPluginsMenu,
   processedVitePluginsMenu,
   processedQuasarAppExts,
-  processedGuidesMenu,
+  processedOtherMenu,
 ]
 
 const config = {
@@ -391,6 +419,7 @@ const config = {
     line2: '',
   } as CopyrightConfig,
   githubEditRootSrc: 'https://github.com/md-plugins/md-plugins/edit/dev/packages/docs/src/',
+  githubSourceRootSrc: 'https://github.com/md-plugins/md-plugins/tree/dev/packages/docs/src/',
   license: {
     label: 'MIT License',
     link: 'https://github.com/md-plugins/md-plugins/blob/dev/LICENSE.md',

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

@@ -6,7 +6,7 @@
   "props": {
     "code": {
       "type": "String",
-      "desc": "The code to display",
+      "desc": "The code to display with Shiki syntax highlighting",
       "examples": [
         "'const a = 1;'",
         "'<div>Hello World</div>'"
@@ -34,4 +34,4 @@
       "category": "content"
     }
   }
-}
+}

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

@@ -4,18 +4,15 @@
     "docsUrl": "https://path-to-your-docs/markdown-codepen"
   },
   "props": {
-    "active": {
-      "type": "Boolean",
-      "desc": "Flag to indicate if the form should be active",
-      "category": "state"
-    },
-    "options": {
+    "title": {
       "type": "String",
-      "desc": "JSON string containing the CodePen options",
+      "desc": "Title used for the generated CodePen",
+      "required": true,
       "examples": [
-        "'{\"title\":\"My Pen\",\"html\":\"<div>Hello World</div>\"}'"
+        "'Basic Example'",
+        "'Advanced Playground'"
       ],
       "category": "content"
     }
   }
-}
+}

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

@@ -13,10 +13,35 @@
       ],
       "category": "content"
     },
+    "file": {
+      "type": "String",
+      "desc": "Vue example file name without the .vue extension",
+      "required": true,
+      "examples": [
+        "'Basic'",
+        "'AdvancedUsage'"
+      ],
+      "category": "content"
+    },
+    "noEdit": {
+      "type": "Boolean",
+      "desc": "Hide the CodePen edit button",
+      "category": "behavior"
+    },
     "noGithub": {
       "type": "Boolean",
-      "desc": "Flag to indicate if the GitHub button should be hidden",
+      "desc": "Hide the GitHub source button",
+      "category": "behavior"
+    },
+    "scrollable": {
+      "type": "Boolean",
+      "desc": "Constrain the example content to a scrollable area",
+      "category": "content"
+    },
+    "overflow": {
+      "type": "Boolean",
+      "desc": "Allow the example content to manage overflow automatically",
       "category": "behavior"
     }
   }
-}
+}