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

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

@@ -0,0 +1,131 @@
+---
+title: Frontmatter Plugin
+desc: Frontmatter plugin for Markdown.
+---
+
+Welcome to the Frontmatter Plugin documentation! This guide will provide you with an overview of the Frontmatter plugin and its features.
+
+## What is the Frontmatter Plugin?
+
+The Frontmatter Plugin is a powerful tool that enhances the standard Markdown functionality by allowing you to extract and process frontmatter and excerpts. It integrates seamlessly with Markdown-It to provide a flexible and customizable way to handle frontmatter in your Markdown files.
+
+## Key Features
+
+- **Frontmatter Extraction**: Extract frontmatter data from your Markdown files.
+- **Excerpt Rendering**: Optionally render excerpts from the frontmatter.
+- **Customizable Options**: Use custom options for the gray-matter library.
+
+## Examples
+
+Here are some examples of what you can achieve with the Frontmatter Plugin:
+
+### Standard Frontmatter
+
+```markup
+---
+title: My Document
+author: John Doe
+date: 2023-10-01
+---
+
+# My Document
+
+This is the content of my document.
+```
+
+### Frontmatter with Excerpt
+
+```markup
+---
+title: My Document
+author: John Doe
+date: 2023-10-01
+excerpt: This is a short summary of my document.
+---
+
+# My Document
+
+This is the content of my document.
+```
+
+## Name
+
+The official NPM name is `@md-plugins/md-plugin-frontmatter`.
+
+## Installation
+
+You can install the Frontmatter plugin using npm, yarn, or pnpm. Choose your preferred method below:
+
+```tabs
+<<| bash npm |>>
+npm install @md-plugins/md-plugin-frontmatter
+<<| bash yarn |>>
+yarn add @md-plugins/md-plugin-frontmatter
+<<| bash pnpm |>>
+pnpm add @md-plugins/md-plugin-frontmatter
+```
+
+## 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 { frontmatterPlugin } from '@md-plugins/md-plugin-frontmatter'
+
+const md = new MarkdownIt()
+
+md.use(frontmatterPlugin, {
+  grayMatterOptions: {
+    excerpt: true, // Enable excerpt extraction
+  },
+  renderExcerpt: true, // Optional: Render the excerpt
+})
+
+// Now you can use the Frontmatter plugin in your Markdown content
+const result = md.render(
+  '---\ntitle: My Document\nauthor: John Doe\ndate: 2023-10-01\nexcerpt: This is a short summary of my document.\n---\n\n# My Document\n\nThis is the content of my document.',
+)
+console.log(result)
+```
+
+### Options
+
+The Frontmatter plugin accepts the following options:
+
+- **grayMatterOptions**: Options for the gray-matter library. See [gray-matter options](https://github.com/jonschlinkert/gray-matter#options) for more details.
+- **renderExcerpt**: Render the excerpt or not. Default is `true`.
+
+## Advanced Configuration
+
+For more advanced configurations, you can combine the Frontmatter plugin with other Markdown-It plugins to enhance your Markdown content further. Here's an example:
+
+```javascript
+import MarkdownIt from 'markdown-it'
+import { frontmatterPlugin } from '@md-plugins/md-plugin-frontmatter'
+import markdownItAnchor from 'markdown-it-anchor'
+import markdownItToc from 'markdown-it-toc-done-right'
+
+const md = new MarkdownIt()
+
+md.use(frontmatterPlugin, {
+  grayMatterOptions: {
+    excerpt: true, // Enable excerpt extraction
+  },
+  renderExcerpt: true, // Render the excerpt
+})
+  .use(markdownItAnchor)
+  .use(markdownItToc)
+
+// Now you can use the Frontmatter plugin along with other plugins in your Markdown content
+const result = md.render(
+  '---\ntitle: My Document\nauthor: John Doe\ndate: 2023-10-01\nexcerpt: This is a short summary of my document.\n---\n\n# Table of Contents\n\n[[toc]]\n\n# My Document\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/md-plugins/headers/advanced.md

@@ -0,0 +1,236 @@
+---
+title: Headers Plugin Advanced Topics
+desc: Headers plugin advanced topics for Markdown.
+---
+
+## Headers Plugin
+
+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
+
+```ts
+import { PluginWithOptions } from 'markdown-it'
+
+/**
+ * Options of md-plugin-headers
+ */
+interface HeadersPluginOptions {
+  /**
+   * A custom slugification function
+   *
+   * Should use the same slugify function with markdown-it-anchor
+   * to ensure the link is matched
+   */
+  slugify?: (str: string) => string
+  /**
+   * A function for formatting header title
+   */
+  format?: (str: string) => string
+  /**
+   * Heading level that going to be extracted
+   *
+   * Should be a subset of markdown-it-anchor's `level` option
+   * to ensure the slug is existed
+   *
+   * @default [2,3]
+   */
+  level?: number[]
+  /**
+   * Should allow headers inside nested blocks or not
+   *
+   * If set to `true`, headers inside blockquote, list, etc. would also be extracted.
+   *
+   * @default false
+   */
+  shouldAllowNested?: boolean
+}
+
+interface TocItem {
+  id: string
+  title: string
+  sub?: boolean
+  deep?: boolean
+}
+
+declare module '@md-plugins/shared' {
+  interface MarkdownItEnv {
+    /**
+     * The toc that are extracted by `md-plugin-headers`
+     */
+    toc?: TocItem[]
+  }
+}
+
+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;
+  font-weight: 700;
+  margin: 0 0 1em !important;
+  display: flex;
+  align-items: center;
+}
+
+.markdown-h2 {
+  font-size: 1.8em;
+  font-weight: 600;
+  padding-bottom: 8px !important;
+  border-bottom: 1px solid $separator-color;
+}
+
+.markdown-h3 {
+  font-size: 1.6em;
+  font-weight: 500;
+}
+
+.markdown-h4 {
+  font-size: 1.4em;
+  font-weight: 500;
+  &:before {
+    content: '» ';
+    vertical-align: text-top;
+  }
+}
+
+.markdown-h5 {
+  font-size: 1em;
+  font-weight: 500;
+  &:before {
+    content: '»» ';
+    vertical-align: text-top;
+  }
+}
+
+.markdown-h6 {
+  font-size: 1em;
+  font-weight: 400;
+  &:before {
+    content: '»»» ';
+    vertical-align: text-top;
+  }
+}
+
+@media (max-width: 850px) {
+  .markdown-h1 {
+    font-size: 1.7em;
+  }
+  .markdown-h2 {
+    font-size: 1.4em;
+  }
+  .markdown-h3 {
+    font-size: 1.3em;
+  }
+  .markdown-h4 {
+    font-size: 1.2em;
+  }
+  .markdown-h5 {
+    font-size: 1.1em;
+  }
+}
+```
+
+### 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.
+
+Happy coding!

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

@@ -0,0 +1,134 @@
+---
+title: Headers Plugin
+desc: Headers plugin for Markdown.
+---
+
+Welcome to the Headers Plugin documentation! This guide will provide you with an overview of the Headers plugin and its features.
+
+## What is the Headers Plugin?
+
+The Headers Plugin is a powerful tool that enhances the standard header functionality in Markdown. It allows you to extract and format headers, making it easier to create a table of contents and navigate through your documentation.
+
+## Key Features
+
+- **Custom Slugification**: Use a custom slugification function to generate unique IDs for headers.
+- **Header Formatting**: Apply custom formatting to header titles.
+- **Heading Levels**: Specify which heading levels to extract.
+- **Nested Headers**: Optionally allow headers inside nested blocks to be extracted.
+
+## Examples
+
+Here are some examples of what you can achieve with the Headers Plugin:
+
+### Standard Header Extraction
+
+```markup
+# Main Title
+
+## Sub Title
+
+### Another Sub Title
+```
+
+### Custom Slugification and Formatting
+
+You can apply custom slugification and formatting to headers:
+
+```javascript
+import MarkdownIt from 'markdown-it'
+import { headersPlugin } from '@md-plugins/md-plugin-headers'
+
+const md = new MarkdownIt()
+
+md.use(headersPlugin, {
+  slugify: (str) => str.toLowerCase().replace(/\s+/g, '-'), // Custom slugification
+  format: (str) => str.toUpperCase(), // Custom formatting
+})
+
+// Now you can use the Headers plugin in your Markdown content
+const result = md.render('# Custom Header\n\n## Another Header')
+console.log(result)
+```
+
+## Name
+
+The official NPM name is `@md-plugins/md-plugin-headers`.
+
+## Installation
+
+You can install the Headers plugin using npm, yarn, or pnpm. Choose your preferred method below:
+
+```tabs
+<<| bash npm |>>
+npm install @md-plugins/md-plugin-headers
+<<| bash yarn |>>
+yarn add @md-plugins/md-plugin-headers
+<<| bash pnpm |>>
+pnpm add @md-plugins/md-plugin-headers
+```
+
+## 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 { headersPlugin } from '@md-plugins/md-plugin-headers'
+
+const md = new MarkdownIt()
+
+md.use(headersPlugin, {
+  level: [2, 3], // Optional: Specify which heading levels to extract
+  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
+})
+
+// Now you can use the Headers plugin in your Markdown content
+const result = md.render('# Main Title\n\n## Sub Title\n\n### Another Sub Title')
+console.log(result)
+```
+
+### Options
+
+The Headers plugin accepts the following options:
+
+- **slugify**: A custom slugification function. Should use the same slugify function with markdown-it-anchor to ensure the link is matched.
+- **format**: A function for formatting header titles.
+- **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`.
+
+## Advanced Configuration
+
+For more advanced configurations, you can combine the Headers plugin with other Markdown-It plugins to enhance your Markdown content further. Here's an example:
+
+```javascript
+import MarkdownIt from 'markdown-it'
+import { headersPlugin } from '@md-plugins/md-plugin-headers'
+import markdownItAnchor from 'markdown-it-anchor'
+import markdownItToc from 'markdown-it-toc-done-right'
+
+const md = new MarkdownIt()
+
+md.use(headersPlugin, {
+  level: [2, 3], // Specify which heading levels to extract
+  slugify: (str) => str.toLowerCase().replace(/\s+/g, '-'), // Customize slugification
+  format: (str) => str.toUpperCase(), // Customize header formatting
+  shouldAllowNested: true, // Allow headers inside nested blocks
+})
+  .use(markdownItAnchor)
+  .use(markdownItToc)
+
+// Now you can use the Headers plugin along with other plugins in your Markdown content
+const result = md.render(
+  '# Table of Contents\n\n[[toc]]\n\n# Main Title\n\n## Sub Title\n\n### Another Sub Title',
+)
+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/md-plugins/image/advanced.md

@@ -0,0 +1,114 @@
+---
+title: Image Plugin Advanced Topics
+desc: Image plugin advanced topics for Markdown.
+---
+
+## Image Plugin
+
+The `image` plugin allows you to add custom classes to images and ensure that the `alt` attribute is properly set in your Markdown content. It also allows you to provide a `width` and a `height`. 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 MarkdownIt from 'markdown-it'
+
+declare const imagePlugin: (
+  md: MarkdownIt,
+  {
+    imageClass,
+  }?: {
+    imageClass?: string | undefined
+  },
+) => void
+
+interface ImagePluginOptions {
+  /**
+   * The class for the image
+   *
+   * @default 'markdown-image'
+   */
+  imageClass?: string
+}
+
+export { type ImagePluginOptions, imagePlugin }
+```
+
+### How It Works
+
+The `image` plugin processes image tokens in your Markdown content, adding custom classes and ensuring that the `alt` attribute is properly set as well as setting the `width` and `height` attributes if set inside the `alt text` area of the image markdown. This helps improve the accessibility and styling of images in your Markdown content.
+
+### Default Behavior
+
+By default, the `image` plugin adds the `markdown-image` class to all images and sets the `alt` attribute to the image's content if it is not already set. It also allows you to specify the `width` and `height` of the displayed image. Here is an example of a Markdown file with images:
+
+```markdown
+![Alt text](path/to/image.jpg)
+
+![Another image](path/to/another-image.png)
+
+![Alt text width="200" height="200"](path/to/image.jpg)
+```
+
+### Plugin Options
+
+The `image` plugin provides an option for customization. Here is the available option and its description:
+
+#### imageClass
+
+- **Type**: `string`
+- **Default**: `'markdown-image'`
+- **Description**: The class to be added to all images.
+
+### Example Configuration
+
+Here is an example of how you can configure the `image` plugin with custom options:
+
+```typescript
+import MarkdownIt from 'markdown-it'
+import { imagePlugin } from '@md-plugins/md-plugin-image'
+
+const md = new MarkdownIt()
+
+md.use(imagePlugin, {
+  imageClass: 'custom-image-class',
+})
+```
+
+### Customizing the CSS
+
+You can customize the appearance of images by overriding the default CSS class. Here are some examples of how you can customize the images:
+
+#### Example 1: Customizing the Border
+
+```css
+.custom-image-class {
+  border: 2px solid #3498db; /* Add a blue border to images */
+}
+```
+
+#### Example 2: Adding a Shadow
+
+```css
+.custom-image-class {
+  box-shadow: 0 4px 8px rgba(0, 0, 0, 0.1); /* Add a shadow to images */
+}
+```
+
+#### Example 3: Changing the Size
+
+```css
+.custom-image-class {
+  width: 100%;
+  max-width: 600px; /* Set a maximum width for images */
+}
+```
+
+### Handling the `alt`, `width`, and `height` Attributes
+
+The `image` plugin ensures that the `alt` attribute is properly set for all images. If the `alt` attribute is not present or is empty, the plugin sets it to the image's content. Additionally, the plugin allows you to specify the `width` and `height` attributes within the `alt` text. These attributes are extracted and applied to the image element, and then removed from the `alt` text. This helps improve the accessibility and styling of your Markdown content.
+
+### Conclusion
+
+The `image` plugin is a powerful tool for adding custom classes to images and ensuring that the `alt`, `width`, and `height` attributes are properly set in your Markdown content. By customizing the class and CSS, you can tailor the appearance of images to match the style of your project. Experiment with different configurations and find the one that works best for you.
+
+Happy coding!