@md-plugins/quasar-app-extension-q-press 0.1.0-alpha.26 → 0.1.0-alpha.28

package/README.md

@@ -2,6 +2,8 @@
 
 The Ultimate Markdown Solution for the Quasar Framework.
 
+See the [documentation](https://md-plugins.netlify.app/quasar-app-extensions/qpress/overview) for more information.
+
 ## Features
 
 - **Markdown**
@@ -63,25 +65,25 @@ The Ultimate Markdown Solution for the Quasar Framework.
 3. Modify your `quasar.config.ts`
 
 - ```ts
-  import { viteMdPlugin, type MenuItem } from '@md-plugins/vite-md-plugin'
-
+  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
-  return {
-  build: {
-  vitePlugins: [
-  // add this plugin
-  [
-  viteMdPlugin,
-  {
-  path: ctx.appPaths.srcDir + '/markdown',
-  menu: sidebar as MenuItem[],
-  },
-  ],
-  // ...
+    // 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[],
+              // options: myOptions as MarkdownOptions
+            },
+          ],
+          // ...
   ```
 
 4. Modify your `src/routes/routes.ts`
@@ -89,59 +91,54 @@ The Ultimate Markdown Solution for the Quasar Framework.
 - ```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
   ```
 
-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
@@ -149,13 +146,12 @@ export default routes
     <router-view />
   </template>
 
-
   <script setup lang="ts">
-  import { useDark } from 'src/.q-press/composables/dark'
-  const { initDark } = useDark()
-  initDark()
+    import { useDark } from 'src/.q-press/composables/dark'
+    const { initDark } = useDark()
+    initDark()
   </script>
-````
+  ```
 
 ## Running the App
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@md-plugins/quasar-app-extension-q-press",
-  "version": "0.1.0-alpha.26",
+  "version": "0.1.0-alpha.28",
   "description": "QPress - The Ultimate Markdown Solution for Quasar Framework",
   "author": "hawkeye64 <galbraith64@gmail.com>",
   "keywords": [
@@ -29,19 +29,19 @@
   "dependencies": {
     "@types/markdown-it": "^14.1.2",
     "markdown-it": "^14.1.0",
-    "@md-plugins/md-plugin-blockquote": "0.1.0-alpha.26",
-    "@md-plugins/md-plugin-codeblocks": "0.1.0-alpha.26",
-    "@md-plugins/md-plugin-frontmatter": "0.1.0-alpha.26",
-    "@md-plugins/md-plugin-image": "0.1.0-alpha.26",
-    "@md-plugins/md-plugin-headers": "0.1.0-alpha.26",
-    "@md-plugins/md-plugin-containers": "0.1.0-alpha.26",
-    "@md-plugins/md-plugin-imports": "0.1.0-alpha.26",
-    "@md-plugins/md-plugin-inlinecode": "0.1.0-alpha.26",
-    "@md-plugins/md-plugin-link": "0.1.0-alpha.26",
-    "@md-plugins/md-plugin-table": "0.1.0-alpha.26",
-    "@md-plugins/md-plugin-title": "0.1.0-alpha.26",
-    "@md-plugins/shared": "0.1.0-alpha.26",
-    "@md-plugins/vite-md-plugin": "0.1.0-alpha.26"
+    "@md-plugins/md-plugin-blockquote": "0.1.0-alpha.28",
+    "@md-plugins/md-plugin-containers": "0.1.0-alpha.28",
+    "@md-plugins/md-plugin-headers": "0.1.0-alpha.28",
+    "@md-plugins/md-plugin-imports": "0.1.0-alpha.28",
+    "@md-plugins/md-plugin-frontmatter": "0.1.0-alpha.28",
+    "@md-plugins/md-plugin-image": "0.1.0-alpha.28",
+    "@md-plugins/md-plugin-inlinecode": "0.1.0-alpha.28",
+    "@md-plugins/md-plugin-table": "0.1.0-alpha.28",
+    "@md-plugins/md-plugin-link": "0.1.0-alpha.28",
+    "@md-plugins/md-plugin-title": "0.1.0-alpha.28",
+    "@md-plugins/md-plugin-codeblocks": "0.1.0-alpha.28",
+    "@md-plugins/vite-md-plugin": "0.1.0-alpha.28",
+    "@md-plugins/shared": "0.1.0-alpha.28"
   },
   "devDependencies": {
     "@types/markdown-it": "^14.1.2",

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

@@ -118,9 +118,10 @@ The following classes are in SCSS format.
   }
 
   &:not(.markdown-note--tip, .markdown-note--warning, .markdown-note--danger) {
-    background-color: $grey-2;
+    color: $brand-light-text;
+    background-color: $brand-light-bg;
     border-color: $separator-color;
-    .markdown-note__title,
+    // .markdown-note__title,
     .markdown-link,
     .markdown-token {
       color: $brand-primary;
@@ -128,9 +129,14 @@ The following classes are in SCSS format.
     .markdown-token {
       border-color: $brand-primary;
     }
+    & strong {
+      font-weight: 700;
+      color: scale-color($brand-light-text, $lightness: 90%);
+    }
   }
 
   &--tip {
+    color: scale-color($positive, $lightness: -40%) !important;
     background-color: scale-color($positive, $lightness: 85%);
     border-color: $positive;
     .markdown-note__title,
@@ -141,9 +147,14 @@ The following classes are in SCSS format.
     .markdown-token {
       border-color: scale-color($positive, $lightness: -40%);
     }
+    & strong {
+      font-weight: 700;
+      color: scale-color($positive, $lightness: 90%);
+    }
   }
 
   &--warning {
+    color: scale-color($warning, $lightness: -40%);
     background-color: scale-color($warning, $lightness: 85%);
     border-color: scale-color($warning, $lightness: -30%);
     .markdown-note__title,
@@ -154,9 +165,14 @@ The following classes are in SCSS format.
     .markdown-token {
       border-color: scale-color($warning, $lightness: -40%);
     }
+    & strong {
+      font-weight: 700;
+      color: scale-color($warning, $lightness: 90%);
+    }
   }
 
   &--danger {
+    color: scale-color($negative, $lightness: -40%);
     background-color: scale-color($negative, $lightness: 90%);
     border-color: $negative;
     .markdown-note__title,
@@ -167,6 +183,11 @@ The following classes are in SCSS format.
     .markdown-token {
       border-color: $negative;
     }
+
+    & strong {
+      font-weight: 700;
+      color: scale-color($negative, $lightness: 90%);
+    }
   }
 
   &--details {

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

@@ -7,7 +7,7 @@ desc: Headers plugin advanced topics for Markdown.
 
 The `headers` plugin allows you to add custom classes to headers and generate a table of contents (TOC) in your Markdown content. This section will cover how the plugin works, the available options for customization, and examples of how to use it effectively.
 
-### Type Infformation
+### Type Information
 
 ```ts
 import { PluginWithOptions } from 'markdown-it'
@@ -44,6 +44,22 @@ interface HeadersPluginOptions {
    * @default false
    */
   shouldAllowNested?: boolean
+  /**
+   * Should allow API headers
+   *
+   * If set to `true`, headers for `<MarkdownAPI>` title would also be extracted.
+   *
+   * @default true
+   */
+  shouldAllowApi?: boolean
+  /**
+   * Should allow Example headers
+   *
+   * If set to `true`, headers for `<MarkdownExample>` title would also be extracted.
+   *
+   * @default true
+   */
+  shouldAllowExample?: boolean
 }
 
 interface TocItem {
@@ -67,168 +83,6 @@ declare const headersPlugin: PluginWithOptions<HeadersPluginOptions>
 export { type HeadersPluginOptions, type TocItem, headersPlugin }
 ```
 
-### How It Works
-
-The `headers` plugin processes headers in your Markdown content, adding custom classes and generating a TOC. The TOC is stored in the `env` object passed to the Markdown renderer.
-
-### Default Behavior
-
-By default, the `headers` plugin adds custom classes to headers and generates a TOC for headers at levels 2 and 3. Here is an example of a Markdown file with headers:
-
-```markdown
-# My Awesome Post
-
-## Introduction
-
-## Details
-
-### Subsection
-
-## Conclusion
-```
-
-### Plugin Options
-
-The `headers` plugin provides several options for customization. Here are the available options and their descriptions:
-
-#### `level`
-
-- **Type**: `number[]`
-- **Default**: `[2, 3]`
-- **Description**: The levels of headers to include in the TOC.
-
-#### `slugify`
-
-- **Type**: `function`
-- **Default**: `defaultSlugify`
-- **Description**: A custom function to generate slugs for the headers.
-
-#### `format`
-
-- **Type**: `function`
-- **Description**: A custom function to format the header titles.
-
-### Example Configuration
-
-Here is an example of how you can configure the `headers` plugin with custom options:
-
-```typescript
-import MarkdownIt from 'markdown-it'
-import { headersPlugin } from '@md-plugins/md-plugin-headers'
-import { slugify as customSlugify } from './custom-slugify'
-
-const md = new MarkdownIt()
-
-md.use(headersPlugin, {
-  level: [2, 3, 4],
-  slugify: customSlugify,
-  format: (str) => str.toUpperCase(),
-})
-```
-
-### Using the TOC
-
-Once the TOC is generated, it is stored in the `env` object. How you handle this data and send it to the front-end is up to you. Here is an example of how to use the TOC in a Vue component:
-
-```vue
-<template>
-  <div>
-    <h1>Table of Contents</h1>
-    <ul>
-      <li v-for="item in toc" :key="item.id">
-        <a :href="'#' + item.id">{{ item.title }}</a>
-        <ul v-if="item.sub">
-          <li v-for="subItem in item.sub" :key="subItem.id">
-            <a :href="'#' + subItem.id">{{ subItem.title }}</a>
-          </li>
-        </ul>
-      </li>
-    </ul>
-  </div>
-</template>
-
-<script setup>
-import { ref } from 'vue'
-
-const toc = ref([
-  { id: 'introduction', title: 'Introduction' },
-  { id: 'details', title: 'Details', sub: [{ id: 'subsection', title: 'Subsection' }] },
-  { id: 'conclusion', title: 'Conclusion' },
-])
-</script>
-```
-
-### Default CSS
-
-By default, the `headers` plugin applies specific CSS classes to different levels of headers. You can add these classes in your CSS to customize the appearance of headers.
-
-```scss
-.markdown-h1 {
-  font-size: 2.4em !important;
-  font-weight: 700;
-  margin: 0 0 1em !important;
-  display: flex;
-  align-items: center;
-}
-
-.markdown-h2 {
-  font-size: 1.8em !important;
-  font-weight: 600;
-  padding-bottom: 8px !important;
-  border-bottom: 1px solid $separator-color;
-}
-
-.markdown-h3 {
-  font-size: 1.6em !important;
-  font-weight: 500;
-}
-
-.markdown-h4 {
-  font-size: 1.4em !important;
-  font-weight: 500;
-  &:before {
-    content: '» ';
-    vertical-align: text-top;
-  }
-}
-
-.markdown-h5 {
-  font-size: 1em !important;
-  font-weight: 500;
-  &:before {
-    content: '»» ';
-    vertical-align: text-top;
-  }
-}
-
-.markdown-h6 {
-  font-size: 1em !important;
-  font-weight: 400;
-  &:before {
-    content: '»»» ';
-    vertical-align: text-top;
-  }
-}
-
-@media (max-width: 850px) {
-  .markdown-h1 {
-    font-size: 1.7em !important;
-  }
-  .markdown-h2 {
-    font-size: 1.4em !important;
-  }
-  .markdown-h3 {
-    font-size: 1.3em !important;
-  }
-  .markdown-h4 {
-    font-size: 1.2em !important;
-  }
-  .markdown-h5 {
-    font-size: 1.1em !important;
-  }
-}
-```
-
 ### Conclusion
 
 The `headers` plugin is a powerful tool for adding custom classes to headers and generating a TOC in your Markdown content. By customizing the levels, slugify function, and format function, you can tailor the plugin to fit your specific needs. Remember, it is up to you to handle the generated TOC data and send it to the front-end in a way that suits your application. Experiment with different configurations and find the one that works best for you.

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

@@ -82,6 +82,8 @@ md.use(headersPlugin, {
   slugify: (str) => str.toLowerCase().replace(/\s+/g, '-'), // Optional: Customize slugification
   format: (str) => str.toUpperCase(), // Optional: Customize header formatting
   shouldAllowNested: true, // Optional: Allow headers inside nested blocks
+  shouldAllowApi = true, // Optional: Allow headers from api title
+  shouldAllowExample = true, // Optional: Allow headers from example title
 })
 
 // Now you can use the Headers plugin in your Markdown content
@@ -98,6 +100,8 @@ The Headers plugin accepts the following options:
 - **level**: Heading levels to be extracted. Should be a subset of markdown-it-anchor's level option to ensure the slug exists. Default is `[2, 3]`.
 
 - **shouldAllowNested**: Should allow headers inside nested blocks or not. Default is `false`.
+- **shouldAllowApi**: Should allow headers from api title or not. Default is `true`.
+- **shouldAllowExample**: Should allow headers from example title or not. Default is `true`.
 
 ## Advanced Configuration
 
@@ -116,6 +120,8 @@ md.use(headersPlugin, {
   slugify: (str) => str.toLowerCase().replace(/\s+/g, '-'), // Customize slugification
   format: (str) => str.toUpperCase(), // Customize header formatting
   shouldAllowNested: true, // Allow headers inside nested blocks
+  shouldAllowApi = true, // Optional: Allow headers from api blocks
+  shouldAllowExample = true, // Optional: Allow headers from example blocks
 })
   .use(markdownItAnchor)
   .use(markdownItToc)

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

@@ -101,7 +101,7 @@ Import Q-Press styles:
 ```ts [maxheight=400px]
 import { defineConfig } from '#q-app/wrappers'
 import type { Plugin } from 'vite'
-import { viteMdPlugin, type MenuItem } from '@md-plugins/vite-md-plugin'
+import { viteMdPlugin, type MenuItem, type MarkdownOptions } from '@md-plugins/vite-md-plugin'
 
 export default defineConfig(async (ctx) => {
   // Dynamically import siteConfig
@@ -117,6 +117,7 @@ export default defineConfig(async (ctx) => {
           {
             path: ctx.appPaths.srcDir + '/markdown',
             menu: sidebar as MenuItem[],
+            // options: myOptions as MarkdownOptions
           },
         ],
         // other plugins...

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

@@ -11,6 +11,30 @@ The `viteMdPlugin` is a powerful tool for integrating Markdown processing into y
 
 ```ts
 import { Plugin } from 'vite'
+import { Options } from 'markdown-it'
+import { BlockquotePluginOptions } from '@md-plugins/md-plugin-blockquote'
+import { CodeblockPluginOptions } from '@md-plugins/md-plugin-codeblocks'
+import { FrontmatterPluginOptions } from '@md-plugins/md-plugin-frontmatter'
+import { HeadersPluginOptions } from '@md-plugins/md-plugin-headers'
+import { ImagePluginOptions } from '@md-plugins/md-plugin-image'
+import { InlineCodePluginOptions } from '@md-plugins/md-plugin-inlinecode'
+import { LinkPluginOptions } from '@md-plugins/md-plugin-link'
+import { TablePluginOptions } from '@md-plugins/md-plugin-table'
+
+interface MarkdownOptions extends Options {
+  html?: boolean
+  linkify?: boolean
+  typographer?: boolean
+  breaks?: boolean
+  blockquote?: BlockquotePluginOptions
+  codeblocks?: CodeblockPluginOptions
+  frontmatter?: FrontmatterPluginOptions
+  headers?: HeadersPluginOptions | boolean
+  image?: ImagePluginOptions
+  inlinecode?: InlineCodePluginOptions
+  link?: LinkPluginOptions
+  table?: TablePluginOptions
+}
 
 interface MenuItem {
   name: string
@@ -24,12 +48,14 @@ interface MenuItem {
   external?: boolean
   expanded?: boolean
 }
+
 interface MenuNode {
   name: string
   path?: string
   external?: boolean
   children?: MenuNode[]
 }
+
 interface FlatMenuEntry {
   name: string
   category: string | null
@@ -37,18 +63,23 @@ interface FlatMenuEntry {
   prev?: FlatMenuEntry
   next?: FlatMenuEntry
 }
+
 type FlatMenu = Record<string, FlatMenuEntry>
+
 interface NavItem extends FlatMenuEntry {
   classes: string
 }
+
 interface RelatedItem {
   name: string
   category: string
   path: string
 }
+
 interface UserConfig {
   path: string
   menu: MenuItem[]
+  config?: MarkdownOptions
 }
 
 /**
@@ -58,6 +89,7 @@ interface UserConfig {
  * @param userConfig - The configuration object for the Vite Markdown plugin.
  * @param userConfig.path - The base path prefix to be used for routing or file resolution.
  * @param userConfig.menu - An array of MenuItem objects representing the navigation menu structure.
+ * @param userConfig.config - Additional configuration options for the Markdown processing.
  * @returns A Vite Plugin object pre-configured with the provided settings for Markdown processing.
  */
 declare function viteMdPlugin(userConfig: UserConfig): Plugin
@@ -65,6 +97,7 @@ declare function viteMdPlugin(userConfig: UserConfig): Plugin
 export {
   type FlatMenu,
   type FlatMenuEntry,
+  type MarkdownOptions,
   type MenuItem,
   type MenuNode,
   type NavItem,
@@ -102,7 +135,7 @@ If you’re using the Quasar Framework with Vite, additional configuration is ne
 1. Update `quasar.config.(js|ts)`:
 
 ```typescript
-import { viteMdPlugin } from '@md-plugins/vite-md-plugin';
+import { viteMdPlugin, type MenuItem, type MarkdownOptions } from '@md-plugins/vite-md-plugin'
 import { menu } from './src/assets/menu'; // be sure to create this file
 
 export default defineConfig((ctx) => {
@@ -120,6 +153,7 @@ export default defineConfig((ctx) => {
         {
           path: ctx.appPaths.srcDir + '/markdown',
           menu: sidebar as MenuItem[],
+          // options: myOptions as MarkdownOptions
         },
       ],
       // ...
@@ -176,6 +210,38 @@ export interface MenuItem {
 }
 ```
 
+#### `config`
+
+- **Type**: `MarkdownOptions`
+- **Description**: Additional configuration options for the Markdown processing.
+
+````ts
+import { Options } from 'markdown-it';
+import { BlockquotePluginOptions } from '@md-plugins/md-plugin-blockquote';
+import { CodeblockPluginOptions } from '@md-plugins/md-plugin-codeblocks';
+import { FrontmatterPluginOptions } from '@md-plugins/md-plugin-frontmatter';
+import { HeadersPluginOptions } from '@md-plugins/md-plugin-headers';
+import { ImagePluginOptions } from '@md-plugins/md-plugin-image';
+import { InlineCodePluginOptions } from '@md-plugins/md-plugin-inlinecode';
+import { LinkPluginOptions } from '@md-plugins/md-plugin-link';
+import { TablePluginOptions } from '@md-plugins/md-plugin-table';
+
+interface MarkdownOptions extends Options {
+    html?: boolean;
+    linkify?: boolean;
+    typographer?: boolean;
+    breaks?: boolean;
+    blockquote?: BlockquotePluginOptions;
+    codeblocks?: CodeblockPluginOptions;
+    frontmatter?: FrontmatterPluginOptions;
+    headers?: HeadersPluginOptions | boolean;
+    image?: ImagePluginOptions;
+    inlinecode?: InlineCodePluginOptions;
+    link?: LinkPluginOptions;
+    table?: TablePluginOptions;
+}
+```
+
 ### Example Configuration
 
 Here is an example of how you can configure the `viteMdPlugin` with custom options:
@@ -195,7 +261,7 @@ const basePath = '/docs'
 export default defineConfig({
   plugins: [vue(), viteMdPlugin(basePath, menu)],
 })
-```
+````
 
 ### Using the Plugin
 
@@ -217,7 +283,7 @@ When you build your project, the `viteMdPlugin` will process this Markdown file
 
 ## Advanced
 
-If you need to change the behavior of `viteMdPlugin`, you can create your own Vite plugin and use that instead. Look at the source to see how it can be done.
+If you need to change the behavior of `viteMdPlugin`, you can make behavioral changes via the `MarkdownOptions`, or you can create your own Vite plugin and use that instead. Look at the source to see how it can be done.
 
 ## Conclusion
 

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

@@ -99,6 +99,7 @@ build: {
       {
         path: ctx.appPaths.srcDir + '/markdown',
         menu: sidebar as MenuItem[],
+        // options: myOptions as MarkdownOptions
       },
     ],
     // ...