Q-Press is a Quasar App Extension for building documentation sites from Markdown, Vue examples, generated API JSON, search indexes, and an optional static-site prerender pass.

What Q-Press Provides

• Markdown pages rendered as Vue route components.
• A generated docs shell with header, sidebar, table of contents, footer, dark mode, and theme support.
• Live example cards from Vue files in src/examples.
• API pages from Quasar-style JSON, including generated API JSON from TypeScript/JSDoc.
• Search UI backed by a static search index.
• Optional announcement banners, privacy consent, and restrained campaign dialogs.
• Optional SSG output for route-specific static HTML on static hosts.

Project-Owned Files

Q-Press has two kinds of files:

• Project-owned files are the files you normally edit: src/markdown, src/examples, src/components, src/siteConfig, src/css, and your normal router files.
• Generated shell files live in src/.q-press. They provide the layout, Markdown components, composables, API helpers, styles, SSG helpers, and generated route utilities.

When upgrading Q-Press, expect src/.q-press to be refreshed. Keep project-specific docs, examples, theme overrides, and navigation in project-owned folders.

Authoring Loop

1. Add or edit Markdown in src/markdown.
2. Add the page to src/siteConfig if it should appear in the header, sidebar, footer, or More menu.
3. Add Vue examples under src/examples/<topic> when a page needs live example cards.
4. Use Q-Press components such as MarkdownExample, MarkdownApi, MarkdownPage, and MarkdownCardLink inside Markdown when the page needs richer structure.
5. Customize the theme through src/css/quasar.variables.scss and runtime --qpress-* CSS variables.
6. Run pnpm check:qpress before release.
7. Build with pnpm build for SPA output or pnpm build:ssg for static route HTML.

Route Conventions

Markdown files become route components. The route path follows the file path under src/markdown.

src/markdown/getting-started/introduction.md
  -> /getting-started/introduction

src/markdown/quasar-app-extensions/qpress/themes.md
  -> /quasar-app-extensions/qpress/themes

If the folder name and file name are the same, the generated route removes the repeated segment:

src/markdown/vite-plugins/vite-md-plugin/vite-md-plugin.md
  -> /vite-plugins/vite-md-plugin

The landing page is the special case. A landing-page.md route is mounted at / and usually uses meta: { fullscreen: true } so it can own the full hero layout. See Customizing The Landing Page for the focused guide.

Generated Route Manifest

Q-Press builds a route manifest from src/markdown/listing.ts during dev and build. The listing uses Vite’s import.meta.glob() so Markdown files stay lazy-loaded, HMR-aware, and visible to the bundler.

Each manifest entry contains the source file, generated route path, route name, Markdown component loader, and Q-Press route metadata. installQPressRoutes() registers those entries with Vue Router by calling router.addRoute() under the generated Q-Press layout route.

Keep custom Vue routes, such as tools, theme builders, or pages with their own layout, in src/router/routes.ts as normal route records.

Where To Go Next