@md-plugins/quasar-app-extension-q-press 0.1.0-alpha.7 → 0.1.0-beta.1

package/README.md

@@ -1,6 +1,238 @@
 # Q-Press
 
-The Ultimate Markdown Solution for Quasar Framework
+The Ultimate Markdown Solution for the Quasar Framework.
+
+See the [documentation](https://md-plugins.netlify.app/quasar-app-extensions/qpress/overview) for more information.
+
+> Current beta release: `0.1.0-beta.1`.
+>
+> Q-Press currently targets Quasar Vite projects using `@quasar/app-vite` `>=3.0.0-beta.14`. TypeScript processing is required.
+
+## Features
+
+- **Markdown**
+- **Dark Mode**
+- **Landing Page**
+- **Markdown Layouts**
+- **Markdown Components**
+- **siteConfig**
+- **CSS Themes**
+- **Automatic Routing**
+
+## 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.globals.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.globals.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 add prismjs`
+
+## Modifications
+
+1. Modify your `src/css/quasar.variables.scss`
+
+- import a Q-Press theme (`default`, `sunrise`, `newspaper`, `tawny`, `mystic`, your own or a 3rd-party theme)
+- ```ts
+  @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, type MarkdownOptions } 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[],
+              // options: myOptions as MarkdownOptions
+            },
+          ],
+          // ...
+  ```
+
+4. Modify your `src/routes/routes.ts`
+
+- ```ts
+  import type { RouteRecordRaw } from 'vue-router'
+  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'),
+    },
+  ] as RouteRecordRaw[]
+
+  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 run `quasar dev`. You can test it out now and you will have the `MD-Plugins` web site running.
+
+All you need to do now is change the configuration and landing page to make it your own.
+
+## Configuration
+
+### Modify `src/siteConfig/index.ts`
+
+1. Make any appropriate changes to the `siteConfig.ts` file
+
+### Modify `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. 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 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.globals.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
 

package/package.json

@@ -1,57 +1,63 @@
 {
   "name": "@md-plugins/quasar-app-extension-q-press",
-  "version": "0.1.0-alpha.7",
+  "version": "0.1.0-beta.1",
   "description": "QPress - The Ultimate Markdown Solution for Quasar Framework",
-  "author": "hawkeye64 <galbraith64@gmail.com>",
   "keywords": [
-    "markdown-it",
-    "quasarframework",
-    "quasar",
     "markdown",
+    "markdown-it",
     "q-press",
+    "quasar",
+    "quasarframework",
     "vite"
   ],
   "homepage": "https://github.com/md-plugins",
   "bugs": {
     "url": "https://github.com/md-plugins/md-plugins/issues"
   },
+  "license": "MIT",
+  "author": "hawkeye64 <galbraith64@gmail.com>",
   "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"
+  "main": "src/index.ts",
+  "publishConfig": {
+    "access": "public"
   },
   "dependencies": {
-    "@md-plugins/md-plugin-blockquote": "0.1.0-alpha.7",
-    "@md-plugins/md-plugin-frontmatter": "0.1.0-alpha.7",
-    "@md-plugins/md-plugin-codeblocks": "0.1.0-alpha.7",
-    "@md-plugins/md-plugin-headers": "0.1.0-alpha.7",
-    "@md-plugins/md-plugin-image": "0.1.0-alpha.7",
-    "@md-plugins/md-plugin-imports": "0.1.0-alpha.7",
-    "@md-plugins/md-plugin-containers": "0.1.0-alpha.7",
-    "@md-plugins/md-plugin-inlinecode": "0.1.0-alpha.7",
-    "@md-plugins/md-plugin-table": "0.1.0-alpha.7",
-    "@md-plugins/md-plugin-link": "0.1.0-alpha.7",
-    "@md-plugins/shared": "0.1.0-alpha.7",
-    "@md-plugins/md-plugin-title": "0.1.0-alpha.7"
+    "@types/markdown-it": "^14.1.2",
+    "fs-extra": "^11.3.4",
+    "markdown-it": "^14.1.1",
+    "@md-plugins/md-plugin-blockquote": "0.1.0-beta.1",
+    "@md-plugins/md-plugin-codeblocks": "0.1.0-beta.1",
+    "@md-plugins/md-plugin-frontmatter": "0.1.0-beta.1",
+    "@md-plugins/md-plugin-image": "0.1.0-beta.1",
+    "@md-plugins/md-plugin-imports": "0.1.0-beta.1",
+    "@md-plugins/md-plugin-headers": "0.1.0-beta.1",
+    "@md-plugins/md-plugin-inlinecode": "0.1.0-beta.1",
+    "@md-plugins/md-plugin-containers": "0.1.0-beta.1",
+    "@md-plugins/md-plugin-table": "0.1.0-beta.1",
+    "@md-plugins/md-plugin-link": "0.1.0-beta.1",
+    "@md-plugins/shared": "0.1.0-beta.1",
+    "@md-plugins/md-plugin-title": "0.1.0-beta.1",
+    "@md-plugins/vite-md-plugin": "0.1.0-beta.1"
   },
   "devDependencies": {
+    "@quasar/app-vite": "3.0.0-beta.14",
     "@types/markdown-it": "^14.1.2",
-    "markdown-it": "^14.1.0",
-    "vite": "^6.0.7"
+    "vite": "^8.0.3"
   },
   "peerDependencies": {
+    "@quasar/app-vite": ">=3.0.0-beta.14",
     "markdown-it": "^14.1.0"
   },
-  "publishConfig": {
-    "access": "public"
+  "engines": {
+    "node": ">=22.13",
+    "pnpm": ">=11.1.0"
   },
   "scripts": {
+    "build": "node ./scripts/build.js",
     "test": "echo \"No test specified\" && exit 0"
   }
 }

package/src/index.ts

@@ -0,0 +1,70 @@
+/**
+ * Quasar App Extension index/runner script
+ * (runs on each dev/build)
+ *
+ * Docs: https://quasar.dev/app-extensions/development-guide/index-api
+ */
+
+import { defineIndexScript } from '@quasar/app-vite'
+
+// import fse from 'fs-extra'
+// import { viteMdPlugin } from '@md-plugins/vite-md-plugin'
+
+export default defineIndexScript((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', '>=3.0.0-beta.14')
+
+  // here we extend /quasar.config, so we can add some Vite/Vue stuff
+  api.extendQuasarConf(async (config) => {
+    config.build ??= {}
+    config.build.viteVuePluginOptions ??= {}
+    config.framework ??= {}
+
+    // make sure 'vueRouterMode' has 'history' mode
+    if (config.build.vueRouterMode !== 'history') {
+      console.warn('Changing vueRouterMode to "history" - required for hash links to work correctly')
+      config.build.vueRouterMode = 'history'
+    }
+
+    // let Vite know to transpile md files
+    const include = config.build.viteVuePluginOptions.include
+    if (Array.isArray(include)) {
+      include.push(/\.(vue|md)$/)
+    }
+    else if (include !== void 0) {
+      config.build.viteVuePluginOptions.include = [include, /\.(vue|md)$/]
+    }
+    else {
+      config.build.viteVuePluginOptions.include = [/\.(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.default || siteConfig
+
+    //   // add vite-md-plugin to quasar.config.js
+    //   config.vite.plugins.push(viteMdPlugin({ path: markdownPath, menu: sidebar }))
+    // }
+  })
+})

package/src/install.ts

@@ -0,0 +1,50 @@
+/**
+ * Quasar App Extension install script
+ *
+ * Docs: https://quasar.dev/app-extensions/development-guide/install-api
+ */
+
+import { defineInstallScript } from '@quasar/app-vite'
+import { existsSync } from 'node:fs'
+
+export default defineInstallScript(async (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', '>=3.0.0-beta.14')
+
+  // 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 (existsSync(path)) {
+    // this is an update scenario
+    console.warn('-------------------------------------')
+    console.warn("Update only for 'src/.q-press' folder")
+    console.warn('-------------------------------------')
+    api.render('./templates/update')
+  }
+  else {
+    // this is a project initial setup
+    console.warn('--------------------------------------------')
+    console.warn('Initial setup. Be sure to read the\ndocumentation on the manual set up required.')
+    console.warn('--------------------------------------------')
+    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
+    }
+  }
+}

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

@@ -0,0 +1,76 @@
+{
+  "type": "component",
+  "meta": {
+    "docsUrl": "https://path-to-your-docs/markdown-api-entry"
+  },
+  "functions": {
+    "getProp": {
+      "desc": "Function to get a property node for the API entry.",
+      "params": {
+        "openState": {
+          "type": "Object",
+          "desc": "The state object to manage open/close state of nodes."
+        },
+        "masterKey": {
+          "type": "String",
+          "desc": "The master key for the API entry."
+        },
+        "prop": {
+          "type": "Object",
+          "desc": "The property object to generate the node for."
+        },
+        "paramName": {
+          "type": "String",
+          "desc": "The name of the parameter."
+        },
+        "level": {
+          "type": "Number",
+          "desc": "The level of the property in the hierarchy."
+        }
+      },
+      "returns": {
+        "type": "Array<VNode>",
+        "desc": "An array of VNode elements representing the property."
+      }
+    },
+    "getDiv": {
+      "desc": "Function to create a div element for the API entry.",
+      "params": {
+        "cols": {
+          "type": "Number",
+          "desc": "The number of columns the div should span."
+        },
+        "label": {
+          "type": "String",
+          "desc": "The label for the div."
+        },
+        "key": {
+          "type": "String",
+          "desc": "The key for the div."
+        },
+        "children": {
+          "type": "Array<VNode>",
+          "desc": "The child nodes for the div."
+        }
+      },
+      "returns": {
+        "type": "VNode",
+        "desc": "A VNode element representing the div."
+      }
+    },
+    "getStringType": {
+      "desc": "Function to get the string representation of a type.",
+      "params": {
+        "type": {
+          "type": "Object",
+          "desc": "The type object to get the string representation for."
+        }
+      },
+      "returns": {
+        "type": "String",
+        "desc": "The string representation of the type."
+      }
+    }
+  },
+  "types": {}
+}

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

@@ -0,0 +1,28 @@
+{
+  "type": "component",
+  "meta": {
+    "docsUrl": "https://path-to-your-docs/markdown-card-link"
+  },
+  "props": {
+    "to": {
+      "type": "String",
+      "desc": "The target URL or path for the link",
+      "examples": [
+        "/home",
+        "https://example.com"
+      ],
+      "required": true,
+      "category": "navigation"
+    },
+    "external": {
+      "type": "Boolean",
+      "desc": "Flag to indicate if the link is external",
+      "category": "navigation"
+    }
+  },
+  "slots": {
+    "default": {
+      "desc": "Slot for custom content inside the link"
+    }
+  }
+}