@md-plugins/quasar-app-extension-q-press NPM

Q-Press

The Ultimate Markdown Solution for the Quasar Framework.

See the documentation for more information.

Features

Markdown
Dark Mode
Landing Page
Markdown Layouts
Markdown Components
siteConfig
CSS Themes
Automatic Routing

Installation

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.global.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.global.d.ts

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

Add prismjs to your project dependencies

npm i prismjs
yarn add prismjs
pnpm add prismjs

Modifications

Modify your src/css/quasar.variables.scss

import a Q-Press theme (default, sunrise, newspaper, tawny, mystic, your own or a 3rd-party theme)

@import '../.q-press/css/themes/sunrise.scss';

Modify your src/css/app.scss

import Q-Press styles

@import '../.q-press/css/app.scss';
@import '../.q-press/css/fonts.scss';
@import '../.q-press/css/prism-theme.scss';

Modify your quasar.config.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
  return {
    build: {
      vitePlugins: [
        // add this plugin
        [
          viteMdPlugin,
          {
            path: ctx.appPaths.srcDir + '/markdown',
            menu: sidebar as MenuItem[],
            // options: myOptions as MarkdownOptions
          },
        ],
        // ...

Modify your src/routes/routes.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

Set up for Dark mode support, update your App.vue

<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 quasar dev and quasar dev. You can test it out now and you will have running the MD-Plugins web site.

All you need to do now is change the configuration and landing page to make it your own.

Configuration

Modify `src/siteConfig/index.ts`

Make any appropriate changes to the siteConfig.ts file

Modify `src/components/LandingPage/LandingPage.vue`

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:

      '@typescript-eslint/no-unused-vars': [
        'error',
        {
          argsIgnorePattern: '^_',
          ignoreRestSiblings: true,
          varsIgnorePattern: '^_',
        },
      ],

Q. Everytime 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 [:

  {
    /**
     * 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.global.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: