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

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

@@ -6,7 +6,7 @@ desc: Q-Press App-Extension for Quasar.
 The Q-Press App Extension is a powerful tool for Quasar developers that simplifies the integration of Markdown content into Quasar applications. It leverages the capabilities of Vite and various Markdown plugins to transform Markdown files into Vue components, enabling a seamless and efficient workflow for content management.
 
 ::: warning
-Q-Press is for Quasar Vite projects using `@quasar/app-vite` `>=3.0.0-beta.14` at this time. TypeScript processing is also required. Do not use if you are using Webpack or have a JavaScript-only project.
+Q-Press is for Quasar Vite projects using `@quasar/app-vite` `>=3.0.0-beta.33` at this time. TypeScript processing is also required. Do not use if you are using Webpack or have a JavaScript-only project.
 :::
 
 ::: tip
@@ -33,14 +33,12 @@ quasar ext add @md-plugins/q-press
 
 - **New Install:**
   - `src/.q-press`
-  - `src/q-press.globals.d.ts`
   - `src/components`
   - `src/markdown`
   - `src/examples`
   - `src/siteConfig`
 - **Update Install:**
   - `src/.q-press`
-  - `src/q-press.globals.d.ts`
 
 ### Additional Dependencies
 
@@ -49,21 +47,25 @@ quasar ext add @md-plugins/q-press
 ```tabs
 <<| bash pnpm |>>
 pnpm i -D markdown-it @types/markdown-it
+<<| bash bun |>>
+bun add -d markdown-it @types/markdown-it
 <<| bash yarn |>>
 yarn add -D markdown-it @types/markdown-it
 <<| bash npm |>>
 npm i -D markdown-it @types/markdown-it
 ```
 
-2. **Add `prismjs` to your project dependencies:**
+2. **Q-Press adds `shiki` to your project dependencies when invoked. If you are wiring the generated files manually, add it yourself:**
 
 ```tabs
 <<| bash pnpm |>>
-pnpm add prismjs
+pnpm add shiki
+<<| bash bun |>>
+bun add shiki
 <<| bash yarn |>>
-yarn add prismjs
+yarn add shiki
 <<| bash npm |>>
-npm i prismjs
+npm i shiki
 ```
 
 ## Configuration
@@ -86,8 +88,6 @@ Import Q-Press styles:
 
 ```scss
 @import '../.q-press/css/app.scss';
-@import '../.q-press/css/fonts.scss';
-@import '../.q-press/css/prism-theme.scss';
 ```
 
 ### Modify `quasar.config.ts`
@@ -125,12 +125,12 @@ export default defineConfig(async (ctx) => {
 
 ```ts [maxheight=400px]
 import type { RouteRecordRaw } from 'vue-router'
-import mdPageList from 'src/markdown/listing'
+import mdPageList from '@/markdown/listing'
 
 const routes = [
   {
     path: '/',
-    component: () => import('src/.q-press/layouts/MarkdownLayout.vue'),
+    component: () => import('@/.q-press/layouts/MarkdownLayout.vue'),
     children: [
       // Include the Landing Page route first
       ...Object.entries(mdPageList)
@@ -169,7 +169,7 @@ const routes = [
   // but you can also remove it
   {
     path: '/:catchAll(.*)*',
-    component: () => import('pages/ErrorNotFound.vue'),
+    component: () => import('@/pages/ErrorNotFound.vue'),
   },
 ] as RouteRecordRaw[]
 
@@ -186,7 +186,7 @@ Update your `App.vue`:
 </template>
 
 <script setup lang="ts">
-  import { useDark } from 'src/.q-press/composables/dark'
+  import { useDark } from '@/.q-press/composables/dark'
   const { initDark } = useDark()
   initDark()
 </script>
@@ -206,7 +206,7 @@ Update your `App.vue`:
 <script setup lang="ts">
 // don't forget to add the Quasar 'Meta' plugin into your quasar.config file!
 import { useMeta } from 'quasar'
-import getMeta from 'src/.q-press/assets/get-meta'
+import getMeta from '@/.q-press/assets/get-meta'
 
 // You can use the `getMeta` function to get the meta tags for your page and provide default values
 useMeta({
@@ -230,16 +230,16 @@ useMeta({
 If you copied older Q-Press internals into your app, update the common cases below:
 
 ```ts
-process.env.CLIENT            // old
+process.env.CLIENT // old
 import.meta.env.QUASAR_CLIENT // new
 
-process.env.DEV               // old
-import.meta.env.DEV           // new
+process.env.DEV // old
+import.meta.env.DEV // new
 
-process.env.FS_QUASAR_FOLDER      // old
+process.env.FS_QUASAR_FOLDER // old
 import.meta.env.QCLI_FS_QUASAR_FOLDER // new
 
-process.env.SEARCH_INDEX      // old
+process.env.SEARCH_INDEX // old
 import.meta.env.QCLI_SEARCH_INDEX // new
 ```
 
@@ -313,7 +313,7 @@ If you don't have a `.prettierignore` file, create one in the root of your proje
 
 ## Updating
 
-When you update, only the `src/.q-press` folder will be updated as well as the file `src/q-press.globals.d.ts`. If you want to re-install everything, just remove the `src/siteConfig` folder.
+When you update, only the `src/.q-press` folder will be updated. If you want to re-install everything, just remove the `src/siteConfig` folder.
 
 To make it easier to update, you can use the following command:
 

package/dist/templates/init/src/markdown/quasar-app-extensions/qpress/site-config.md

@@ -52,7 +52,6 @@ const secondaryToolbarLinks = [
   mdPluginsMenu, // <-- this is the menu we just created
   vitePluginsMenu,
   QuasarAppExts,
-  guidesMenu,
   otherMenu,
 ]
 ```
@@ -61,7 +60,7 @@ const secondaryToolbarLinks = [
 
 A `MenuItem` looks like this, but not all options are used for header menus:
 
-```ts
+```ts [twoslash]
 interface MenuItem {
   name: string
   path?: string
@@ -74,6 +73,21 @@ interface MenuItem {
   external?: boolean
   expanded?: boolean
 }
+
+const docsMenu = {
+  name: 'Guides',
+  expanded: true,
+  children: [
+    { name: 'Installation', path: '/getting-started/installation' },
+    { name: 'Themes', path: '/quasar-app-extensions/qpress/themes' },
+  ],
+} satisfies MenuItem
+
+const firstDocLink = docsMenu.children[0]
+//    ^?
+
+type MenuChildren = NonNullable<MenuItem['children']>
+//   ^?
 ```
 
 ## Sidebar Menu Items
@@ -105,7 +119,7 @@ export const sidebar = [
   processedMdPluginsMenu, // <-- this is the menu we just created
   processedVitePluginsMenu,
   processedQuasarAppExts,
-  processedGuidesMenu,
+  processedOtherMenu,
 ]
 ```
 

package/dist/templates/init/src/markdown/quasar-app-extensions/qpress/themes.md

@@ -3,27 +3,44 @@ title: Q-Press Themes
 desc: Themes for Q-Press App-Extension for Quasar.
 ---
 
-Currently, there are five themes available for **Q-Press**:
+Currently, there are six themes available for **Q-Press**:
 
 - **Default**
+- **Evergreen**
 - **Mystic**
 - **Newspaper**
 - **Sunrise**
 - **Tawny**
 
-To use a theme, simply add the following line to your `src/css/quasar.variables.(scss|sass)` file:
+## Theme Gallery
 
-```scss
+Each preview below is wrapped in a `qpress-theme-preview` namespace. That means the gallery can show every bundled theme at once without importing every theme file or overriding the active site theme.
+
+<script import>
+import QPressThemeGallery from '@/components/QPressThemeGallery.vue'
+</script>
+
+<QPressThemeGallery />
+
+To use a theme, add the import to your `src/css/quasar.variables.scss` or `src/css/quasar.variables.sass` file:
+
+```tabs
+<<| scss SCSS |>>
 @import '../.q-press/css/themes/sunrise.scss';
+<<| sass Sass |>>
+@import '../.q-press/css/themes/sunrise.scss'
 ```
 
-This will load the `sunrise` theme into your **Q-Press** enabled app.
+This will load the `sunrise` theme into your **Q-Press** enabled app. Q-Press themes are shipped as `.scss` files, but they can be imported from either SCSS or Sass syntax.
+
+Import only one Q-Press theme, then add any project-specific overrides below that import. This keeps the theme variables predictable while still letting you tune colors, typography, and spacing for your site.
 
 ## Custom Themes
 
-If you want to build your own theme, add these variables to your `src/css/quasar.variables.(scss|sass)` file and modify them to your liking:
+If you want to build your own theme, add these variables to your `src/css/quasar.variables.scss` or `src/css/quasar.variables.sass` file and modify them to your liking:
 
-```scss
+```tabs
+<<| scss SCSS |>>
 @use 'sass:color';
 
 $primary: #214466;
@@ -59,7 +76,7 @@ $light-pill: $brand-light;
 $light-text: $brand-light-text;
 $light-bg: $brand-light-bg;
 
-$dark-pill: scale-color($brand-primary, $lightness: -80%);
+$dark-pill: scale-color($brand-dark-bg, $lightness: 12%);
 $dark-text: $brand-dark-text;
 $dark-bg: $brand-dark-bg;
 
@@ -91,13 +108,76 @@ $shadow--small: 0 6px 6px 0 rgba($brand-primary, 0.28);
 $header-height: 55px;
 $header-transition: 0.6s cubic-bezier(0.25, 0.8, 0.5, 1);
 $header-quick-transition: 0.28s ease-in-out;
+<<| sass Sass |>>
+@use 'sass:color'
+
+$primary: #214466
+$secondary: #266660
+$accent: #853394
+
+$positive: #2ecc71
+$negative: #ff1732
+$info: #10a0ff
+$warning: #ffd52d
+
+$brand-primary: #00bfff
+$brand-secondary: #4b555c
+$brand-accent: #ea5e13
+$brand-dark: #2c3e50
+$brand-light: #f5f5f5
+$brand-medium: #6b7f86
+$brand-light-text: #4d4d4d
+$brand-light-bg: #fefefe
+$brand-dark-bg: #080e1a
+$brand-dark-text: #cbcbcb
+$brand-light-codeblock-bg: #f5f5f5
+$brand-light-codeblock-text: #4d4d4d
+$brand-dark-codeblock-bg: #121212
+$brand-dark-codeblock-text: #e6e6e6
+
+$header-btn-color--light: #757575
+$header-btn-hover-color--light: #212121
+$header-btn-color--dark: #929397
+$header-btn-hover-color--dark: #fff
+
+$light-pill: $brand-light
+$light-text: $brand-light-text
+$light-bg: $brand-light-bg
+
+$dark-pill: scale-color($brand-dark-bg, $lightness: 12%)
+$dark-text: $brand-dark-text
+$dark-bg: $brand-dark-bg
+
+$separator-color: $brand-accent
+$separator-color-dark: $brand-accent
+
+$font-size: 16px
+$font-size-brand: 16px
+$font-weight-brand: 500
+$font-weight-technical: 400
+$letter-spacing-brand: 0.7px
+
+$font-family-technical: 'Roboto', -apple-system, Avenir, BlinkMacSystemFont, 'Segoe UI', Helvetica, Arial, sans-serif
+$font-family-examples: $font-family-technical
+$font-family-brand: 'Montserrat', $font-family-technical
+
+$shadow--large: 0 24px 24px 0 rgba(0, 179, 255, 0.24)
+$shadow--medium: 0 6px 6px 0 rgba($brand-primary, 0.38)
+$shadow--small: 0 6px 6px 0 rgba($brand-primary, 0.28)
+
+$header-height: 55px
+$header-transition: 0.6s cubic-bezier(0.25, 0.8, 0.5, 1)
+$header-quick-transition: 0.28s ease-in-out
 ```
 
+For custom themes, prefer deriving dark surfaces such as `$dark-pill` from `$brand-dark-bg` instead of `$brand-primary`. Accent colors can become too saturated or too dark when reused as backgrounds or text in dark mode.
+
 ## Media Query Breakpoints
 
-When setting up your menu system, you may need to adjust the media query breakpoints. You can add the following to your `src/css/quasar.variables.(scss|sass)` file:
+When setting up your menu system, you may need to adjust the media query breakpoints. You can add the following to your `src/css/quasar.variables.scss` or `src/css/quasar.variables.sass` file:
 
-```scss
+```tabs
+<<| scss SCSS |>>
 $mq-list:
   375,
   470,
@@ -114,6 +194,7 @@ $mq-list:
   1300 /* drawer */,
   1310,
   1400;
+
 @each $query in $mq-list {
   @media (min-width: #{$query}px) {
     .lt-#{$query} {
@@ -127,4 +208,15 @@ $mq-list:
     }
   }
 }
+<<| sass Sass |>>
+$mq-list: 375, 470, 510, 600, 780, 860, 910, 1000, 1020, 1100, 1130, 1190, 1300, 1310, 1400
+
+@each $query in $mq-list
+  @media (min-width: #{$query}px)
+    .lt-#{$query}
+      display: none
+
+  @media (max-width: #{$query - 1}px)
+    .gt-#{$query}
+      display: none
 ```

package/dist/templates/init/src/markdown/quasar-app-extensions/vite-md-plugin-app-ext/advanced.md

@@ -1,4 +1,162 @@
 ---
 title: ViteMdPluginAppExt Advanced Topics
 desc: Advanced Topics for the ViteMdPluginAppExt.
+related:
+  - vite-plugins/vite-md-plugin/advanced
+  - quasar-app-extensions/qpress/overview
 ---
+
+The `@md-plugins/quasar-app-extension-vite-md-plugin` app extension is intentionally small. It prepares a Quasar Vite app so Markdown files can be treated like Vue files, but your app still owns the Markdown source folder, menu shape, and `viteMdPlugin` options.
+
+::: tip
+If you want a complete documentation site scaffold, use [Q-Press](/quasar-app-extensions/qpress/overview). If you only want Markdown pages inside an existing Quasar app, this app extension is the lighter fit.
+:::
+
+## What the App Extension Changes
+
+On every Quasar dev/build run, the app extension extends `quasar.config` with the browser-side settings Markdown pages need:
+
+```ts
+build: {
+  vueRouterMode: 'history',
+
+  viteVuePluginOptions: {
+    include: [/\.(vue|md)$/],
+  },
+},
+
+framework: {
+  autoImportVueExtensions: ['vue', 'md'],
+},
+```
+
+These settings solve three common problems:
+
+- `vueRouterMode: 'history'` keeps hash links and generated markdown routes predictable.
+- `viteVuePluginOptions.include` lets Vue compile `.md` files as Vue single-file components.
+- `autoImportVueExtensions` lets route files and component imports resolve `.md` files without always spelling out the extension.
+
+## What You Still Configure
+
+The app extension does not generate your docs shell or menu for you. You still install and configure `@md-plugins/vite-md-plugin` in `quasar.config.ts`.
+
+```ts
+import { defineConfig } from '#q-app/wrappers'
+import type { Plugin } from 'vite'
+
+import { viteMdPlugin, type MenuItem } from '@md-plugins/vite-md-plugin'
+import { sidebar } from './src/siteConfig'
+
+export default defineConfig((ctx) => ({
+  build: {
+    vitePlugins: [
+      [
+        viteMdPlugin,
+        {
+          path: ctx.appPaths.srcDir + '/markdown',
+          menu: sidebar as MenuItem[],
+          config: {
+            html: true,
+            linkify: true,
+          },
+        },
+      ] as unknown as Plugin,
+    ],
+  },
+}))
+```
+
+For JavaScript projects, remove the `type` imports and casts. The runtime shape is the same.
+
+## Recommended Folder Shape
+
+A simple Quasar app can keep Markdown content and navigation data close together:
+
+```text
+src/
+  markdown/
+    getting-started/
+      introduction.md
+    guides/
+      routing.md
+  siteConfig/
+    index.ts
+```
+
+Then export the menu from `src/siteConfig/index.ts`:
+
+```ts
+import type { MenuItem } from '@md-plugins/vite-md-plugin'
+
+export const sidebar: MenuItem[] = [
+  {
+    name: 'Getting Started',
+    children: [{ name: 'Introduction', path: '/getting-started/introduction' }],
+  },
+  {
+    name: 'Guides',
+    children: [{ name: 'Routing', path: '/guides/routing' }],
+  },
+]
+```
+
+The `path` values should match the route you expect for the markdown file under the configured Markdown folder.
+
+## Markdown Options
+
+Use the `config` option to tune Markdown-It and the bundled md-plugins.
+
+```ts
+viteMdPlugin({
+  path: ctx.appPaths.srcDir + '/markdown',
+  menu: sidebar,
+  config: {
+    html: true,
+    linkify: true,
+    typographer: true,
+    codeblocks: {
+      defaultLang: 'typescript',
+      preClass: 'markdown-code',
+    },
+    link: {
+      externalTarget: '_blank',
+      externalRel: 'noopener noreferrer',
+    },
+  },
+})
+```
+
+::: warning
+Only enable `html: true` for content you trust. Markdown HTML is powerful, but it also means your markdown authors can inject raw HTML.
+:::
+
+## Routing Notes
+
+The app extension sets `vueRouterMode` to `history` because Q-Press and the Vite markdown plugin rely on stable URLs and hash anchors. If your app is deployed to static hosting, make sure your host rewrites unknown routes back to `index.html`.
+
+For example, Netlify apps usually need:
+
+```toml
+[[redirects]]
+  from = "/*"
+  to = "/index.html"
+  status = 200
+```
+
+## When to Use Q-Press Instead
+
+Choose Q-Press when you want the full docs experience:
+
+- Generated docs layout, header, sidebars, footer, and search.
+- Markdown examples and CodePen generation.
+- API cards using Quasar-style JSON metadata.
+- Themes, release pages, FAQ, and contribution pages.
+
+Choose this app extension when you already have an app shell and only need Markdown files to compile and route cleanly.
+
+## Troubleshooting
+
+- If Markdown imports fail, confirm `viteVuePluginOptions.include` includes `/\.(vue|md)$/`.
+- If routes work locally but fail after refresh in production, add a history fallback on your host.
+- If Markdown pages render but links do not behave like SPA links, check the `link` plugin options and your generated routes.
+- If you recently upgraded Quasar app-vite, run `quasar prepare` so generated Quasar aliases and types are refreshed.

package/dist/templates/init/src/markdown/quasar-app-extensions/vite-md-plugin-app-ext/overview.md

@@ -9,7 +9,7 @@ related:
 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.
 
 ::: warning
-This app extension targets Quasar Vite projects using `@quasar/app-vite` `>=3.0.0-beta.14`.
+This app extension targets Quasar Vite projects using `@quasar/app-vite` `>=3.0.0-beta.33`.
 :::
 
 ## Key Features

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

@@ -84,10 +84,15 @@ export default defineConfig(({ mode }) => {
     ],
     build: {
       chunkSizeWarningLimit: 650,
-      rollupOptions: {
+      rolldownOptions: {
         output: {
-          manualChunks: {
-            vendor: ['vue', 'vite'],
+          codeSplitting: {
+            groups: [
+              {
+                name: (moduleId) =>
+                  /node_modules[\\/](vue|vite)[\\/]/.test(moduleId) ? 'vendor' : null,
+              },
+            ],
           },
         },
       },

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

@@ -18,11 +18,13 @@ The Vite Examples Plugin is a powerful tool that enhances the standard Vite func
 
 ## Installation
 
-You can install the Vite Examples plugin using npm, yarn, or pnpm. Choose your preferred method below:
+You can install the Vite Examples plugin using npm, yarn, pnpm, or bun. Choose your preferred method below:
 
 ```tabs
 <<| bash pnpm |>>
 pnpm add @md-plugins/vite-examples-plugin
+<<| bash bun |>>
+bun add @md-plugins/vite-examples-plugin
 <<| bash yarn |>>
 yarn add @md-plugins/vite-examples-plugin
 <<| bash npm |>>
@@ -40,8 +42,14 @@ extendViteConf(viteConf, { isClient }) {
   if (ctx.prod && isClient) {
     viteConf.build = viteConf.build || {}
     viteConf.build.chunkSizeWarningLimit = 650
-    viteConf.build.rollupOptions = {
-      output: { manualChunks: viteManualChunks },
+    viteConf.build.rolldownOptions = viteConf.build.rolldownOptions || {}
+    viteConf.build.rolldownOptions.output = viteConf.build.rolldownOptions.output || {}
+    viteConf.build.rolldownOptions.output.codeSplitting = {
+      groups: [
+        {
+          name: (moduleId) => viteManualChunks(moduleId) ?? null,
+        },
+      ],
     }
   }
 }
@@ -71,9 +79,15 @@ export default defineConfig(({ mode }) => {
     ],
     build: {
       chunkSizeWarningLimit: 650,
-      rollupOptions: {
+      rolldownOptions: {
         output: {
-          manualChunks: viteManualChunks,
+          codeSplitting: {
+            groups: [
+              {
+                name: (moduleId) => viteManualChunks(moduleId) ?? null,
+              },
+            ],
+          },
         },
       },
     },