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

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

@@ -0,0 +1,301 @@
+---
+title: Containers Plugin Advanced Topics
+desc: Containers plugin advanced topics for Markdown.
+---
+
+## Containers Plugin
+
+The `containers` plugin allows you to add custom containers for callouts, warnings, and more in your Markdown content. This section will cover the CSS used by the plugin, how you can customize the output with your own CSS, and the available options for configuring the plugin.
+
+### Type Information
+
+```ts
+import MarkdownIt from 'markdown-it'
+import Token from 'markdown-it/lib/token.mjs'
+import container from 'markdown-it-container'
+
+type Container = typeof container
+
+type CreateContainerFn = (
+  container: Container,
+  type: string,
+  defaultTitle: string,
+) => [Container, string, any?]
+
+interface ContainerDetails {
+  type: string
+  defaultTitle: string
+}
+
+interface ContainerOptions {
+  render(tokens: Token[], idx: number): string
+}
+
+/**
+ * Adds container support to a MarkdownIt instance.
+ *
+ * This function applies custom container plugins to the MarkdownIt parser.
+ *
+ * @param md - The MarkdownIt instance to which the container plugins will be added.
+ * @param containers - An array of ContainerDetails objects, each specifying a container type and its default title.
+ * @param createContainer - A function that creates and returns the container plugin configuration.
+ *
+ * @example
+ * const containers: ContainerDetails[] = [
+ *   { type: 'warning', defaultTitle: 'Warning' },
+ *   { type: 'tip', defaultTitle: 'Tip' },
+ *   { type: 'details', defaultTitle: 'Details' },
+ * ];
+ *
+ * function createContainer(
+ *   container: Container,
+ *   containerType: string,
+ *   defaultTitle: string
+ * ): [Container, string, ContainerOptions] {
+ *   const containerTypeLen = containerType.length;
+ *
+ *   return [
+ *     container,
+ *     containerType,
+ *     {
+ *       render(tokens: Token[], idx: number): string {
+ *         const token = tokens[idx];
+ *         const title =
+ *           token.info.trim().slice(containerTypeLen).trim() || defaultTitle;
+ *
+ *         if (containerType === 'details') {
+ *           return token.nesting === 1
+ *             ? `<details class="markdown-note markdown-note--${containerType}"><summary class="markdown-note__title">${title}</summary>\n`
+ *             : '</details>\n';
+ *         }
+ *
+ *         return token.nesting === 1
+ *           ? `<div class="markdown-note markdown-note--${containerType}"><p class="markdown-note__title">${title}</p>\n`
+ *           : '</div>\n';
+ *       },
+ *     },
+ *   ];
+ * }
+ *
+ */
+declare function containersPlugin(
+  md: MarkdownIt,
+  containers: ContainerDetails[],
+  createContainer: CreateContainerFn,
+): void
+
+export {
+  type Container,
+  type ContainerDetails,
+  type ContainerOptions,
+  type CreateContainerFn,
+  containersPlugin,
+}
+```
+
+### Default CSS
+
+By default, the `containers` plugin applies specific CSS classes to different types of containers. You can add these classes in your CSS to customize the appearance of containers.
+
+::: tip
+The following classes are in SCSS format.
+:::
+
+```scss
+.markdown-note {
+  font-size: $font-size;
+  border-radius: $generic-border-radius;
+  margin: 16px 0;
+  padding: 16px;
+  border-width: 1px;
+  border-style: solid;
+
+  > p,
+  > ul {
+    margin-bottom: 0;
+  }
+
+  &:not(.markdown-note--tip, .markdown-note--warning, .markdown-note--danger) {
+    background-color: $grey-2;
+    border-color: $separator-color;
+    .markdown-note__title,
+    .markdown-link,
+    .markdown-token {
+      color: $brand-primary;
+    }
+    .markdown-token {
+      border-color: $brand-primary;
+    }
+  }
+
+  &--tip {
+    background-color: scale-color($positive, $lightness: 85%);
+    border-color: $positive;
+    .markdown-note__title,
+    .markdown-link,
+    .markdown-token {
+      color: scale-color($positive, $lightness: -40%);
+    }
+    .markdown-token {
+      border-color: scale-color($positive, $lightness: -40%);
+    }
+  }
+
+  &--warning {
+    background-color: scale-color($warning, $lightness: 85%);
+    border-color: scale-color($warning, $lightness: -30%);
+    .markdown-note__title,
+    .markdown-link,
+    .markdown-token {
+      color: scale-color($warning, $lightness: -40%);
+    }
+    .markdown-token {
+      border-color: scale-color($warning, $lightness: -40%);
+    }
+  }
+
+  &--danger {
+    background-color: scale-color($negative, $lightness: 90%);
+    border-color: $negative;
+    .markdown-note__title,
+    .markdown-link,
+    .markdown-token {
+      color: $negative;
+    }
+    .markdown-token {
+      border-color: $negative;
+    }
+  }
+
+  &--details {
+    .markdown-note__title {
+      cursor: pointer;
+      display: list-item;
+    }
+
+    &:not([open]) > .markdown-note__title {
+      padding-bottom: 0;
+    }
+  }
+
+  &__title {
+    font-weight: 700;
+    letter-spacing: $letter-spacing-brand;
+    padding-bottom: 8px;
+  }
+}
+```
+
+### Customizing the CSS
+
+You can customize the appearance of containers by overriding the default CSS classes. Here are some examples of how you can customize the containers:
+
+#### Example 1: Customizing the Border Color
+
+```css
+.markdown-note--tip {
+  border-color: #3498db; /* Change the border color to blue */
+}
+```
+
+#### Example 2: Adding a Background Image
+
+```css
+.markdown-note {
+  background-image: url('path/to/your/image.png');
+  background-size: cover;
+  background-repeat: no-repeat;
+}
+```
+
+#### Example 3: Changing the Font Style
+
+```css
+.markdown-note__title {
+  font-family: 'Courier New', Courier, monospace; /* Change the font style */
+}
+```
+
+### Plugin Options
+
+The `containers` plugin provides several options for customization. Here are the available options and their descriptions:
+
+#### `type`
+
+- **Type**: `string`
+- **Description**: The type of the container (e.g., 'tip', 'warning', 'danger', 'details').
+
+#### `defaultTitle`
+
+- **Type**: `string`
+- **Description**: The default title to use if no specific title is provided in the Markdown.
+
+#### `render`
+
+- **Type**: `function`
+- **Description**: A custom render function to define how the container should be rendered.
+
+### Example Configuration
+
+Here is an example of how you can configure the `containers` plugin with custom options:
+
+```typescript
+import MarkdownIt from 'markdown-it'
+import type Token from 'markdown-it/lib/token.mjs'
+import { containersPlugin } from '@md-plugins/md-plugin-containers'
+import type {
+  ContainerDetails,
+  CreateContainerFn,
+  Container,
+  ContainerOptions,
+} from '@md-plugins/md-plugin-containers'
+
+const createContainer: CreateContainerFn = (
+  container: Container,
+  containerType: string,
+  defaultTitle: string,
+): [Container, string, ContainerOptions] => {
+  const containerTypeLen = containerType.length
+
+  return [
+    container,
+    containerType,
+    {
+      render(tokens: Token[], idx: number): string {
+        const token = tokens[idx]
+        if (!token) {
+          return ''
+        }
+
+        const title = token.info.trim().slice(containerTypeLen).trim() || defaultTitle
+
+        if (containerType === 'details') {
+          return token.nesting === 1
+            ? `<details class="markdown-note markdown-note--${containerType}"><summary class="markdown-note__title">${title}</summary>\n`
+            : '</details>\n'
+        }
+
+        return token.nesting === 1
+          ? `<div class="markdown-note markdown-note--${containerType}"><p class="markdown-note__title">${title}</p>\n`
+          : '</div>\n'
+      },
+    },
+  ]
+}
+
+const containers: ContainerDetails[] = [
+  { type: 'tip', defaultTitle: 'TIP' },
+  { type: 'warning', defaultTitle: 'WARNING' },
+  { type: 'danger', defaultTitle: 'WARNING' },
+  { type: 'details', defaultTitle: 'Details' },
+]
+
+const md = new MarkdownIt()
+md.use(containersPlugin, containers, createContainer)
+```
+
+### Conclusion
+
+By customizing the CSS classes and using the available plugin options, you can tailor the appearance and behavior of containers to match the style of your project. Experiment with different styles and configurations to find the one that works best for you.
+
+Happy coding!

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

@@ -0,0 +1,206 @@
+---
+title: Containers Plugin
+desc: Containers plugin for Markdown.
+---
+
+Welcome to the Containers Plugin documentation! This guide will provide you with an overview of the Containers plugin and its features.
+
+## What is the Containers Plugin?
+
+The Containers Plugin is a powerful tool that enhances the standard Markdown functionality by allowing you to create custom containers for different types of content blocks. It integrates seamlessly with Markdown-It to provide a flexible and customizable way to handle containers in your Markdown files.
+
+## Key Features
+
+- **Custom Containers**: Create custom containers for different types of content blocks like tips, warnings, and details.
+- **Default Titles**: Specify default titles for containers if no specific title is provided in the Markdown.
+- **Flexible Configuration**: Use a custom function to create and configure containers.
+
+## Examples
+
+Here are some examples of what you can achieve with the Containers Plugin:
+
+### Standard Container
+
+::: tip
+This is a tip container.
+:::
+
+```markup
+::: tip
+This is a tip container.
+:::
+```
+
+::: warning
+This is a warning container.
+:::
+
+```markup
+::: warning
+This is a warning container.
+:::
+```
+
+::: danger
+This is a danger container.
+:::
+
+```markup
+::: danger
+This is a danger container.
+:::
+```
+
+::: details
+This is a details container.
+:::
+
+```markup
+::: details
+This is a details container.
+:::
+```
+
+### Container with Custom Title
+
+::: warning Custom Warning Title
+This is a warning container with a custom title.
+:::
+
+```markup
+::: warning Custom Warning Title
+This is a warning container with a custom title.
+:::
+```
+
+## Name
+
+The official NPM name is `@md-plugins/md-plugin-containers`.
+
+## Installation
+
+You can install the Containers plugin using npm, yarn, or pnpm. Choose your preferred method below:
+
+```tabs
+<<| bash npm |>>
+npm install @md-plugins/md-plugin-containers
+<<| bash yarn |>>
+yarn add @md-plugins/md-plugin-containers
+<<| bash pnpm |>>
+pnpm add @md-plugins/md-plugin-containers
+```
+
+## Configuration
+
+After installing the plugin, you need to configure it in your Markdown-It setup. Here's an example of how to do that:
+
+```js
+import MarkdownIt from 'markdown-it'
+import { containersPlugin } from '@md-plugins/md-plugin-containers'
+import container from 'markdown-it-container'
+
+const md = new MarkdownIt()
+
+const containers = [
+  { type: 'warning', defaultTitle: 'Warning' },
+  { type: 'tip', defaultTitle: 'Tip' },
+  { type: 'details', defaultTitle: 'Details' },
+]
+
+function createContainer(container, containerType, defaultTitle) {
+  const containerTypeLen = containerType.length
+
+  return [
+    container,
+    containerType,
+    {
+      render(tokens, idx) {
+        const token = tokens[idx]
+        const title = token.info.trim().slice(containerTypeLen).trim() || defaultTitle
+
+        if (containerType === 'details') {
+          return token.nesting === 1
+            ? `<details class="markdown-note markdown-note--${containerType}"><summary class="markdown-note__title">${title}</summary>\n`
+            : '</details>\n'
+        }
+
+        return token.nesting === 1
+          ? `<div class="markdown-note markdown-note--${containerType}"><p class="markdown-note__title">${title}</p>\n`
+          : '</div>\n'
+      },
+    },
+  ]
+}
+
+md.use(containersPlugin, containers, createContainer)
+
+// Now you can use the Containers plugin in your Markdown content
+const result = md.render('::: tip\nThis is a tip container.\n:::')
+console.log(result)
+```
+
+### Options
+
+The Containers plugin accepts the following options:
+
+- **containers**: An array of `ContainerDetails` objects, each specifying a container type and its default title.
+- **createContainer**: A function that creates and returns the container plugin configuration.
+
+## Advanced Configuration
+
+For more advanced configurations, you can combine the Containers plugin with other Markdown-It plugins to enhance your Markdown content further. Here's an example:
+
+```js
+import MarkdownIt from 'markdown-it'
+import { containersPlugin } from '@md-plugins/md-plugin-containers'
+import markdownItAnchor from 'markdown-it-anchor'
+import markdownItToc from 'markdown-it-toc-done-right'
+import container from 'markdown-it-container'
+
+const md = new MarkdownIt()
+
+const containers = [
+  { type: 'warning', defaultTitle: 'Warning' },
+  { type: 'tip', defaultTitle: 'Tip' },
+  { type: 'details', defaultTitle: 'Details' },
+]
+
+function createContainer(container, containerType, defaultTitle) {
+  const containerTypeLen = containerType.length
+
+  return [
+    container,
+    containerType,
+    {
+      render(tokens, idx) {
+        const token = tokens[idx]
+        const title = token.info.trim().slice(containerTypeLen).trim() || defaultTitle
+
+        if (containerType === 'details') {
+          return token.nesting === 1
+            ? `<details class="markdown-note markdown-note--${containerType}"><summary class="markdown-note__title">${title}</summary>\n`
+            : '</details>\n'
+        }
+
+        return token.nesting === 1
+          ? `<div class="markdown-note markdown-note--${containerType}"><p class="markdown-note__title">${title}</p>\n`
+          : '</div>\n'
+      },
+    },
+  ]
+}
+
+md.use(containersPlugin, containers, createContainer).use(markdownItAnchor).use(markdownItToc)
+
+// Now you can use the Containers plugin along with other plugins in your Markdown content
+const result = md.render(
+  '::: tip\nThis is a tip container.\n:::\n\n# Table of Contents\n\n[[toc]]\n\n::: warning Custom Warning Title\nThis is a warning container with a custom title.\n:::',
+)
+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/frontmatter/advanced.md

@@ -0,0 +1,164 @@
+---
+title: Frontmatter Plugin Advanced Topics
+desc: Frontmatter plugin advanced topics for Markdown.
+---
+
+## Frontmatter Plugin
+
+The `frontmatter` plugin allows you to extract and process frontmatter content from your Markdown files. 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 { PluginWithOptions } from 'markdown-it'
+import matter from 'gray-matter'
+
+type GrayMatterOptions = matter.GrayMatterOption<string, GrayMatterOptions>
+
+/**
+ * Options of md-plugin-frontmatter
+ */
+interface FrontmatterPluginOptions {
+  /**
+   * Options of gray-matter
+   *
+   * @see https://github.com/jonschlinkert/gray-matter#options
+   */
+  grayMatterOptions?: GrayMatterOptions
+  /**
+   * Render the excerpt or not
+   *
+   * @default false
+   */
+  renderExcerpt?: boolean
+}
+
+declare module '@md-plugins/shared' {
+  interface MarkdownItEnv {
+    /**
+     * The raw Markdown content without frontmatter
+     */
+    content?: string
+    /**
+     * Whether render excerpt or not
+     */
+    renderExcerpt?: boolean
+    /**
+     * The excerpt that extracted by `md-plugin-frontmatter`
+     *
+     * - Would be the rendered HTML when `renderExcerpt` is enabled
+     * - Would be the raw Markdown when `renderExcerpt` is disabled
+     */
+    excerpt?: string
+    /**
+     * The frontmatter that extracted by `md-plugin-frontmatter`
+     */
+    frontmatter?: Record<string, unknown>
+  }
+}
+
+/**
+ * Get markdown frontmatter and excerpt
+ *
+ * Extract them into env
+ */
+declare const frontmatterPlugin: PluginWithOptions<FrontmatterPluginOptions>
+
+export { type FrontmatterPluginOptions, frontmatterPlugin }
+```
+
+### How It Works
+
+Frontmatter is a block of metadata at the top of a Markdown file, enclosed by triple dashes (`---`). The `frontmatter` plugin parses this block and makes the metadata available for use in your Markdown content.
+
+### Default Behavior
+
+By default, the `frontmatter` plugin extracts the frontmatter content and makes it available in the `env` object passed to the Markdown renderer. Here is an example of a Markdown file with frontmatter:
+
+```markdown
+---
+title: My Awesome Post
+date: 2023-10-01
+tags: [markdown, frontmatter, plugin]
+---
+```
+
+### Plugin Options
+
+The frontmatter plugin provides several options for customization. Here are the available options and their descriptions:
+
+#### `grayMatterOptions`
+
+- **Type**: `object`
+- **Description**: Options to pass to the `gray-matter` library for parsing frontmatter.
+
+#### `renderExcerpt`
+
+- **Type**: `boolean`
+- **Default**: `false`
+- **Description**: Whether to render the excerpt using the original `markdown-it` render method.
+
+### Example Configuration
+
+Here is an example of how you can configure the frontmatter plugin with custom options:
+
+```typescript
+import MarkdownIt from 'markdown-it'
+import { frontmatterPlugin } from '@md-plugins/md-plugin-frontmatter'
+
+const md = new MarkdownIt()
+
+md.use(frontmatterPlugin, {
+  grayMatterOptions: {
+    excerpt: true,
+    excerpt_separator: '<!-- more -->',
+  },
+  renderExcerpt: true,
+})
+```
+
+### Using Frontmatter in Templates
+
+Once the frontmatter is extracted and validated, 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 frontmatter in a Vue component:
+
+```html
+<template>
+  <div>
+    <h1>{{ frontmatter.title }}</h1>
+    <p>Published on: {{ frontmatter.date }}</p>
+    <p>Tags: {{ frontmatter.tags.join(', ') }}</p>
+  </div>
+</template>
+
+<script setup>
+  import { ref } from 'vue'
+
+  const frontmatter = ref({
+    title: 'My Awesome Post',
+    date: '2023-10-01',
+    tags: ['markdown', 'frontmatter', 'plugin'],
+  })
+</script>
+```
+
+### Handling Errors
+
+The frontmatter plugin includes error handling to ensure that any issues with parsing the frontmatter do not break the rendering process. If an error occurs, the plugin will log the error and continue rendering the content without the frontmatter.
+
+```typescript
+try {
+  // Parse frontmatter and content
+  ;({ data, content } = grayMatter(src, grayMatterOptions))
+} catch (error) {
+  console.error('Failed to parse frontmatter:', error)
+  data = {}
+  content = src
+  excerpt = undefined
+}
+```
+
+### Conclusion
+
+The frontmatter plugin is a powerful tool for extracting and processing metadata from your Markdown files. By customizing the parsing and validation logic, you can tailor the plugin to fit your specific needs. Remember, it is up to you to handle the extracted frontmatter 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!