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

package/src/templates/init/src/markdown/md-plugins/title/advanced.md

@@ -0,0 +1,88 @@
+---
+title: Title Plugin Advanced Topics
+desc: Title plugin advanced topics for Markdown.
+---
+
+## Title Plugin
+
+The `title` plugin allows you to extract the title from your Markdown content and store it in the `env` object. This section will cover how the plugin works, the available options for customization, and examples of how to use it effectively.
+
+### Type Information
+
+```ts
+import { PluginSimple } from 'markdown-it'
+
+/**
+ * Get markdown page title info
+ *
+ * Extract it into env
+ */
+declare const titlePlugin: PluginSimple
+
+declare module '@md-plugins/shared' {
+  interface MarkdownItEnv {
+    /**
+     * The title that extracted by `md-plugin-title`
+     */
+    title?: string
+    heading?: boolean
+  }
+}
+
+export { titlePlugin }
+```
+
+### How It Works
+
+The `title` plugin processes the tokens in your Markdown content, extracting the first `h1` tag and storing its content as the title in the `env` object. This helps manage the title of your Markdown content programmatically.
+
+### Default Behavior
+
+By default, the `title` plugin extracts the content of the first `h1` tag and stores it in the `env.title` property. Here is an example of a Markdown file with a title:
+
+```markdown
+# My Awesome Post
+
+This is the content of my awesome post.
+```
+
+### Plugin Options
+
+The `title` plugin does not provide any options for customization. It is designed to work out of the box with the default behavior.
+
+### Example Configuration
+
+Here is an example of how you can use the `title` plugin:
+
+```typescript
+import MarkdownIt from 'markdown-it'
+import { titlePlugin } from '@md-plugins/md-plugin-title'
+
+const md = new MarkdownIt()
+
+md.use(titlePlugin)
+```
+
+### Using the Extracted Title
+
+Once the title is extracted, it is stored in the `env.title` property. How you handle this data and send it to the front-end is up to you.
+
+### Integration with Frontmatter Plugin
+
+If you are using the `frontmatter` plugin and one of the items in the frontmatter is `title:`, you do not need to use the `title` plugin. The `frontmatter` plugin will handle the extraction of the title for you. Here is an example of a Markdown file with frontmatter:
+
+```markdown
+---
+title: My Awesome Post
+date: 2023-10-01
+tags: [markdown, title, plugin]
+---
+
+This is the content of my awesome post.
+```
+
+### Conclusion
+
+The `title` plugin is a simple yet powerful tool for extracting the title from your Markdown content. By storing the title in the `env` object, you can manage the title programmatically and use it in your front-end application. If you are using the `frontmatter` plugin with a `title` field, you do not need to use the `title` plugin. Experiment with different configurations and find the one that works best for you.
+
+Happy coding!

package/src/templates/init/src/markdown/md-plugins/title/overview.md

@@ -0,0 +1,99 @@
+---
+title: Title Plugin
+desc: Title plugin for Markdown.
+---
+
+Welcome to the Title Plugin documentation! This guide will provide you with an overview of the Title plugin and its features.
+
+## What is the Title Plugin?
+
+The Title Plugin is a powerful tool that enhances the standard Markdown functionality by allowing you to extract and manage the title of your Markdown content. It integrates seamlessly with Markdown-It to provide a flexible and customizable way to handle titles in your Markdown files.
+
+## Key Features
+
+- **Title Extraction**: Automatically extract the title from the first `h1` heading in your Markdown content.
+- **Environment Integration**: Store the extracted title in the Markdown-It environment for easy access.
+
+## Examples
+
+Here are some examples of what you can achieve with the Title Plugin:
+
+### Standard Title Extraction
+
+```markup
+# My Document Title
+
+This is the content of my document.
+```
+
+## Environment Variables
+
+When using the Title plugin, the following variables are set in the env object:
+
+- **title**: The extracted title from the first h1 heading in the Markdown content.
+- **heading**: A boolean indicating whether a title was extracted.
+
+## Name
+
+The official NPM name is `@md-plugins/md-plugin-title`.
+
+## Installation
+
+You can install the Title plugin using npm, yarn, or pnpm. Choose your preferred method below:
+
+```tabs
+<<| bash npm |>>
+npm install @md-plugins/md-plugin-title
+<<| bash yarn |>>
+yarn add @md-plugins/md-plugin-title
+<<| bash pnpm |>>
+pnpm add @md-plugins/md-plugin-title
+```
+
+## Configuration
+
+After installing the plugin, you need to configure it in your Markdown-It setup. Here's an example of how to do that:
+
+```javascript
+import MarkdownIt from 'markdown-it'
+import { titlePlugin } from '@md-plugins/md-plugin-title'
+
+const md = new MarkdownIt()
+
+md.use(titlePlugin)
+
+// Now you can use the Title plugin in your Markdown content
+const result = md.render('# My Document Title\n\nThis is the content of my document.')
+console.log(result)
+```
+
+### Options
+
+The Title plugin does not accept any options.
+
+## Advanced Configuration
+
+For more advanced configurations, you can combine the Title plugin with other Markdown-It plugins to enhance your Markdown content further. Here's an example:
+
+```javascript
+import MarkdownIt from 'markdown-it'
+import { titlePlugin } from '@md-plugins/md-plugin-title'
+import markdownItAnchor from 'markdown-it-anchor'
+import markdownItToc from 'markdown-it-toc-done-right'
+
+const md = new MarkdownIt()
+
+md.use(titlePlugin).use(markdownItAnchor).use(markdownItToc)
+
+// Now you can use the Title plugin along with other plugins in your Markdown content
+const result = md.render(
+  '# My Document Title\n\n# Table of Contents\n\n[[toc]]\n\nThis is the content of my document.',
+)
+console.log(result)
+```
+
+## 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/other/release-notes.md

@@ -0,0 +1,12 @@
+---
+title: Release Notes
+desc: The changelog for MD-Plugins packages.
+---
+
+Release notes (with changelog) for MD-Plugins packages are available on [GitHub Releases](https://github.com/md-plugins/md-plugins/releases).
+
+<!-- <script import>
+import PublicReleases from 'components/Releases/PublicReleases.vue'
+</script>
+
+<PublicReleases /> -->

package/src/templates/init/src/markdown/privacy-policy.md

@@ -0,0 +1,12 @@
+---
+title: Privacy Policy
+desc: Markdown for your Quasar and Vue builds
+editLink: false
+fullscreen: true
+---
+
+> _Privacy Policy_ of **@md-plugins**
+
+::: info
+This Website collects some Personal Data from its Users.
+:::

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

@@ -0,0 +1,101 @@
+---
+title: Q-Press Advanced Topics
+desc: Advanced Topics for the Q-Press App-Extension.
+examples: QAvatar
+related:
+  - vite-plugins/viteexamplesplugin/overview
+---
+
+If you plan on having `api` and `examples` support in your markdown files, we will discuss making the necessary updates to support that. If you don't know what `api` and `examples` are, here are examples for Quasar's `QAvatar` component:
+
+<script import>
+import AvatarApi from 'quasar/dist/api/QAvatar.json'
+</script>
+
+<MarkdownApi :api="AvatarApi" name="QAvatar"/>
+
+<MarkdownExample title="Title for example card" file="BasicExample" no-edit no-github/>
+
+## Usage
+
+You will need to make sure you have the necessary components installed as outlined further down in the [Installation](#installation) section.
+
+In your `src` folder, you should have an `examples` folder. Each child folder should be a topic, like a `QAvatar` folder. In this folder, you will add your examples.
+
+In the `frontmatter` of your markdown file, you will need to specify the topic folder like so:
+
+```yaml
+examples: QAvatar
+```
+
+In your markdown file, you can add the following to create an `example` card:
+
+::: tip
+The `file="BasicExample"` is the name of the Vue file (without extension) in the `examples/QAvatar` folder.
+:::
+
+```markdown
+<MarkdownExample title="Title for example card" file="BasicExample" no-edit no-github/>
+```
+
+In your markdown file, you can add the following to create an `api` card:
+
+::: tip
+The API format conforms to Quasar's API format.
+We will touch on this at a later date.
+:::
+
+```markdown
+<script import >
+import AvatarApi from 'quasar/dist/api/QAvatar.json'
+</script>
+
+<MarkdownApi :api="AvatarApi" name="QAvatar"/>
+```
+
+## viteExamplesPlugin
+
+### 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:
+
+```ts
+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...
+]
+```
+
+## 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/quasar-app-extensions/qpress/components.md

@@ -0,0 +1,69 @@
+---
+title: Q-Press Components
+desc: Components for Q-Press App-Extension for Quasar.
+---
+
+Q-Press has a lot of components that can be used in your app. Under the hood, these components are being used by the system. But, if you find a way to make them useful, you will find the documentation for them below to be helpful.
+
+## 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 MarkdownInstallationApi from 'src/.q-press/api/components/MarkdownInstallation.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'
+
+</script>
+
+<MarkdownApi :api="DarkModeToggleApi" name="DarkModeToggle"/>
+<MarkdownApi :api="MarkdownApiApi" name="MarkdownApi"/>
+<MarkdownApi :api="MarkdownCardLinkApi" name="MarkdownCardLink"/>
+<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"/> -->
+
+<MarkdownApi :api="MarkdownExampleApi" name="MarkdownExample"/>
+<MarkdownApi :api="MarkdownHeaderApi" name="MarkdownHeader"/>
+<MarkdownApi :api="MarkdownHeaderIconLinksApi" name="MarkdownHeaderIconLinks"/>
+<MarkdownApi :api="MarkdownHeaderMenuApi" name="MarkdownHeaderMenu"/>
+<MarkdownApi :api="MarkdownHeaderTextLinksApi" name="MarkdownHeaderTextLinks"/>
+<MarkdownApi :api="MarkdownInstallationApi" name="MarkdownInstallation"/>
+
+<MarkdownApi :api="MarkdownLayoutApi" name="MarkdownLayout"/>
+<MarkdownApi :api="MarkdownLinkApi" name="MarkdownLink"/>
+<MarkdownApi :api="MarkdownPageApi" name="MarkdownPage"/>
+<MarkdownApi :api="MarkdownPageFooterApi" name="MarkdownPageFooter"/>
+<!-- No <MarkdownApi :api="MarkdownPageSidebarApi" name="MarkdownPageSidebar"/> -->
+<!-- No <MarkdownApi :api="MarkdownPageTocApi" name="MarkdownPageToc"/> -->
+
+<MarkdownApi :api="MarkdownPrerenderApi" name="MarkdownPrerender"/>
+<MarkdownApi :api="MarkdownTreeApi" name="MarkdownTree"/>

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

@@ -0,0 +1,254 @@
+---
+title: Q-Press
+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 at this time. Typescript processing is also required. Do not use if you are using Webpack or have a Javascript-only project.
+:::
+
+::: tip
+This website is built with **Q-Press**! When you install the App-Extension, you will be able have this website up and running in minutes. Later, you can make adjustments to the `src/siteConfig` and add your own markdown files in the `src/markdown` folder to make it your own.
+:::
+
+## 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.
+- **Hot Module Replacement (HMR)**: Supports HMR for Markdown files, enabling a smooth development experience with instant updates.
+
+## Installation
+
+To install the Q-Press App Extension, use the following command on your existing Quasar project:
+
+```bash
+quasar ext add @md-plugins/q-press
+```
+
+### What Gets Installed
+
+- **New Install:**
+  - `src/.q-press`
+  - `src/q-press.global.d.ts`
+  - `src/components`
+  - `src/markdown`
+  - `src/examples`
+  - `src/siteConfig`
+- **Update Install:**
+  - `src/.q-press`
+  - `src/q-press.global.d.ts`
+
+### Additional Dependencies
+
+1. **Install `markdown-it` and `@types/markdown-it` in your project devDependencies:**
+
+```tabs
+<<| bash npm |>>
+npm i -D markdown-it @types/markdown-it
+<<| bash yarn |>>
+yarn add -D markdown-it @types/markdown-it
+<<| bash pnpm |>>
+pnpm i -D markdown-it @types/markdown-it
+```
+
+2. **Add `prismjs` to your project dependencies:**
+
+```tabs
+<<| bash npm |>>
+npm i prismjs
+<<| bash yarn |>>
+yarn add prismjs
+<<| bash pnpm |>>
+pnpm i prismjs
+```
+
+## Configuration
+
+### Modify `src/css/quasar.variables.scss`
+
+Import a Q-Press theme (`default`, `sunrise`, `newspaper`, `tawny`, your own or a 3rd-party theme):
+
+```scss
+@import '../.q-press/css/themes/sunrise.scss';
+```
+
+### Modify `src/css/app.scss`
+
+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`
+
+```typescript
+import { defineConfig } from '#q-app/wrappers'
+import type { Plugin } from 'vite'
+import { viteMdPlugin, type MenuItem } from '@md-plugins/vite-md-plugin'
+
+export default defineConfig(async (ctx) => {
+  // Dynamically import siteConfig
+  const siteConfig = await import('./src/siteConfig')
+  const { sidebar } = siteConfig.default
+
+  return {
+    build: {
+      vitePlugins: [
+        // add this plugin
+        [
+          viteMdPlugin,
+          {
+            path: ctx.appPaths.srcDir + '/markdown',
+            menu: sidebar as MenuItem[],
+          },
+        ],
+        // other plugins...
+      ],
+    },
+  }
+})
+```
+
+### Modify `src/routes/routes.ts`
+
+```typescript
+import mdPageList from 'src/markdown/listing'
+
+const routes = [
+  {
+    path: '/',
+    component: () => import('src/.q-press/layouts/MarkdownLayout.vue'),
+    children: [
+      // Include the Landing Page route first
+      ...Object.entries(mdPageList)
+        .filter(([key]) => key.includes('landing-page.md'))
+        .map(([_key, component]) => ({
+          path: '',
+          name: 'Landing Page',
+          component,
+          meta: { fullscreen: true, dark: true },
+        })),
+
+      // Now include all other routes, excluding the landing-page
+      ...Object.keys(mdPageList)
+        .filter((key) => !key.includes('landing-page.md')) // Exclude duplicates
+        .map((key) => {
+          const acc = {
+            path: '',
+            component: mdPageList[key],
+          }
+
+          if (acc.path === '') {
+            // Remove '.md' from the end of the filename
+            const parts = key.substring(1, key.length - 3).split('/')
+            const len = parts.length
+            const path = parts[len - 2] === parts[len - 1] ? parts.slice(0, len - 1) : parts
+
+            acc.path = path.join('/')
+          }
+
+          return acc
+        }),
+    ],
+  },
+
+  // Always leave this as last one,
+  // but you can also remove it
+  {
+    path: '/:catchAll(.*)*',
+    component: () => import('pages/ErrorNotFound.vue'),
+  },
+]
+
+export default routes
+```
+
+### Set Up for Dark Mode
+
+Update your `App.vue`:
+
+```ts
+<template>
+  <router-view />
+</template>
+
+<script setup lang="ts">
+  import { useDark } from 'src/.q-press/composables/dark'
+  const { initDark } = useDark()
+  initDark()
+</script>
+```
+
+## FAQ
+
+:::details Q. I have errors in my`routes.ts` file, what should I do?
+
+**A.** You can remove the following line: `import type { RouteRecordRaw } from 'vue-router'` and also remove the `type` keyword from the `routes` variable (`: RouteRecordRaw[]`).
+:::
+
+:::details Q. I still see an error in my `routes.ts` file, for `_key`, what should I do?
+
+**A.** In your `eslint.config.js` file, add/replace the following in your rules:
+
+```js
+'@typescript-eslint/no-unused-vars': [
+  'error',
+  {
+    argsIgnorePattern: '^_',
+    ignoreRestSiblings: true,
+    varsIgnorePattern: '^_',
+  },
+],
+```
+
+:::
+
+:::details Q. Every time I save a markdown file, `prettier` changes it so that it breaks. How can I prevent this?
+
+**A.** This is both a `prettier` and `eslint` issue. In `eslint.config.js`, add the following to the top of the file, right after `export default [`:
+
+```js
+{
+  /**
+   * Ignore the following files.
+   * Please note that pluginQuasar.configs.recommended() already ignores
+   * the "node_modules" folder for you (and all other Quasar project
+   * relevant folders and files).
+   *
+   * ESLint requires "ignores" key to be the only one in this object
+   */
+  ignores: ['eslint.config.js', '**/*.md', 'dist/**/*', 'node_modules'],
+},
+```
+
+If you don't have a `.prettierignore` file, create one in the root of your project and add the following:
+
+```bash
+- Ignore all Markdown files:
+\*_/_.md
+```
+
+:::
+
+## Updating
+
+When you update, only the `src/.q-press` folder will be updated as well as the file `src/q-press.global.d.ts`. 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:
+
+```bash
+quasar ext invoke @md-plugins/q-press
+```
+
+Then select the `Overwrite All` option.
+
+---
+
+Happy coding!

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

@@ -0,0 +1,4 @@
+---
+title: Q-Press Themes
+desc: Themes for Q-Press App-Extension for Quasar.
+---

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

@@ -0,0 +1,4 @@
+---
+title: ViteMdPluginAppExt Advanced Topics
+desc: Advanced Topics for the ViteMdPluginAppExt.
+---