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

package/LICENSE.md

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2024-present, MD-PLUGINS
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -0,0 +1,230 @@
+# Q-Press
+
+The Ultimate Markdown Solution for the Quasar Framework.
+
+## Features
+
+- **Markdown**
+- **Dark Mode**
+- **Landing Page**
+- **Markdown Layouts**
+- **Markdown Components**
+- **siteConfig**
+- **CSS Themes**
+
+## Installation
+
+1. Install the **Q-Press** App-Ext
+
+- `quasar ext add @md-plugins/q-press`
+- Here is what gets installed on a **new** install:
+  - `src/.q-press`
+  - `src/q-press.global.d.ts`
+  - `src/components`
+  - `src/markdown`
+  - `src/examples`
+  - `src/siteConfig`
+- Here is what gets installed on an **update** install:
+  - `src/.q-press`
+  - `src/q-press.global.d.ts`
+
+2. Install `markdown-it` and `@types/markdown-it` in your project devDependencies
+
+- `npm i -D markdown-it @types/markdown-it`
+- `yarn add -D markdown-it @types/markdown-it`
+- `pnpm i -D markdown-it @types/markdown-it`
+
+3. Add `prismjs` to your project dependencies
+
+- `npm i prismjs`
+- `yarn add prismjs`
+- `pnpm i prismjs`
+
+## Modifications
+
+1. Modify your `src/css/quasar.variables.scss`
+
+- import a Q-Press theme (`default`, `sunrise`, `newspaper`, `tawny`, your own or a 3rd-party theme)
+- `@import '../.q-press/css/themes/sunrise.scss';`
+
+2. Modify your `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';
+  ```
+
+3. Modify your `quasar.config.ts`
+
+```ts
+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
+  return {
+    build: {
+      vitePlugins: [
+        // add this plugin
+        [
+          viteMdPlugin,
+          {
+            path: ctx.appPaths.srcDir + '/markdown',
+            menu: sidebar as MenuItem[],
+          },
+        ],
+        // ...
+```
+
+4. Modify your `src/routes/routes.ts`
+
+```ts
+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
+```
+
+5. Set up for Dark mode support, 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>
+```
+
+## Running the App
+
+This is a Quasar app, so all you have to do is `quasar dev` and `quasar dev`. You can test it out now and you will have running the `MD-Plugins` web site.
+
+All you need to do now is change the configuration and landing page to make it your own.
+
+## Configuration
+
+### `src/siteConfig/index.ts`
+
+1. Make any appropriate changes to the `siteConfig.ts` file
+
+### `src/components/LandingPage/LandingPage.vue`
+
+1. Update the `LandingPage.vue` file to include your own content
+
+---
+
+## FAQ
+
+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[]`).
+
+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: '^_',
+        },
+      ],
+```
+
+Q. Everytime 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 and add the following:
+
+```
+# 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
+```
+
+## Documentation
+
+In case this README falls out of date, please refer to the [documentation](https://md-plugins.netlify.app/quasar-app-extensions/qpress/overview) for the latest information.
+
+## License
+
+This project is licensed under the MIT License. See the [LICENSE](LICENSE.md) file for details.

package/old/prompts.js

@@ -0,0 +1,44 @@
+/**
+ * Quasar App Extension prompts script
+ *
+ * Docs: https://quasar.dev/app-extensions/development-guide/prompts-api
+ *
+ * Inquirer prompts
+ * (answers are available as "api.prompts" in the other scripts)
+ * https://www.npmjs.com/package/inquirer#question
+ *
+ * Example:
+
+  return [
+    {
+      name: 'name',
+      type: 'input',
+      required: true,
+      message: 'Quasar CLI Extension name (without prefix)',
+    },
+    {
+      name: 'preset',
+      type: 'checkbox',
+      message: 'Check the features needed for your project:',
+      choices: [
+        {
+          name: 'Install script',
+          value: 'install'
+        },
+        {
+          name: 'Prompts script',
+          value: 'prompts'
+        },
+        {
+          name: 'Uninstall script',
+          value: 'uninstall'
+        }
+      ]
+    }
+  ]
+
+ */
+
+export default function (api) {
+  return []
+}

package/old/uninstall.js

@@ -0,0 +1,9 @@
+/**
+ * Quasar App Extension uninstall script
+ *
+ * Docs: https://quasar.dev/app-extensions/development-guide/uninstall-api
+ */
+
+export default function (api) {
+  //
+}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@md-plugins/quasar-app-extension-q-press",
+  "version": "0.1.0-alpha.10",
+  "description": "QPress - The Ultimate Markdown Solution for Quasar Framework",
+  "author": "hawkeye64 <galbraith64@gmail.com>",
+  "keywords": [
+    "markdown-it",
+    "quasarframework",
+    "quasar",
+    "markdown",
+    "q-press",
+    "vite"
+  ],
+  "homepage": "https://github.com/md-plugins",
+  "bugs": {
+    "url": "https://github.com/md-plugins/md-plugins/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/md-plugins/md-plugins.git"
+  },
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">= 12.2.0",
+    "npm": ">= 5.6.0",
+    "yarn": ">= 1.6.0"
+  },
+  "dependencies": {
+    "@md-plugins/md-plugin-codeblocks": "0.1.0-alpha.10",
+    "@md-plugins/md-plugin-containers": "0.1.0-alpha.10",
+    "@md-plugins/md-plugin-headers": "0.1.0-alpha.10",
+    "@md-plugins/md-plugin-blockquote": "0.1.0-alpha.10",
+    "@md-plugins/md-plugin-imports": "0.1.0-alpha.10",
+    "@md-plugins/md-plugin-frontmatter": "0.1.0-alpha.10",
+    "@md-plugins/md-plugin-inlinecode": "0.1.0-alpha.10",
+    "@md-plugins/md-plugin-image": "0.1.0-alpha.10",
+    "@md-plugins/md-plugin-link": "0.1.0-alpha.10",
+    "@md-plugins/md-plugin-table": "0.1.0-alpha.10",
+    "@md-plugins/md-plugin-title": "0.1.0-alpha.10",
+    "@md-plugins/vite-md-plugin": "0.1.0-alpha.10",
+    "@md-plugins/shared": "0.1.0-alpha.10"
+  },
+  "devDependencies": {
+    "@types/markdown-it": "^14.1.2",
+    "fs-extra": "^11.2.0",
+    "markdown-it": "^14.1.0",
+    "vite": "^6.0.7"
+  },
+  "peerDependencies": {
+    "markdown-it": "^14.1.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "node ./scripts/build.js",
+    "test": "echo \"No test specified\" && exit 0"
+  }
+}

package/scripts/build.js

@@ -0,0 +1,33 @@
+// Copy from the Docs package to this project
+import fse from 'fs-extra'
+import path from 'path'
+import { fileURLToPath } from 'url'
+
+// Get the current directory name
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = path.dirname(__filename)
+
+// Construct full paths
+const initPath = path.resolve(__dirname, '../src/templates/init')
+const updatePath = path.resolve(__dirname, '../src/templates/update')
+const globalsPath = path.resolve(__dirname, '../../docs/src/q-press.globals.d.ts')
+const qPressPath = path.resolve(__dirname, '../../docs/src/.q-press')
+const componentsPath = path.resolve(__dirname, '../../docs/src/components')
+const markdownPath = path.resolve(__dirname, '../../docs/src/markdown')
+const examplesPath = path.resolve(__dirname, '../../docs/src/examples')
+const siteConfigPath = path.resolve(__dirname, '../../docs/src/siteConfig')
+
+// The "update" folder only gets 'q-press.globals.d.ts' and the '_q-press' folder
+fse.removeSync(initPath)
+fse.removeSync(updatePath)
+
+fse.copySync(globalsPath, path.join(initPath, 'src/q-press.globals.d.ts'))
+fse.copySync(globalsPath, path.join(updatePath, 'src/q-press.globals.d.ts'))
+
+fse.copySync(qPressPath, path.join(initPath, 'src/_q-press'))
+fse.copySync(qPressPath, path.join(updatePath, 'src/_q-press'))
+
+fse.copySync(componentsPath, path.join(initPath, 'src/components'))
+fse.copySync(markdownPath, path.join(initPath, 'src/markdown'))
+fse.copySync(examplesPath, path.join(initPath, 'src/examples'))
+fse.copySync(siteConfigPath, path.join(initPath, 'src/siteConfig'))

package/src/index.js

@@ -0,0 +1,63 @@
+/*global console*/
+/**
+ * Quasar App Extension index/runner script
+ * (runs on each dev/build)
+ *
+ * Docs: https://quasar.dev/app-extensions/development-guide/index-api
+ */
+
+// import fse from 'fs-extra'
+// import { viteMdPlugin } from '@md-plugins/vite-md-plugin'
+
+async function extendConfig(config /*, api*/) {
+  // console.log('config', config)
+  // console.log('api', api)
+
+  // make sure 'vueRouterMode' has 'history' mode
+  if (config.build.vueRouterMode !== 'history') {
+    console.log('Changing vueRouterMode to "history" - required for hash links to work correctly')
+    config.build.vueRouterMode = 'history'
+  }
+
+  // let Vite know to transpile md files
+  config.build.viteVuePluginOptions.include = config.build.viteVuePluginOptions.include || []
+  config.build.viteVuePluginOptions.include.push(/\.(vue|md)$/)
+
+  // let Vue know to auto import md files
+  const extensions = new Set(config.framework.autoImportVueExtensions || [])
+  extensions.add('md')
+  extensions.add('vue')
+  config.framework.autoImportVueExtensions = Array.from(extensions)
+
+  // add the appropriate plugins
+  const plugins = new Set(config.framework.plugins || [])
+  plugins.add('Cookies')
+  plugins.add('Dark')
+  plugins.add('Meta')
+  plugins.add('Notify')
+  config.framework.plugins = Array.from(plugins)
+
+  // const markdownPath = api.resolve.src('markdown')
+  // const path = api.resolve.src('siteConfig')
+  // if (fse.pathExistsSync(path) && fse.pathExistsSync(markdownPath)) {
+  //   const siteConfig = await import(path)
+  //   const { sidebar } = siteConfig
+
+  //   // viteMdPlugin(ctx.appPaths.srcDir + '/markdown', sidebar as MenuItem[]),
+  //   // add vite-md-plugin to quiasar.config.js
+  //   config.vite.plugins.push([viteMdPlugin, { path: markdownPath, menu: sidebar }])
+  // }
+}
+
+export default function (api) {
+  // verify this is a Vite project
+  if (!api.hasVite) {
+    throw new Error('This extension requires Vite')
+  }
+
+  api.compatibleWith('quasar', '^2.0.0')
+  api.compatibleWith('@quasar/app-vite', '^2.0.0')
+
+  // here we extend /quasar.config, so we can add some Vite/Vue stuff
+  api.extendQuasarConf(extendConfig)
+}

package/src/install.js

@@ -0,0 +1,49 @@
+/*global console*/
+/**
+ * Quasar App Extension install script
+ *
+ * Docs: https://quasar.dev/app-extensions/development-guide/install-api
+ */
+
+import fse from 'fs-extra'
+
+export default async function (api) {
+  // verify this is a Vite project
+  if (!api.hasVite) {
+    throw new Error('This extension requires Vite')
+  }
+
+  api.compatibleWith('quasar', '^2.0.0')
+  api.compatibleWith('@quasar/app-vite', '^2.0.0')
+
+  // project must have pinia installed
+  if ((await api.getStorePackageName()) !== 'pinia') {
+    console.error('-----------------------------')
+    console.error('This extension requires pinia')
+    console.error('-----------------------------')
+    throw new Error('This extension requires pinia')
+  }
+
+  // project must be typescript
+  if ((await api.hasTypescript()) !== true) {
+    console.error('----------------------------------')
+    console.error('This extension requires TypeScript')
+    console.error('----------------------------------')
+    throw new Error('This extension requires TypeScript')
+  }
+
+  const path = api.resolve.src('siteConfig')
+  if (fse.pathExistsSync(path)) {
+    // this is an update scenario
+    console.log('-------------------------------------')
+    console.log("Update only for 'src/.q-press' folder")
+    console.log('-------------------------------------')
+    api.render('./templates/update')
+  } else {
+    // this is a project initial setup
+    console.log('--------------------------------------------')
+    console.log('Initial setup. Be sure to read the\ndocumentation on the manual set up required.')
+    console.log('--------------------------------------------')
+    api.render('./templates/init')
+  }
+}

package/src/templates/init/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')"
+        }
+      }
+    }
+  }
+}

package/src/templates/init/src/_q-press/api/components/MarkdownApi.json

@@ -0,0 +1,67 @@
+{
+  "type": "component",
+  "meta": {
+    "docsUrl": "https://path-to-your-docs/markdown-api"
+  },
+  "props": {
+    "nameBanner": {
+      "type": "String",
+      "desc": "Title to display in the banner",
+      "examples": [
+        "'API Documentation'",
+        "'Component API'"
+      ],
+      "category": "content"
+    },
+    "pageLink": {
+      "type": "String",
+      "desc": "URL for the page link",
+      "examples": [
+        "'https://github.com/user/repo/edit/main/docs/page.md'"
+      ],
+      "category": "navigation"
+    }
+  },
+  "events": {
+    "searchFieldClick": {
+      "desc": "Emitted when the search field is clicked",
+      "params": {
+        "evt": {
+          "type": "Event",
+          "desc": "JS event object"
+        }
+      }
+    },
+    "filterClick": {
+      "desc": "Emitted when the filter button is clicked",
+      "params": {
+        "evt": {
+          "type": "Event",
+          "desc": "JS event object"
+        }
+      }
+    }
+  },
+  "methods": {
+    "onSearchFieldClick": {
+      "desc": "Handler for the search field click event",
+      "params": {
+        "evt": {
+          "type": "Event",
+          "desc": "JS event object"
+        }
+      },
+      "returns": null
+    },
+    "onFilterClick": {
+      "desc": "Handler for the filter button click event",
+      "params": {
+        "evt": {
+          "type": "Event",
+          "desc": "JS event object"
+        }
+      },
+      "returns": null
+    }
+  }
+}