@md-plugins/quasar-app-extension-q-press 0.1.0-alpha.27 → 0.1.0-alpha.29

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@md-plugins/quasar-app-extension-q-press",
-  "version": "0.1.0-alpha.27",
+  "version": "0.1.0-alpha.29",
   "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-frontmatter": "0.1.0-alpha.27",
-    "@md-plugins/md-plugin-blockquote": "0.1.0-alpha.27",
-    "@md-plugins/md-plugin-containers": "0.1.0-alpha.27",
-    "@md-plugins/md-plugin-imports": "0.1.0-alpha.27",
-    "@md-plugins/md-plugin-image": "0.1.0-alpha.27",
-    "@md-plugins/md-plugin-table": "0.1.0-alpha.27",
-    "@md-plugins/md-plugin-inlinecode": "0.1.0-alpha.27",
-    "@md-plugins/md-plugin-headers": "0.1.0-alpha.27",
-    "@md-plugins/md-plugin-link": "0.1.0-alpha.27",
-    "@md-plugins/md-plugin-codeblocks": "0.1.0-alpha.27",
-    "@md-plugins/shared": "0.1.0-alpha.27",
-    "@md-plugins/md-plugin-title": "0.1.0-alpha.27",
-    "@md-plugins/vite-md-plugin": "0.1.0-alpha.27"
+    "@md-plugins/md-plugin-blockquote": "0.1.0-alpha.29",
+    "@md-plugins/md-plugin-codeblocks": "0.1.0-alpha.29",
+    "@md-plugins/md-plugin-containers": "0.1.0-alpha.29",
+    "@md-plugins/md-plugin-frontmatter": "0.1.0-alpha.29",
+    "@md-plugins/md-plugin-headers": "0.1.0-alpha.29",
+    "@md-plugins/md-plugin-image": "0.1.0-alpha.29",
+    "@md-plugins/md-plugin-imports": "0.1.0-alpha.29",
+    "@md-plugins/md-plugin-inlinecode": "0.1.0-alpha.29",
+    "@md-plugins/md-plugin-link": "0.1.0-alpha.29",
+    "@md-plugins/md-plugin-table": "0.1.0-alpha.29",
+    "@md-plugins/shared": "0.1.0-alpha.29",
+    "@md-plugins/md-plugin-title": "0.1.0-alpha.29",
+    "@md-plugins/vite-md-plugin": "0.1.0-alpha.29"
   },
   "devDependencies": {
     "@types/markdown-it": "^14.1.2",

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/md-plugins/shared/overview.md

@@ -44,7 +44,6 @@ declare const htmlUnescape: (str: string) => string
 interface MarkdownItEnv {
   plugins?: Record<string, unknown>
 }
-
 interface MarkdownItHeader {
   /**
    * The slug of the header
@@ -73,6 +72,16 @@ interface MarkdownItHeader {
    */
   children: MarkdownItHeader[]
 }
+type ResolvePluginOptionsFn = <T extends object, K extends keyof any>(
+  options:
+    | T
+    | {
+        [P in K]?: T
+      }
+    | undefined,
+  key: K,
+  defaults: T,
+) => T
 
 interface ResolveTitleOptions {
   /**
@@ -90,7 +99,6 @@ interface ResolveTitleOptions {
    */
   shouldEscapeText: boolean
 }
-
 /**
  * Resolve header title from markdown-it token
  *
@@ -103,7 +111,7 @@ declare const resolveTitleFromToken: (
 
 interface ResolveHeadersOptions extends ResolveTitleOptions {
   /**
-   * Heading level that is going to be resolved; ie: `1` to `6`
+   * Heading level that going to be resolved
    */
   level: number[]
   /**
@@ -123,7 +131,6 @@ interface ResolveHeadersOptions extends ResolveTitleOptions {
    */
   format?: (str: string) => string | undefined
 }
-
 /**
  * Resolve headers from markdown-it tokens
  */
@@ -144,14 +151,27 @@ declare const resolveHeadersFromTokens: (
  */
 declare const slugify: (str: string) => string
 
+declare function resolvePluginOptions<T extends object, K extends keyof any>(
+  options:
+    | T
+    | {
+        [key in K]?: T
+      }
+    | undefined,
+  key: K,
+  defaults: T,
+): T
+
 export {
   type MarkdownItEnv,
   type MarkdownItHeader,
   type ResolveHeadersOptions,
+  type ResolvePluginOptionsFn,
   type ResolveTitleOptions,
   htmlEscape,
   htmlUnescape,
   resolveHeadersFromTokens,
+  resolvePluginOptions,
   resolveTitleFromToken,
   slugify,
 }

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,
@@ -177,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:
@@ -196,7 +261,7 @@ const basePath = '/docs'
 export default defineConfig({
   plugins: [vue(), viteMdPlugin(basePath, menu)],
 })
-```
+````
 
 ### Using the Plugin
 
@@ -218,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