From 9e4f2386f7fdca466c0b7be40c8c2cad9714e24e Mon Sep 17 00:00:00 2001 From: Drew Smirnoff Date: Fri, 29 May 2026 09:02:55 +0400 Subject: [PATCH] docs: support TIP CAUTION and other (#1376) ## What? Adds support for `[!TIP]` and other github's admonitions. ## Why? So it looks better, and can be read from GitHub and our [docs website](https://docs.matcha.email) --------- Signed-off-by: drew --- docs/docs/Features/Images.md | 5 +-- docs/docs/Features/PGP.md | 3 +- docs/docs/installation.md | 9 +++- docs/docs/setup-guides/gmail.md | 6 ++- docs/docs/setup-guides/icloud.md | 6 ++- docs/docusaurus.config.ts | 2 + docs/package-lock.json | 18 +++++++- docs/package.json | 3 +- docs/src/css/custom.css | 75 +++++++++++++++++++++++++++++++- 9 files changed, 114 insertions(+), 13 deletions(-) diff --git a/docs/docs/Features/Images.md b/docs/docs/Features/Images.md index f4cd672fbde8974295dee578bfc3f2c1ed6b3f8e..624c03ff75df3beb1f19c66b23c0f610b4bd0719 100644 --- a/docs/docs/Features/Images.md +++ b/docs/docs/Features/Images.md @@ -1,10 +1,9 @@ # Image Protocol Compatibility -> [!TIP] This feature is optional. To disable images, go to Settings > Image Display: OFF, you can also always turn it on for 1 email by pressing `i` - +> [!TIP] +> This feature is optional. To disable images, go to Settings > General > Disable Image Display: ON, you can also always turn it on for 1 email by pressing `i`. If you worry about security, we use a sandboxed subprocess for decoding on Linux (via Landlock + seccomp), via [termimage](https://github.com/floatpane/termimage), and we never execute any code from emails. Matcha supports modern terminal image protocols for displaying images directly in your terminal. This allows for rich email viewing with inline images, including those embedded in HTML emails (CID references), remote images, and base64-encoded data URIs. -Image rendering is powered by [termimage](https://github.com/floatpane/termimage), which handles protocol detection, decoding (in a sandboxed subprocess on Linux via Landlock + seccomp), and rendering for Kitty graphics, Sixel, and Unicode half-block fallback. ## Supported Protocols diff --git a/docs/docs/Features/PGP.md b/docs/docs/Features/PGP.md index 095f4ab3d245eb4fa06e98081449dba2eac0e64b..8f54890cecd66a143badd04af5361c37f56d36bf 100644 --- a/docs/docs/Features/PGP.md +++ b/docs/docs/Features/PGP.md @@ -168,7 +168,8 @@ Your configuration: } ``` -Note: The YubiKey PIN is stored in your OS keyring (e.g. GNOME Keyring, KDE Wallet, macOS Keychain) and is never saved to `config.json`. +> [!NOTE] +> The YubiKey PIN is stored in your OS keyring (e.g. GNOME Keyring, KDE Wallet, macOS Keychain) and is never saved to `config.json`. ### Moving Your GPG Key to a YubiKey diff --git a/docs/docs/installation.md b/docs/docs/installation.md index b7d8bc9388cd23109df3351b6532c748a98f73e9..76455e0f2074e9f6114af133c0a402afabcdb653 100644 --- a/docs/docs/installation.md +++ b/docs/docs/installation.md @@ -46,7 +46,8 @@ You can download pre-compiled binaries from the [Releases page](https://github.c ## 🐧 Linux -> Note: Homebrew support for Linux was [dropped](https://github.com/floatpane/matcha/pull/1360) (since matcha v0.40.0). You can still use Homebrew on Linux for nightly releases, but for stable releases, please use one of the other installation methods below. +> [!WARNING] +> Homebrew support for Linux was [dropped](https://github.com/floatpane/matcha/pull/1360) (since matcha [v0.40.0](https://github.com/flaotpane)). You can still use Homebrew on Linux for nightly releases, but for stable releases, please use one of the other installation methods below. ### Snap @@ -66,7 +67,8 @@ flatpak install https://matcha.email/matcha.flatpakref ### AUR (Arch Linux) (unofficial) -> Note: This is an unofficial package, not maintained by the Matcha team. Use at your own risk. For any issues with the AUR package, please contact the maintainer ([Dominiquini](https://github.com/Dominiquini)). +> [!NOTE] +> This is an unofficial package, not maintained by the Matcha team. Use at your own risk. For any issues with the AUR package, please contact the maintainer ([Dominiquini](https://github.com/Dominiquini)). If you're using Arch Linux, you can install Matcha from the AUR: @@ -134,6 +136,9 @@ Once you have WSL installed and set up, you can follow the [Linux](#-linux) inst ## 🏗️ Building from Source +> [!WARNING] +> Building from source is not recommended for most users, as it requires additional dependencies and setup. Only proceed if you are comfortable with development tools and want to contribute to the project or need a custom build. + If you have Go installed, you can build Matcha from source: ```bash diff --git a/docs/docs/setup-guides/gmail.md b/docs/docs/setup-guides/gmail.md index f85513a5b221c71412b3efc426b0c4ad20687ae1..ea70744671bab141633c8a7162108ab07fe95a5a 100644 --- a/docs/docs/setup-guides/gmail.md +++ b/docs/docs/setup-guides/gmail.md @@ -46,7 +46,8 @@ OAuth2 lets you authorize Matcha through Google's standard sign-in flow. No app ![OAuth consent screen](../assets/setup-guides/gmail/oauth-consent-screen.png) -> **Note:** Your app will be in "Testing" mode, which is perfectly fine for personal use. Google will show an "unverified app" warning during sign-in — just click **Continue**. Tokens in testing mode expire after 7 days, after which you'll need to re-authorize with `matcha gmail auth`. +> [!NOTE] +> Your app will be in "Testing" mode, which is perfectly fine for personal use. Google will show an "unverified app" warning during sign-in — just click **Continue**. Tokens in testing mode expire after 7 days, after which you'll need to re-authorize with `matcha gmail auth`. ### 4. Create OAuth credentials @@ -143,7 +144,8 @@ If you prefer not to set up OAuth2, you can use an app password instead. App Pas 4. Click **Generate**. 5. Copy the 16-character app password shown by Google. -> **⚠️ Important:** Treat this app password as you would your primary password. Never share it, or expose it publicly. This credential grants full access to your Gmail account. The app password sits locally in your device and is never shared with us. +> [!CAUTION] +> Treat this app password as you would your primary password. Never share it, or expose it publicly. This credential grants full access to your Gmail account. The app password sits locally in your device and is never shared with us. ![Generate Google App Password](../assets/setup-guides/gmail/generate-app-password.jpg) diff --git a/docs/docs/setup-guides/icloud.md b/docs/docs/setup-guides/icloud.md index a9d29b585958ada80f69f7e815af2828764be6c5..d803acddbbea126b3fa10f62982ecd8a76ea2e86 100644 --- a/docs/docs/setup-guides/icloud.md +++ b/docs/docs/setup-guides/icloud.md @@ -9,7 +9,8 @@ Matcha requires an app-specific password to access your iCloud Mail account. App ## 1. Enable two-factor authentication (if not enabled) -> If you already use two-factor authentication you can skip this step. +> [!NOTE] +> If you already use two-factor authentication you can skip this step. ![MacOS settings](../assets/setup-guides/icloud/settings.jpg) @@ -40,7 +41,8 @@ On a Mac, go to **System Settings > [your name] > Sign-In & Security** and enabl *This key is revoked, don't worry* -> **Important:** Treat this app-specific password as you would your primary password. Never share it or expose it publicly. The password sits locally on your device and is never shared with us. +> [!CAUTION] +> Treat this app-specific password as you would your primary password. Never share it or expose it publicly. The password sits locally on your device and is never shared with us. ![Matcha Add Account view](../assets/setup-guides/icloud/matcha.png) diff --git a/docs/docusaurus.config.ts b/docs/docusaurus.config.ts index 008141c8f4779bc4141ff4b2d1b0bd8683d47ef7..0ca8e3d42778f15a9cb62ae049d4236266522058 100644 --- a/docs/docusaurus.config.ts +++ b/docs/docusaurus.config.ts @@ -1,6 +1,7 @@ import { themes as prismThemes } from "prism-react-renderer"; import type { Config } from "@docusaurus/types"; import type * as Preset from "@docusaurus/preset-classic"; +import remarkGithubAdmonitionsToDirectives from "remark-github-admonitions-to-directives"; const config: Config = { title: "Matcha", @@ -29,6 +30,7 @@ const config: Config = { sidebarPath: "./sidebars.ts", routeBasePath: "/", editUrl: "https://github.com/floatpane/matcha/tree/master/docs/", + beforeDefaultRemarkPlugins: [remarkGithubAdmonitionsToDirectives], }, blog: false, theme: { diff --git a/docs/package-lock.json b/docs/package-lock.json index d55d92a8b409c76c3f4ca815d1695fb6474b4045..1a5fdefd012a5c827346eba2ec71df2584b50145 100644 --- a/docs/package-lock.json +++ b/docs/package-lock.json @@ -14,7 +14,8 @@ "clsx": "^2.0.0", "prism-react-renderer": "^2.3.0", "react": "^19.0.0", - "react-dom": "^19.0.0" + "react-dom": "^19.0.0", + "remark-github-admonitions-to-directives": "^2.1.0" }, "devDependencies": { "@docusaurus/module-type-aliases": "3.10.1", @@ -15763,6 +15764,21 @@ "url": "https://opencollective.com/unified" } }, + "node_modules/remark-github-admonitions-to-directives": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/remark-github-admonitions-to-directives/-/remark-github-admonitions-to-directives-2.1.0.tgz", + "integrity": "sha512-bI3E4Oj1pKY3ym2IQrrVCdORgEu0+mSrWgpCYFNy8QvytfnLs/nAacVPjkWU/JzDMUiQio2k4nTFP7bsIr9TSA==", + "license": "MIT", + "dependencies": { + "@types/mdast": "^4.0.0", + "mdast-util-directive": "^3.0.0", + "unified": "^11.0.0", + "unist-util-visit": "^5.0.0" + }, + "engines": { + "pnpm": ">=9.0.0" + } + }, "node_modules/remark-mdx": { "version": "3.1.1", "resolved": "https://registry.npmjs.org/remark-mdx/-/remark-mdx-3.1.1.tgz", diff --git a/docs/package.json b/docs/package.json index 7db428bec098a7545c88590251d635ad6e416dfa..babdefd38e65220c1d19fb8ca8ebff011c6e1f4f 100644 --- a/docs/package.json +++ b/docs/package.json @@ -21,7 +21,8 @@ "clsx": "^2.0.0", "prism-react-renderer": "^2.3.0", "react": "^19.0.0", - "react-dom": "^19.0.0" + "react-dom": "^19.0.0", + "remark-github-admonitions-to-directives": "^2.1.0" }, "devDependencies": { "@docusaurus/module-type-aliases": "3.10.1", diff --git a/docs/src/css/custom.css b/docs/src/css/custom.css index a3accfda364349fe14a7d00b0960137b42d74e64..30b8837bda434746b6975bc64cebcb3c90b28070 100644 --- a/docs/src/css/custom.css +++ b/docs/src/css/custom.css @@ -8,9 +8,14 @@ --ifm-color-primary-lightest: #dcfce7; --ifm-code-font-size: 95%; --docusaurus-highlighted-code-line-bg: rgba(0, 0, 0, 0.1); + + --gh-note: #0969da; + --gh-tip: #1a7f37; + --gh-important: #8250df; + --gh-warning: #9a6700; + --gh-caution: #cf222e; } -/* For dark mode */ [data-theme="dark"] { --ifm-color-primary: #4ade80; --ifm-color-primary-dark: #22c55e; @@ -20,4 +25,72 @@ --ifm-color-primary-lighter: #bbf7d0; --ifm-color-primary-lightest: #dcfce7; --docusaurus-highlighted-code-line-bg: rgba(0, 0, 0, 0.3); + + --gh-note: #1f6feb; + --gh-tip: #3fb950; + --gh-important: #a371f7; + --gh-warning: #d29922; + --gh-caution: #f85149; +} + +/* GitHub-style alerts */ +.alert { + --ifm-alert-background-color: transparent; + --ifm-alert-shadow: none; + border-width: 0 0 0 4px; + border-radius: 2px; +} + +[class*='admonitionHeading'] { + text-transform: capitalize; +} + +.alert--secondary { + --ifm-alert-border-color: var(--gh-note); + --ifm-alert-foreground-color: var(--ifm-font-color-base); +} +.alert--secondary [class*='admonitionHeading'], +.alert--secondary [class*='admonitionIcon'] svg { + color: var(--gh-note); + fill: var(--gh-note); +} + +.alert--success { + --ifm-alert-border-color: var(--gh-tip); + --ifm-alert-foreground-color: var(--ifm-font-color-base); +} +.alert--success [class*='admonitionHeading'], +.alert--success [class*='admonitionIcon'] svg { + color: var(--gh-tip); + fill: var(--gh-tip); +} + +.alert--info { + --ifm-alert-border-color: var(--gh-important); + --ifm-alert-foreground-color: var(--ifm-font-color-base); +} +.alert--info [class*='admonitionHeading'], +.alert--info [class*='admonitionIcon'] svg { + color: var(--gh-important); + fill: var(--gh-important); +} + +.alert--warning { + --ifm-alert-border-color: var(--gh-warning); + --ifm-alert-foreground-color: var(--ifm-font-color-base); +} +.alert--warning [class*='admonitionHeading'], +.alert--warning [class*='admonitionIcon'] svg { + color: var(--gh-warning); + fill: var(--gh-warning); +} + +.alert--danger { + --ifm-alert-border-color: var(--gh-caution); + --ifm-alert-foreground-color: var(--ifm-font-color-base); +} +.alert--danger [class*='admonitionHeading'], +.alert--danger [class*='admonitionIcon'] svg { + color: var(--gh-caution); + fill: var(--gh-caution); }