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

package/dist/templates/init/src/markdown/other/contributing/documentation.md

@@ -0,0 +1,31 @@
+---
+title: Documentation
+desc: Contribute to the documentation
+keys: Contributing
+---
+
+Documentation improvements are welcome. MD-Plugins includes docs for individual Markdown plugins, Vite plugins, and Q-Press.
+
+## Editing Pages
+
+The easiest way to edit a page is with the **Edit this page on GitHub** link that appears near the bottom of most pages. That opens the exact source file on GitHub so you can propose the change with a pull request.
+
+You can also fork the repository, edit the markdown files locally, and open a pull request.
+
+## Writing Guidelines
+
+Please keep this in mind when writing MD-Plugins docs:
+
+- Speak directly to the user.
+- Keep sentences and paragraphs focused.
+- Prefer examples that can be copied into real projects.
+- Mention package names and commands explicitly.
+- Update related pages when a change affects more than one package.
+
+## Local Verification
+
+When changing docs, run:
+
+```bash
+pnpm --filter mdplugins_docs build
+```

package/dist/templates/init/src/markdown/other/contributing/overview.md

@@ -0,0 +1,41 @@
+---
+title: Overview
+desc: Innovation through collaboration
+keys: Contributing
+---
+
+Interested in contributing to MD-Plugins? Here's how you can contribute.
+
+## Working Together
+
+MD-Plugins is free to use under the MIT License. The project grows through feedback, documentation, tests, examples, bug reports, and pull requests from people using it in real projects.
+
+Contributions are not limited to code. We welcome:
+
+- Bug reports and reproductions.
+- Documentation fixes.
+- Examples that show practical usage.
+- Tests for Markdown plugins and Q-Press behavior.
+- Pull requests that improve the developer experience.
+
+## Working In The Open
+
+MD-Plugins lives on [GitHub](https://github.com/md-plugins/md-plugins). Work, discussion, issues, bugs, features, improvements, and comments happen in public so everyone can follow along.
+
+If you notice something that could be improved, you have two good options:
+
+1. Open an issue for the request. We'll review it and help decide the next step.
+
+2. Begin the work yourself and contribute it back with a pull request. Works-in-progress are welcome, especially when the direction would benefit from early feedback.
+
+If working with GitHub sounds like a lot, check out this [free video series](https://app.egghead.io/playlists/how-to-contribute-to-an-open-source-project-on-github).
+
+## Before You Start
+
+Before submitting a pull request, run the checks that match your change:
+
+```bash
+pnpm check:all
+```
+
+Thanks for helping make MD-Plugins better for everyone.

package/dist/templates/init/src/markdown/other/contributing/packages.md

@@ -0,0 +1,28 @@
+---
+title: Packages
+desc: How to contribute to MD-Plugins packages
+keys: Contributing
+---
+
+MD-Plugins is a package collection. Contributions can target Markdown-it plugins, Vite plugins, the Q-Press app extension, shared utilities, docs templates, examples, tests, or release tooling.
+
+## What To Include
+
+Package contributions are strongest when they include:
+
+- A short rationale that explains the user problem.
+- Tests for behavior changes.
+- Documentation updates when public behavior changes.
+- Examples when the feature is easier to understand visually.
+- Migration notes when existing users need to change code.
+
+## First Steps
+
+Open an issue or discussion before larger work. Include a detailed description that explains:
+
+- Which package is affected.
+- Whether the change is a fix, feature, refactor, or documentation update.
+- How the change should behave.
+- Any compatibility or release concerns.
+
+This gives maintainers and users a place to weigh in before the pull request lands.

package/dist/templates/init/src/markdown/other/contributing/sponsor.md

@@ -0,0 +1,23 @@
+---
+title: Sponsor
+desc: About sponsoring MD-Plugins
+keys: Contributing
+---
+
+## Sponsorship
+
+MD-Plugins is free and open-source software. If it saves you time or helps your team ship documentation, consider supporting ongoing maintenance.
+
+Financial support helps make room for:
+
+- Package maintenance.
+- Compatibility updates for Quasar, Vite, Vue, and Markdown-it.
+- Documentation improvements.
+- Examples and playground support.
+- Bug fixes and release work.
+
+## Support Options
+
+GitHub Sponsors: [https://github.com/sponsors/hawkeye64](https://github.com/sponsors/hawkeye64)
+
+PayPal: [https://paypal.me/hawkeye64](https://paypal.me/hawkeye64)

package/dist/templates/init/src/markdown/other/faq.md

@@ -0,0 +1,179 @@
+---
+title: Frequently Asked Questions
+desc: Common questions and answers about MD-Plugins.
+keys: Other
+---
+
+Use this page to quickly scan the questions people tend to ask while setting up MD-Plugins, Q-Press, and the direct Vite plugins.
+
+## General
+
+:::details Q. What are MD-Plugins?
+
+**A.** MD-Plugins are Markdown-it and Vite plugins that help turn Markdown into application-ready content. They cover things like headings, links, frontmatter, images, code blocks, examples, and Q-Press documentation sites.
+:::
+
+:::details Q. Can I use MD-Plugins without Quasar?
+
+**A.** Yes. The individual Markdown-it plugins and direct Vite plugins can be used in non-Quasar projects. For example, `@md-plugins/vite-md-plugin` and `@md-plugins/vite-examples-plugin` can be used in Vue/Vite projects, and the `@md-plugins/md-plugin-*` packages can be used anywhere you configure MarkdownIt.
+
+The Quasar-specific limitation only applies to app extensions, such as Q-Press. Those app extensions target Quasar CLI Vite projects and are not intended for Webpack or JavaScript-only Quasar projects.
+:::
+
+:::details Q. Which package should I start with?
+
+**A.** Use `@md-plugins/quasar-app-extension-q-press` if you want the full Q-Press documentation site experience inside a Quasar CLI Vite project.
+
+Use `@md-plugins/vite-md-plugin` if you want Markdown pages or content in a Vue/Vite app without installing the Q-Press app extension.
+
+Use the individual `@md-plugins/md-plugin-*` packages when you already own the MarkdownIt setup and only need specific behavior.
+:::
+
+## Installation And Updates
+
+:::details Q. How do I install MD-Plugins?
+
+**A.** Install the package that matches your integration path. For direct Vite plugin usage:
+
+```tabs
+<<| bash pnpm |>>
+pnpm add @md-plugins/vite-md-plugin@beta
+<<| bash Bun |>>
+bun add @md-plugins/vite-md-plugin@beta
+<<| bash Yarn |>>
+yarn add @md-plugins/vite-md-plugin@beta
+<<| bash npm |>>
+npm install @md-plugins/vite-md-plugin@beta
+```
+
+For Q-Press in a Quasar CLI Vite project:
+
+```bash
+quasar ext add @md-plugins/q-press@beta
+```
+
+Refer to the installation section for each package when you need package-specific options.
+:::
+
+:::details Q. How do I update an existing Q-Press project?
+
+**A.** Update the app extension package, then invoke it so the generated files can be refreshed:
+
+```bash
+pnpm up @md-plugins/quasar-app-extension-q-press@beta
+quasar ext invoke @md-plugins/q-press
+```
+
+Choose `Overwrite All` if you want the generated `src/.q-press` files to match the current beta templates.
+:::
+
+:::details Q. Does Q-Press support Webpack projects?
+
+**A.** No. Q-Press targets Quasar CLI Vite projects. The direct Markdown-it and Vite plugin packages are the right path for non-Quasar Vite projects.
+:::
+
+## Plugin Usage
+
+:::details Q. How do I add custom classes to images?
+
+**A.** Use the image plugin and pass the class through its options:
+
+```ts
+import MarkdownIt from 'markdown-it'
+import { imagePlugin } from '@md-plugins/md-plugin-image'
+
+const md = new MarkdownIt()
+
+md.use(imagePlugin, {
+  imageClass: 'custom-image-class',
+})
+```
+
+:::
+
+:::details Q. How do I extract and process frontmatter content?
+
+**A.** Use the frontmatter plugin and read the generated frontmatter from the MarkdownIt environment:
+
+```ts
+import MarkdownIt from 'markdown-it'
+import { frontmatterPlugin } from '@md-plugins/md-plugin-frontmatter'
+
+const md = new MarkdownIt()
+
+md.use(frontmatterPlugin, {
+  grayMatterOptions: {
+    excerpt: true,
+    excerpt_separator: '<!-- more -->',
+  },
+  renderExcerpt: true,
+})
+
+const env = {}
+const html = md.render(code, env)
+
+console.log(env.frontmatter)
+```
+
+:::
+
+:::details Q. How do I enhance code block rendering?
+
+**A.** Use the codeblocks plugin. It can render syntax-highlighted code blocks, copy buttons, tabbed code blocks, line highlighting, and code-group metadata:
+
+```ts
+import MarkdownIt from 'markdown-it'
+import { codeblocksPlugin } from '@md-plugins/md-plugin-codeblocks'
+
+const md = new MarkdownIt()
+
+md.use(codeblocksPlugin, {
+  defaultLang: 'javascript',
+  containerComponent: 'MarkdownPrerender',
+  copyButtonComponent: 'MarkdownCopyButton',
+})
+```
+
+:::
+
+:::details Q. How do I convert Markdown links into Vue components?
+
+**A.** Use the link plugin to render Markdown links as Vue routing components:
+
+```ts
+import MarkdownIt from 'markdown-it'
+import { linkPlugin } from '@md-plugins/md-plugin-link'
+
+const md = new MarkdownIt()
+
+md.use(linkPlugin, {
+  linkTag: 'RouterLink',
+  linkToKeyword: 'to',
+  pageScript: 'import { RouterLink } from "vue-router"',
+})
+```
+
+:::
+
+## Troubleshooting
+
+:::details Q. My Markdown content is not rendering correctly. What should I check first?
+
+**A.** Confirm that the package is installed, the plugin is registered with MarkdownIt or Vite, and your generated Q-Press files are current. If you recently upgraded Q-Press, run:
+
+```bash
+quasar ext invoke @md-plugins/q-press
+```
+
+Choose `Overwrite All` when you want the generated files to match the latest templates.
+:::
+
+:::details Q. How do I report a bug or request a feature?
+
+**A.** Open an issue in the MD-Plugins repository and include the package name, version, reproduction steps, expected result, and actual result.
+:::
+
+:::details Q. Where can I get support?
+
+**A.** Start with the package documentation and FAQ. If you are blocked or found a bug, open a GitHub issue with enough detail for someone else to reproduce the problem.
+:::

package/dist/templates/init/src/markdown/other/releases.md

@@ -0,0 +1,11 @@
+---
+title: Releases
+desc: The latest MD-Plugins releases
+keys: Other
+---
+
+<script import>
+import GitHubReleases from '@/components/page-parts/releases/GitHubReleases.vue'
+</script>
+
+<GitHubReleases class="q-mt-sm" />

package/dist/templates/init/src/markdown/other/upgrade-guide.md

@@ -0,0 +1,165 @@
+---
+title: Upgrade Guide
+desc: Upgrade MD-Plugins and Q-Press to the 0.1.0 beta.
+keys: Other
+related:
+  - quasar-app-extensions/qpress/overview
+  - quasar-app-extensions/vite-md-plugin-app-ext/overview
+  - vite-plugins/vite-md-plugin/overview
+---
+
+The `0.1.0` beta line moves the Quasar app extensions, including Q-Press, to the Quasar CLI Vite 3 beta toolchain. It is the right version to use when your Quasar application is being upgraded to `@quasar/app-vite` `>=3.0.0-beta.33`.
+
+::: warning
+Q-Press and the Quasar app extension packages now target Quasar Vite projects using `@quasar/app-vite` `>=3.0.0-beta.33`. They are not intended for Webpack projects or JavaScript-only Quasar projects.
+:::
+
+::: tip
+The core Markdown-it plugins and direct Vite plugins are not Quasar-only. You can use packages such as `@md-plugins/vite-md-plugin`, `@md-plugins/vite-examples-plugin`, and the individual `@md-plugins/md-plugin-*` packages in Vue/Vite projects without installing a Quasar app extension.
+:::
+
+## Before You Upgrade
+
+- For Q-Press or the Quasar app extensions, make sure your app is already on a Quasar Vite setup.
+- For Q-Press or the Quasar app extensions, upgrade the app to `@quasar/app-vite` `>=3.0.0-beta.33`.
+- Use TypeScript in the consuming Quasar project when using the Quasar app extensions.
+- Import `defineConfig` in `quasar.config.ts` directly from `@quasar/app-vite`.
+- Use `/// <reference types="@quasar/app-vite/client" />` in `src/env.d.ts`.
+- Commit or stash local changes before invoking Q-Press, because the update flow can overwrite files in `src/.q-press`.
+
+## Update Packages
+
+For Q-Press projects, update the app extension package and then invoke it:
+
+```tabs
+<<| bash pnpm |>>
+pnpm up @md-plugins/quasar-app-extension-q-press@beta
+<<| bash npm |>>
+npm install @md-plugins/quasar-app-extension-q-press@beta
+<<| bash yarn |>>
+yarn add @md-plugins/quasar-app-extension-q-press@beta
+<<| bash bun |>>
+bun add @md-plugins/quasar-app-extension-q-press@beta
+```
+
+Then invoke the app extension:
+
+```bash
+quasar ext invoke @md-plugins/q-press
+```
+
+When prompted, choose `Overwrite All` if you want the generated Q-Press files to match the beta templates.
+
+For direct Vite plugin usage, update the packages you consume:
+
+```tabs
+<<| bash pnpm |>>
+pnpm up @md-plugins/vite-md-plugin@beta @md-plugins/vite-examples-plugin@beta
+<<| bash npm |>>
+npm install @md-plugins/vite-md-plugin@beta @md-plugins/vite-examples-plugin@beta
+<<| bash yarn |>>
+yarn add @md-plugins/vite-md-plugin@beta @md-plugins/vite-examples-plugin@beta
+<<| bash bun |>>
+bun add @md-plugins/vite-md-plugin@beta @md-plugins/vite-examples-plugin@beta
+```
+
+## Remove App-Level Shared Imports
+
+Q-Press applications should not install or import `@md-plugins/shared` directly. The shared package remains part of the MD-Plugins internals, but app-level Q-Press files should use the helpers generated into the app.
+
+If your project has this dependency, remove it from the consuming app:
+
+```bash
+pnpm remove @md-plugins/shared
+# or
+npm uninstall @md-plugins/shared
+# or
+yarn remove @md-plugins/shared
+# or
+bun remove @md-plugins/shared
+```
+
+If you have customized generated files and cannot choose `Overwrite All`, update copied Q-Press files that import `slugify` from `@md-plugins/shared`.
+
+Use the local helper from `src/.q-press/components/markdown-utils.ts` instead:
+
+```ts
+import { slugify } from './markdown-utils'
+```
+
+For files outside `src/.q-press/components`, import from the generated helper path used by that file. For example:
+
+```ts
+import { slugify } from '@/.q-press/components/markdown-utils'
+```
+
+or:
+
+```ts
+import { slugify } from '../.q-press/components/markdown-utils'
+```
+
+## Q-Press Type Globals
+
+Q-Press now provides its shared Markdown, menu and `ImportMeta` globals directly from the app extension package. After upgrading to this release line and running `quasar prepare`, projects no longer need to keep a local `src/q-press.globals.d.ts` file.
+
+If you still see type errors for `TocMenuItem`, `MenuItem`, `MarkdownModule`, `import.meta.glob` or Quasar `import.meta.env` values, run:
+
+```bash
+quasar prepare
+```
+
+Then make sure the app is using the updated `@md-plugins/quasar-app-extension-q-press` package.
+
+## Environment Variable Changes
+
+Quasar CLI Vite 3 exposes runtime flags through `import.meta.env`. If you copied older Q-Press internals into your own code, update them:
+
+| Old pattern                   | New pattern                              |
+| ----------------------------- | ---------------------------------------- |
+| `process.env.CLIENT`          | `import.meta.env.QUASAR_CLIENT`          |
+| `process.env.SERVER`          | `import.meta.env.QUASAR_SERVER`          |
+| `process.env.DEV`             | `import.meta.env.QUASAR_DEV`             |
+| `process.env.PROD`            | `import.meta.env.QUASAR_PROD`            |
+| `process.env.VUE_ROUTER_MODE` | `import.meta.env.QUASAR_VUE_ROUTER_MODE` |
+| `process.env.VUE_ROUTER_BASE` | `import.meta.env.QUASAR_VUE_ROUTER_BASE` |
+
+Q-Press also uses `QCLI_*` values for Quasar CLI provided build-time values, such as search index and filesystem paths.
+
+## Example Action Updates
+
+The beta templates include updated example actions for GitHub source links and CodePen playgrounds. If your project keeps customized Q-Press files, compare your copies of these files with the current template:
+
+- `src/.q-press/components/MarkdownExample.vue`
+- `src/.q-press/components/MarkdownCodepen.vue`
+- `src/.q-press/components/markdown-utils.ts`
+- `src/siteConfig/index.ts`
+
+Set `siteConfig.githubSourceRootSrc` when the source-view link should point at generated example files instead of edit links. Configure `siteConfig.codepen` when examples need external CSS, JavaScript, setup code, package globals or a project-specific `titleSuffix`.
+
+## Vite Plugin Configuration
+
+`viteMdPlugin` should be configured with an options object:
+
+```ts
+import { viteMdPlugin, type MenuItem } from '@md-plugins/vite-md-plugin'
+
+vitePlugins: [
+  viteMdPlugin({
+    path: ctx.appPaths.srcDir + '/markdown',
+    menu: sidebar as MenuItem[],
+  }),
+]
+```
+
+## Verify The Upgrade
+
+Run these checks in the consuming app:
+
+```bash
+pnpm install
+quasar prepare
+quasar build
+```
+
+If you use linting or formatting, run those checks after invoking Q-Press so any regenerated files are included.

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

@@ -57,11 +57,13 @@ import AvatarApi from 'quasar/dist/api/QAvatar.json'
 
 ### 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 |>>
@@ -79,8 +81,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,
+        },
+      ],
     }
   }
 }

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

@@ -8,33 +8,31 @@ Q-Press has a lot of components that can be used in your app. Under the hood, th
 ## Components
 
 <script import>
-import DarkModeToggleApi from 'src/.q-press/api/components/DarkModeToggle.json'
-import MarkdownApiApi from 'src/.q-press/api/components/MarkdownApi.json'
-import MarkdownCardLinkApi from 'src/.q-press/api/components/MarkdownCardLink.json'
-import MarkdownCardTitleApi from 'src/.q-press/api/components/MarkdownCardTitle.json'
-import MarkdownCodeApi from 'src/.q-press/api/components/MarkdownCode.json'
-import MarkdownCodepenApi from 'src/.q-press/api/components/MarkdownCodepen.json'
-
-import MarkdownCodePrismApi from 'src/.q-press/api/components/MarkdownCodePrism.json'
-import MarkdownCopyButtonApi from 'src/.q-press/api/components/MarkdownCopyButton.json'
-import MarkdownDrawerSidebarApi from 'src/.q-press/api/components/MarkdownDrawerSidebar.json'
-import MarkdownDrawerTocApi from 'src/.q-press/api/components/MarkdownDrawerToc.json'
-
-import MarkdownExampleApi from 'src/.q-press/api/components/MarkdownExample.json'
-import MarkdownHeaderApi from 'src/.q-press/api/components/MarkdownHeader.json'
-import MarkdownHeaderIconLinksApi from 'src/.q-press/api/components/MarkdownHeaderIconLinks.json'
-import MarkdownHeaderMenuApi from 'src/.q-press/api/components/MarkdownHeaderMenu.json'
-import MarkdownHeaderTextLinksApi from 'src/.q-press/api/components/MarkdownHeaderTextLinks.json'
-
-import MarkdownLayoutApi from 'src/.q-press/api/components/MarkdownLayout.json'
-import MarkdownLinkApi from 'src/.q-press/api/components/MarkdownLink.json'
-import MarkdownPageApi from 'src/.q-press/api/components/MarkdownPage.json'
-import MarkdownPageFooterApi from 'src/.q-press/api/components/MarkdownPageFooter.json'
-import MarkdownPageSidebarApi from 'src/.q-press/api/components/MarkdownPageSidebar.json'
-import MarkdownPageTocApi from 'src/.q-press/api/components/MarkdownPageToc.json'
-
-import MarkdownTreeApi from 'src/.q-press/api/components/MarkdownTree.json'
-import MarkdownPrerenderApi from 'src/.q-press/api/components/MarkdownPrerender.json'
+import DarkModeToggleApi from '@/.q-press/api/components/DarkModeToggle.json'
+import MarkdownApiApi from '@/.q-press/api/components/MarkdownApi.json'
+import MarkdownCardLinkApi from '@/.q-press/api/components/MarkdownCardLink.json'
+import MarkdownCardTitleApi from '@/.q-press/api/components/MarkdownCardTitle.json'
+import MarkdownCodeApi from '@/.q-press/api/components/MarkdownCode.json'
+import MarkdownCodepenApi from '@/.q-press/api/components/MarkdownCodepen.json'
+import MarkdownCopyButtonApi from '@/.q-press/api/components/MarkdownCopyButton.json'
+import MarkdownDrawerSidebarApi from '@/.q-press/api/components/MarkdownDrawerSidebar.json'
+import MarkdownDrawerTocApi from '@/.q-press/api/components/MarkdownDrawerToc.json'
+
+import MarkdownExampleApi from '@/.q-press/api/components/MarkdownExample.json'
+import MarkdownHeaderApi from '@/.q-press/api/components/MarkdownHeader.json'
+import MarkdownHeaderIconLinksApi from '@/.q-press/api/components/MarkdownHeaderIconLinks.json'
+import MarkdownHeaderMenuApi from '@/.q-press/api/components/MarkdownHeaderMenu.json'
+import MarkdownHeaderTextLinksApi from '@/.q-press/api/components/MarkdownHeaderTextLinks.json'
+
+import MarkdownLayoutApi from '@/.q-press/api/components/MarkdownLayout.json'
+import MarkdownLinkApi from '@/.q-press/api/components/MarkdownLink.json'
+import MarkdownPageApi from '@/.q-press/api/components/MarkdownPage.json'
+import MarkdownPageFooterApi from '@/.q-press/api/components/MarkdownPageFooter.json'
+import MarkdownPageSidebarApi from '@/.q-press/api/components/MarkdownPageSidebar.json'
+import MarkdownPageTocApi from '@/.q-press/api/components/MarkdownPageToc.json'
+
+import MarkdownTreeApi from '@/.q-press/api/components/MarkdownTree.json'
+import MarkdownPrerenderApi from '@/.q-press/api/components/MarkdownPrerender.json'
 
 </script>
 
@@ -44,8 +42,6 @@ import MarkdownPrerenderApi from 'src/.q-press/api/components/MarkdownPrerender.
 <MarkdownApi :api="MarkdownCardTitleApi" name="MarkdownCardTitle"/>
 <MarkdownApi :api="MarkdownCodeApi" name="MarkdownCode"/>
 <MarkdownApi :api="MarkdownCodepenApi" name="MarkdownCodepen"/>
-
-<MarkdownApi :api="MarkdownCodePrismApi" name="MarkdownCodePrism"/>
 <MarkdownApi :api="MarkdownCopyButtonApi" name="MarkdownCopyButton"/>
 <!-- No <MarkdownApi :api="MarkdownDrawerSidebarApi" name="MarkdownDrawerSidebar"/> -->
 <!-- No <MarkdownApi :api="MarkdownDrawerTocApi" name="MarkdownDrawerToc"/> -->