feat(desktop): embed BoosAPI Desktop client as a subproject
Vendor the rebranded BoosAPI Desktop client (Tauri + Vue) into metapi as a monorepo subdirectory under desktop/. Source only — node_modules, dist, Cargo target and the upstream .git history are excluded. desktop/ keeps its own independent Cargo workspace (desktop/src-tauri with crates/*); it is not part of the backend boosapi crate, so a `cargo check` at the metapi root still compiles only the backend. Build the desktop app from desktop/src-tauri per desktop/README.md. Note: app icons are still placeholder assets pending the final BoosAPI logo. The updater signing keys live outside the repo and are not included.
This commit is contained in:
boos
@@ -0,0 +1,107 @@
|
||||
# Troubleshooting
|
||||
|
||||
If you do not yet know whether the issue is CSS, peers, SSR, or custom-tag wiring, start with [Troubleshooting by Symptom](/guide/troubleshooting-path) first.
|
||||
|
||||
If something breaks, here are common fixes:
|
||||
|
||||
- If you get `window is not defined` during SSR, wrap components in `<client-only>` for Nuxt and use the `onMounted` guard for Vite SSR.
|
||||
- Install `katex` when math rendering fails, and import `katex/dist/katex.min.css` in your app entry.
|
||||
- For Mermaid issues, upgrade or pin `mermaid` to a version >= 11 and check asynchronous render logs.
|
||||
- If you load KaTeX/Mermaid via CDN `<script>`, make sure `window.katex` / `window.mermaid` exist before first render, or call `setKatexLoader(() => window.katex)` / `setMermaidLoader(() => window.mermaid)` once after they load.
|
||||
- For performance concerns, check that `viewportPriority` is true and avoid too many heavy nodes in a single mount.
|
||||
|
||||
If unsure, reproduce issue using the playground (or the hosted quick test) and then open an issue with stack trace and minimal markdown sample.
|
||||
|
||||
Hosted quick test: https://markstream-vue.simonhe.me/test
|
||||
|
||||
Open a new issue (quick link): https://github.com/Simon-He95/markstream-vue/issues/new?template=bug_report.yml
|
||||
|
||||
## Common problems (FAQ)
|
||||
|
||||
- Tailwind / CSS utilities overriding styling: If your project uses Tailwind or a component library (e.g., shadcn), utility classes or global styles may override the library's styles. See the Tailwind integration guide for recommended import ordering and strategies: [/guide/tailwind](/guide/tailwind).
|
||||
|
||||
Quick fixes:
|
||||
|
||||
- Import `markstream-vue/index.css` inside a `@layer components { ... }` block (see the Tailwind page). This controls style ordering.
|
||||
- Consider setting a `prefix` in Tailwind config (e.g., `tw-`) to avoid collisions with component library class names.
|
||||
- Use scoped selectors or `:deep` to target only the elements you need to override.
|
||||
|
||||
Note: `markstream-vue` scopes its packaged CSS under an internal `.markstream-vue` container (including theme variables and Tailwind utilities), so most conflicts come from ordering/resets inside the renderer area rather than global leakage.
|
||||
|
||||
- Want to tweak looks? You can customize via CSS variables in `src/index.css` (e.g., `--vscode-editor-background`, `--vscode-editor-foreground`) or override component classes in your app's stylesheet. Use the `@apply` helper or your own stylesheet to keep style rules isolated.
|
||||
|
||||
- Slots first: if the styling you want needs layout changes inside a component, check whether the component provides a named slot (e.g., `header-left`, `header-right`, `loading`). Slots are an easy and stable escape hatch that let you re-render interior markup without overriding internals.
|
||||
|
||||
- Still not enough? Use `setCustomComponents(id, mapping)` to replace an entire renderer for a node with your own Vue component. See the `Advanced` guide for `setCustomComponents` usage and how to scope them to a `custom-id`.
|
||||
Quick example (replace the renderer for `code_block` nodes scoped to `my-docs`):
|
||||
|
||||
```ts
|
||||
import { setCustomComponents } from 'markstream-vue'
|
||||
|
||||
setCustomComponents('my-docs', {
|
||||
code_block: MyCustomCodeBlock,
|
||||
})
|
||||
```
|
||||
|
||||
This will cause all `MarkdownRender` instances with `custom-id="my-docs"` to render the `code_block` node using `MyCustomCodeBlock` instead of the default. See `Advanced` for more examples.
|
||||
|
||||
- Repro / report flow: When you run into rendering anomalies or errors, try to reproduce them with the `playground` app and a minimal markdown sample. If it's still broken, run unit tests locally with `pnpm test` to rule out regressions. Then open an issue with:
|
||||
|
||||
1. Minimal markdown example that reproduces the problem (include in the issue body or link to a gist).
|
||||
2. Steps to reproduce (playground link or `playground` instructions), and the environment (browser, Node version, Vite/Nuxt).
|
||||
3. Any error stack traces and relevant console output.
|
||||
|
||||
Prefer to share a small `playground` reproduction and include a link; maintainers will triage and ask for more context if needed.
|
||||
|
||||
Extra tip: if you can write a unit/integration test that reproduces the bug, add it under the `test/` folder and run `pnpm test` locally — this is the fastest way for maintainers to validate and fix regressions.
|
||||
|
||||
## CSS looks wrong? Start here
|
||||
|
||||
Most rendering bugs are caused by style ordering, missing resets, or utility frameworks (Tailwind/UnoCSS) trumping component CSS. Run through this checklist before filing an issue:
|
||||
|
||||
1. **Reset browser defaults** — margins on `p`, `dl`, `table`, and `pre` differ per browser. Import a reset (`modern-css-reset`, `@unocss/reset`, or Tailwind's `@tailwind base`) *before* `markstream-vue` styles:
|
||||
|
||||
```css
|
||||
@import 'modern-css-reset';
|
||||
@tailwind base;
|
||||
@tailwind components;
|
||||
|
||||
@import 'markstream-vue/index.css';
|
||||
```
|
||||
|
||||
2. **Use CSS layers** — When Tailwind or UnoCSS runs in `@layer components` or `utilities`, wrap the library CSS import so the cascade is predictable:
|
||||
|
||||
```css
|
||||
@layer components {
|
||||
@import 'markstream-vue/index.css';
|
||||
}
|
||||
```
|
||||
|
||||
For UnoCSS, inject the CSS inside `preflights`:
|
||||
|
||||
```ts
|
||||
import { defineConfig, presetUno } from 'unocss'
|
||||
|
||||
export default defineConfig({
|
||||
presets: [presetUno()],
|
||||
preflights: [
|
||||
{
|
||||
layer: 'components',
|
||||
getCSS: () => '@import "markstream-vue/index.css";',
|
||||
},
|
||||
],
|
||||
})
|
||||
```
|
||||
|
||||
3. **Double-check peer CSS** — KaTeX ships CSS. Missing imports show up as invisible formulas. Mermaid does not require extra CSS.
|
||||
|
||||
4. **Scope overrides via `custom-id`** — When integrating with larger design systems, renderers can stomp on each other. Add `custom-id="docs"` to `MarkdownRender` and apply overrides scoped to `[data-custom-id="docs"]` so other layouts stay untouched.
|
||||
|
||||
If none of the above helps, reproduce the issue in the playground (`pnpm play`) with a CSS-only snippet and include the link when reporting the bug.
|
||||
|
||||
Quick test — run the playground locally to reproduce and debug:
|
||||
|
||||
```bash
|
||||
pnpm play
|
||||
# open the playground and reproduce the issue with a minimal Markdown sample
|
||||
```
|
||||
Reference in New Issue
Block a user