Q-Press

Q-Press is the Quasar documentation layer in md-plugins. It turns Markdown folders into routed docs sites with generated layouts, themes, live examples, API pages, static search, route validation, and SSG output.

See the documentation for more information.

Current stable release: 2.2.0.

Q-Press currently targets Quasar Vite projects using @quasar/app-vite >=3.0.0. TypeScript processing is required.

Features

• Markdown routes generated from src/markdown.
• Manifest-backed route registration through Vue Router addRoute().
• Q-Press layouts with sidebar, ToC, page headers, edit links, and landing-page support.
• Markdown components for APIs, examples, tabs, steps, callouts, and code blocks.
• Live examples and CodePen helpers powered by the examples plugin.
• Static search indexes generated by @md-plugins/vite-search-plugin.
• Search UI powered by the framework-agnostic @md-plugins/search-ui Web Component.
• SSG build helpers for static-host-friendly route output.
• Q-Press CLI for API generation, route checks, SSG, and release validation.

Q-Press builds a Markdown route manifest from src/markdown/listing.ts during dev and build. The generated installQPressRoutes() helper registers those Markdown routes under the Q-Press layout route with Vue Router's dynamic route API. App-owned pages such as theme builders or custom tools should remain explicit Vue Router records in src/router/routes.ts.

Installation

1. 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/components
  • src/markdown
  • src/examples
  • src/siteConfig
• Here is what gets installed on an update install:
  • src/.q-press

2. Install markdown-it in your project devDependencies

• npm i -D markdown-it
• yarn add -D markdown-it
• pnpm i -D markdown-it
• bun add -d markdown-it

3. Q-Press adds its docs build helpers to your project devDependencies when invoked. If you are wiring the generated files manually, add them yourself:

• npm i -D mermaid shiki @md-plugins/search-ui @md-plugins/vite-search-plugin @md-plugins/vite-ssg-plugin @vue/server-renderer
• yarn add -D mermaid shiki @md-plugins/search-ui @md-plugins/vite-search-plugin @md-plugins/vite-ssg-plugin @vue/server-renderer
• pnpm add -D mermaid shiki @md-plugins/search-ui @md-plugins/vite-search-plugin @md-plugins/vite-ssg-plugin @vue/server-renderer
• bun add -d mermaid shiki @md-plugins/search-ui @md-plugins/vite-search-plugin @md-plugins/vite-ssg-plugin @vue/server-renderer

Q-Press CLI

Q-Press exposes one primary CLI command with focused subcommands:

qpress api generate
qpress api check
qpress check
qpress ssg

Use qpress check before release or CI builds to validate Markdown routes, internal links, related frontmatter routes, siteConfig navigation routes, MarkdownExample files, Q-Press API JSON, and common SSG-unsafe example patterns. Unreachable Markdown page warnings are available with qpress check --check-unreachable for stricter release checks.

Use qpress api generate and qpress api check when TypeScript source and JSDoc are the source of truth for rendered MarkdownApi pages. Q-Press can document exported functions and documented exported constants, including object-shaped constants with nested properties and literal default values.

Check options can be kept in a project-local config file such as qpress.config.json or qpress.config.mjs:

{
  "check": {
    "allowedRoutes": ["/theme-builder"],
    "ignoreFiles": ["__*.md"]
  }
}

Unknown config keys and invalid value types fail fast so typos do not silently change release checks.

Use qpress ssg to prerender Q-Press routes into static HTML. The older qpress-ssg command remains available as a backwards-compatible alias, but new scripts should prefer qpress ssg so all Q-Press tooling is grouped under one command.

Development Notes

The generated Q-Press templates are copied from the docs app during the package build. packages/qPress/scripts/build.js copies packages/docs/src/.q-press into both template destinations:

• packages/qPress/src/templates/init/src/_q-press
• packages/qPress/src/templates/update/src/_q-press

When changing generated Q-Press components, edit packages/docs/src/.q-press first and rebuild Q-Press so both init and update templates stay aligned. Editing only a template copy can be lost the next time the package build runs.

Modifications

1. 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';

2. Modify your src/css/app.scss

• import Q-Press styles

• @import '../.q-press/css/app.scss';

3. Modify your quasar.config.ts

• import { viteMdPlugin, type MenuItem, type MarkdownOptions } from '@md-plugins/vite-md-plugin'
  import { viteSearchPlugin } from '@md-plugins/vite-search-plugin'
  
  export default defineConfig(async (ctx) => {
    // Dynamically import siteConfig
    const siteConfig = await import('./src/siteConfig')
    const { sidebar } = siteConfig.default
    return {
      build: {
        vitePlugins: [
          // add this plugin
          [
            viteMdPlugin,
            {
              path: ctx.appPaths.srcDir + '/markdown',
              menu: sidebar as MenuItem[],
              // options: myOptions as MarkdownOptions
            },
          ],
          viteSearchPlugin({
            markdown: {
              root: ctx.appPaths.srcDir + '/markdown',
              // Optional: keep generated test pages, drafts, or private docs out of search.
              exclude: [/\/__/],
            },
          }),
          // ...

  The search plugin emits search/search-index.json during production builds. The generated MarkdownSearch.vue wrapper uses @md-plugins/search-ui to provide the header search control and route selected results through Vue Router.

4. Modify your src/router/routes.ts

• import { createQPressLayoutRoute, createQPressNotFoundRoute } from '@/.q-press/router/routes'
  
  const routes = [
    // Keep app-owned custom routes here.
    createQPressLayoutRoute(),
    createQPressNotFoundRoute(),
  ]
  
  export default routes

5. Modify your src/router/index.ts

• import { installQPressRoutes } from '@/.q-press/router/routes'
  import { qpressRouteManifest } from '@/markdown/listing'
  
  // after createRouter(...)
  installQPressRoutes(router, qpressRouteManifest)

  Q-Press Markdown pages are registered from the generated route manifest. Keep custom Vue routes such as a docs-only Theme Builder in src/router/routes.ts.

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

• <template>
    <router-view />
  </template>
  
  <script setup lang="ts">
    import { useDark } from '@/.q-press/composables/dark'
    const { initDark } = useDark()
    initDark()
  </script>

Running the App

This is a Quasar app, so all you have to do is run quasar dev. You can test the generated Q-Press site immediately, then replace the starter content with your own docs.

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

Configuration

Modify src/siteConfig/index.ts

1. Make any appropriate changes to the siteConfig.ts file

Modify src/components/LandingPage/LandingPage.vue

1. 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. Update to the manifest-backed route setup shown above. src/router/routes.ts should keep custom Vue routes plus createQPressLayoutRoute() and createQPressNotFoundRoute(). src/router/index.ts should call installQPressRoutes(router, qpressRouteManifest) after creating the router.

Custom routes, such as a docs-only Theme Builder page, stay in routes.ts. Q-Press only adds Markdown routes from the manifest.

Q. Every time I save a Markdown file, the formatter changes syntax that Q-Press needs. How can I prevent this? A. Current Q-Press projects use oxfmt for repository formatting. Use pnpm format and pnpm format:check as the source of truth for Markdown formatting.

If your editor formats Markdown differently on save, configure it to use the workspace formatter or disable format-on-save for Markdown in that project. A project-level VS Code setting is usually enough:

{
  "[markdown]": {
    "editor.formatOnSave": false
  }
}

Updating

When you update, only the src/.q-press folder will be updated. 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:

quasar ext invoke @md-plugins/q-press

Documentation

In case this README falls out of date, please refer to the documentation for the latest information.

Support

If Q-Press is useful in your workflow and you want to support ongoing maintenance:

• GitHub Sponsors: https://github.com/sponsors/hawkeye64
• PayPal: https://paypal.me/hawkeye64

License

This project is licensed under the MIT License. See the LICENSE file for details.