Add visible Linux setup launcher (#13)

Author: maphew

README.html

@@ -83,7 +83,7 @@ <h2>🚀 Features</h2>
 <li>🔒 Raw Markdown HTML is sanitized by default; use <code>--unsafe-html</code> to preserve it for trusted input</li>
 <li>👀 <code>--watch</code> flag enables auto-rerender on file change (with debouncing)</li>
 <li>🌐 <code>--open</code> flag renders to a temp dir and launches the system default browser</li>
-<li>🧑‍🚀 <code>--setup</code> / no-arg interactive first-run guide, plus a Windows/Linux <code>mdo-setup</code> launcher that opens it for file-manager users</li>
+<li>🧑‍🚀 Explicit <code>--setup</code> first-run guide, plus a Windows/Linux <code>mdo-setup</code> launcher that opens it for file-manager users</li>
 <li>🧭 Built-in <code>--install-file-manager</code> / <code>--uninstall-file-manager</code> integration (no separate install scripts needed)</li>
 <li>⚡ Fast and self-contained — no required runtime assets; <code>mdo.exe</code> remains the core CLI</li>
 <li>🧩 Built on <code>pulldown-cmark</code>, <code>clap</code>, and <code>notify</code></li>
@@ -194,7 +194,7 @@ <h3>Examples</h3>
 used by normal mdo output:</p>
 <pre><code class="language-bash">python scripts/build-docs.py
 </code></pre>
-<p>The homepage source is <code>docs/index.md</code>; it uses only Markdown and the <code>--css  docs/assets/site.css</code> override so the docs-only presentation is layered after
+<p>The homepage source is <code>docs/index.md</code>; it uses only Markdown and the <code>--css docs/assets/site.css</code> override so the docs-only presentation is layered after
 mdo's embedded simple.css and typography defaults. The sample preview source is
 <code>docs/assets/sample.md</code>; <code>scripts/build-docs.py</code> renders it with
 <code>docs/assets/sample.css</code> to demonstrate per-page CSS overrides. The GitHub Pages
@@ -243,10 +243,11 @@ <h3>First-run setup</h3>
 <p>On Windows, double-click <code>mdo-setup.exe</code> to open that same guided setup in a
 fresh Windows Terminal (<code>wt</code>) window, falling back to a plain new console if
 <code>wt</code> is unavailable — the no-terminal entry point for Explorer users. On
-Linux, run <code>mdo-setup</code> to get setup in your <code>$TERMINAL</code> or a known terminal emulator
-(<code>gnome-terminal</code>, <code>konsole</code>, <code>xterm</code>, and others); it is also what <code>mdo-open</code>
-runs when launched with no file. Double-clicking the bare <code>mdo-setup</code> binary from
-a file manager is not reliable on Linux, so prefer <code>mdo --setup</code> from a shell.
+Linux, launch <strong>mdo Setup</strong> from your application menu, or run <code>mdo-setup</code> to
+open guided setup in your <code>$TERMINAL</code> or a known terminal emulator
+(<code>gnome-terminal</code>, <code>konsole</code>, <code>xterm</code>, and others). It is also what <code>mdo-open</code>
+runs when launched with no file. Running <code>mdo-setup</code> repairs its per-user
+application-menu entry if needed.
 This preserves <code>mdo</code> as the normal CLI. On Windows, launching <code>mdo-open.exe</code>
 directly with no file opens the same guided setup in a fresh Windows Terminal
 (<code>wt</code>) window using the <strong>One Half Light</strong> color scheme, centered on the active
@@ -274,9 +275,14 @@ <h2>Linux file manager integration</h2>
 show an action-oriented entry instead of a tool-name-only entry. Rerunning the
 installer also removes older Nautilus Scripts entries named <strong>Preview with
 mdo</strong> or <strong>Render with mdo</strong>.</p>
+<p>The hosted Linux installer also writes the separate, visible
+<code>~/.local/share/applications/mdo-setup.desktop</code> launcher. It has no MIME types
+and remains installed if you run <code>mdo --uninstall-file-manager</code>; that command
+only removes the hidden <strong>Open as HTML</strong> file-handler integration.</p>
 <p>Linux release archives also include <code>mdo-setup</code>, which opens the same first-run
-setup in a terminal window. It launches your <code>$TERMINAL</code> or a known terminal
-emulator (<code>gnome-terminal</code>, <code>konsole</code>, <code>xterm</code>, and others); if none is found it
+setup in a terminal window and registers itself as <strong>mdo Setup</strong> in Linux
+application menus. It launches your <code>$TERMINAL</code> or a known terminal emulator
+(<code>gnome-terminal</code>, <code>konsole</code>, <code>xterm</code>, and others); if none is found it
 shows a <code>zenity</code>/<code>kdialog</code>/<code>yad</code> notice pointing you to <code>mdo --setup</code>. If you
 launch <code>mdo-open</code> directly with no file, it opens <code>mdo-setup</code> when the setup
 helper is present.</p>
@@ -413,6 +419,6 @@ <h2>📄 License</h2>
 <p>at your option, matching the licensing of the upstream project.</p>
 
 </main>
-<footer class="mdo-generated">Generated by <a href="https://maphew.github.io/mdo/">mdo</a> 0.4.0 in 0.006s on <time datetime="2026-06-18">2026-06-18</time>.</footer>
+<footer class="mdo-generated">Generated by <a href="https://maphew.github.io/mdo/">mdo</a> 0.4.0 in 0.001s on <time datetime="2026-07-10">2026-07-10</time>.</footer>
 </body>
 </html>

README.md

@@ -259,10 +259,11 @@ you can immediately verify the browser-opening flow.
 On Windows, double-click `mdo-setup.exe` to open that same guided setup in a
 fresh Windows Terminal (`wt`) window, falling back to a plain new console if
 `wt` is unavailable — the no-terminal entry point for Explorer users. On
-Linux, run `mdo-setup` to open guided setup in your `$TERMINAL` or a known terminal emulator
-(`gnome-terminal`, `konsole`, `xterm`, and others); it is also what `mdo-open`
-runs when launched with no file. Double-clicking the bare `mdo-setup` binary from
-a file manager is not reliable on Linux, so prefer `mdo --setup` from a shell.
+Linux, launch **mdo Setup** from your application menu, or run `mdo-setup` to
+open guided setup in your `$TERMINAL` or a known terminal emulator
+(`gnome-terminal`, `konsole`, `xterm`, and others). It is also what `mdo-open`
+runs when launched with no file. Running `mdo-setup` repairs its per-user
+application-menu entry if needed.
 This preserves `mdo` as the normal CLI. On Windows, launching `mdo-open.exe`
 directly with no file opens the same guided setup in a fresh Windows Terminal
 (`wt`) window using the **One Half Light** color scheme, centered on the active
@@ -297,9 +298,15 @@ show an action-oriented entry instead of a tool-name-only entry. Rerunning the
 installer also removes older Nautilus Scripts entries named **Preview with
 mdo** or **Render with mdo**.
 
+The hosted Linux installer also writes the separate, visible
+`~/.local/share/applications/mdo-setup.desktop` launcher. It has no MIME types
+and remains installed if you run `mdo --uninstall-file-manager`; that command
+only removes the hidden **Open as HTML** file-handler integration.
+
 Linux release archives also include `mdo-setup`, which opens the same first-run
-setup in a terminal window. It launches your `$TERMINAL` or a known terminal
-emulator (`gnome-terminal`, `konsole`, `xterm`, and others); if none is found it
+setup in a terminal window and registers itself as **mdo Setup** in Linux
+application menus. It launches your `$TERMINAL` or a known terminal emulator
+(`gnome-terminal`, `konsole`, `xterm`, and others); if none is found it
 shows a `zenity`/`kdialog`/`yad` notice pointing you to `mdo --setup`. If you
 launch `mdo-open` directly with no file, it opens `mdo-setup` when the setup
 helper is present.

docs/assets/sample.html

@@ -117,6 +117,6 @@ <h2>Commands</h2>
 <p>Use <code>--bare</code> when another template owns the document shell.</p>
 
 </main>
-<footer class="mdo-generated">Generated by <a href="https://maphew.github.io/mdo/">mdo</a> 0.4.0 in 0.001s on <time datetime="2026-06-18">2026-06-18</time>.</footer>
+<footer class="mdo-generated">Generated by <a href="https://maphew.github.io/mdo/">mdo</a> 0.4.0 in 0.001s on <time datetime="2026-07-10">2026-07-10</time>.</footer>
 </body>
 </html>

docs/index.html

@@ -1562,7 +1562,7 @@ <h3>Explore first</h3>
 <p>Setup explains the render-and-open workflow, the normal convert-once command, and the reversible integration commands.</p>
 <h3>Opt in when ready</h3>
 <p>Running <code>mdo</code> with no arguments prints a short <strong>Open Markdown as HTML</strong> landing page and exits successfully; use <code>mdo --help</code> for the full CLI reference. Run <code>mdo --setup</code> when you want guided setup. On Windows and Linux it can offer to install <strong>Open as HTML</strong> for the current user only. The default answer is <strong>Yes</strong>, but mdo still does not change the default Markdown app. Choose <strong>No</strong> to skip or run setup again later.</p>
-<p>After you press Enter to finish setup, mdo opens a short welcome sample so you can immediately verify the browser-opening flow. On Windows, double-click <code>mdo-setup.exe</code> to open that same guided setup in a fresh Windows Terminal (<code>wt</code>) window, falling back to a plain new console if <code>wt</code> is unavailable. On Linux, run <code>mdo-setup</code> to open guided setup in your <code>$TERMINAL</code> or a known terminal emulator (<code>gnome-terminal</code>, <code>konsole</code>, <code>xterm</code>, and others); it is also what <code>mdo-open</code> runs when launched with no file. Double-clicking the bare binary from a file manager is not reliable on Linux, so prefer <code>mdo --setup</code> from a shell.</p>
+<p>After you press Enter to finish setup, mdo opens a short welcome sample so you can immediately verify the browser-opening flow. On Windows, double-click <code>mdo-setup.exe</code> to open that same guided setup in a fresh Windows Terminal (<code>wt</code>) window, falling back to a plain new console if <code>wt</code> is unavailable. On Linux, launch <strong>mdo Setup</strong> from your application menu or run <code>mdo-setup</code> to open guided setup in your <code>$TERMINAL</code> or a known terminal emulator (<code>gnome-terminal</code>, <code>konsole</code>, <code>xterm</code>, and others); it is also what <code>mdo-open</code> runs when launched with no file. Running it repairs its per-user application-menu entry if needed.</p>
 <p>On Windows, launching <code>mdo-open.exe</code> directly with no file opens the same guided setup in a fresh Windows Terminal (<code>wt</code>) window using the <strong>One Half Light</strong> color scheme, centered on the active display; if <code>wt</code> is unavailable, it falls back to a plain new console.</p>
 <h2>Usage</h2>
 <p>By default, <code>mdo</code> writes a styled HTML file beside the source Markdown file. Use <code>--open</code> to render into a stable temp path and launch the default browser.</p>
@@ -1616,7 +1616,7 @@ <h3>Windows Explorer</h3>
 <li><strong>Open with</strong> offers <strong>Open as HTML</strong>.</li>
 <li>If <strong>Open as HTML</strong> is made the default handler, double-click opens the browser.</li>
 <li>If <code>mdo-open.exe</code> is next to <code>mdo.exe</code>, it is used for flash-free Explorer launches; otherwise the single <code>mdo.exe</code> binary still works.</li>
-<li><code>mdo-setup.exe</code> and no-file <code>mdo-open.exe</code> open the guided setup in a fresh <code>wt</code> window with the <strong>One Half Light</strong> color scheme and center it on the active display, falling back to a plain new console when <code>wt</code> cannot be started.</li>
+<li><code>mdo-setup.exe</code> and no-file <code>mdo-open.exe</code> open guided setup in a fresh <code>wt</code> window with the <strong>One Half Light</strong> color scheme and center it on the active display, falling back to a plain new console when <code>wt</code> cannot be started.</li>
 <li>Windows Open With should show the friendly name <strong>Open as HTML</strong> with the mdo icon instead of exposing the wrapper file name.</li>
 </ul>
 <h3>Linux File Managers</h3>
@@ -1626,6 +1626,7 @@ <h3>Linux File Managers</h3>
 mdo --uninstall-file-manager
 </code></pre>
 <ul>
+<li>The hosted installer registers a visible <strong>mdo Setup</strong> application-menu entry at <code>~/.local/share/applications/mdo-setup.desktop</code>; running <code>mdo-setup</code> repairs it for Cargo or Homebrew installs. It is separate from the hidden <code>mdo.desktop</code> file handler and remains after <code>mdo --uninstall-file-manager</code>.</li>
 <li><code>mdo-setup</code> opens the same first-run setup in a terminal window (your <code>$TERMINAL</code> or a known emulator such as <code>gnome-terminal</code>, <code>konsole</code>, or <code>xterm</code>); if none is found it shows a <code>zenity</code>/<code>kdialog</code>/<code>yad</code> notice pointing to <code>mdo --setup</code>.</li>
 <li>Most XDG file managers show <strong>Open With -&gt; Open as HTML</strong> for Markdown files.</li>
 <li>GNOME Files/Nautilus uses the same Open With entry; no duplicate Scripts item is installed.</li>
@@ -1664,6 +1665,6 @@ <h2>Project Links</h2>
 <p>mdo is dual-licensed under MIT or Apache-2.0 and forked with gratitude from Hafiz Ali Raza's original Markdown-to-HTML CLI.</p>
 
 </main>
-<footer class="mdo-generated">Generated by <a href="https://maphew.github.io/mdo/">mdo</a> 0.4.0 in 0.004s on <time datetime="2026-06-18">2026-06-18</time>.</footer>
+<footer class="mdo-generated">Generated by <a href="https://maphew.github.io/mdo/">mdo</a> 0.4.0 in 0.001s on <time datetime="2026-07-10">2026-07-10</time>.</footer>
 </body>
 </html>

docs/index.md

@@ -107,7 +107,7 @@ Setup explains the render-and-open workflow, the normal convert-once command, an
 
 Running `mdo` with no arguments prints a short **Open Markdown as HTML** landing page and exits successfully; use `mdo --help` for the full CLI reference. Run `mdo --setup` when you want guided setup. On Windows and Linux it can offer to install **Open as HTML** for the current user only. The default answer is **Yes**, but mdo still does not change the default Markdown app. Choose **No** to skip or run setup again later.
 
-After you press Enter to finish setup, mdo opens a short welcome sample so you can immediately verify the browser-opening flow. On Windows, double-click `mdo-setup.exe` to open that same guided setup in a fresh Windows Terminal (`wt`) window, falling back to a plain new console if `wt` is unavailable. On Linux, run `mdo-setup` to open guided setup in your `$TERMINAL` or a known terminal emulator (`gnome-terminal`, `konsole`, `xterm`, and others); it is also what `mdo-open` runs when launched with no file. Double-clicking the bare binary from a file manager is not reliable on Linux, so prefer `mdo --setup` from a shell.
+After you press Enter to finish setup, mdo opens a short welcome sample so you can immediately verify the browser-opening flow. On Windows, double-click `mdo-setup.exe` to open that same guided setup in a fresh Windows Terminal (`wt`) window, falling back to a plain new console if `wt` is unavailable. On Linux, launch **mdo Setup** from your application menu or run `mdo-setup` to open guided setup in your `$TERMINAL` or a known terminal emulator (`gnome-terminal`, `konsole`, `xterm`, and others); it is also what `mdo-open` runs when launched with no file. Running it repairs its per-user application-menu entry if needed.
 
 On Windows, launching `mdo-open.exe` directly with no file opens the same guided setup in a fresh Windows Terminal (`wt`) window using the **One Half Light** color scheme, centered on the active display; if `wt` is unavailable, it falls back to a plain new console.
 
@@ -192,6 +192,7 @@ mdo --install-file-manager --set-default
 mdo --uninstall-file-manager
 ```
 
+- The hosted installer registers a visible **mdo Setup** application-menu entry at `~/.local/share/applications/mdo-setup.desktop`; running `mdo-setup` repairs it for Cargo or Homebrew installs. It is separate from the hidden `mdo.desktop` file handler and remains after `mdo --uninstall-file-manager`.
 - `mdo-setup` opens the same first-run setup in a terminal window (your `$TERMINAL` or a known emulator such as `gnome-terminal`, `konsole`, or `xterm`); if none is found it shows a `zenity`/`kdialog`/`yad` notice pointing to `mdo --setup`.
 - Most XDG file managers show **Open With -> Open as HTML** for Markdown files.
 - GNOME Files/Nautilus uses the same Open With entry; no duplicate Scripts item is installed.

docs/install.sh

@@ -88,6 +88,10 @@ done
 echo "mdo installed to ${install_dir}"
 "${install_dir}/mdo" --version
 
+if [ "$os" = "Linux" ]; then
+  "${install_dir}/mdo-setup" --register-launcher-only
+fi
+
 case ":${PATH}:" in
   *":${install_dir}:"*) ;;
   *)

src/bin/mdo-setup.rs

@@ -28,7 +28,18 @@ fn main() -> ExitCode {
 
 #[cfg(target_os = "linux")]
 fn main() -> ExitCode {
-    match linux_setup::run() {
+    let register_only = std::env::args_os()
+        .nth(1)
+        .is_some_and(|arg| arg == "--register-launcher-only");
+    let result = if register_only {
+        linux_setup::register_launcher().map(|path| {
+            println!("Installed application launcher: {}", path.display());
+        })
+    } else {
+        linux_setup::run()
+    };
+
+    match result {
         Ok(()) => ExitCode::SUCCESS,
         Err(e) => {
             linux_setup::error_dialog(
@@ -81,6 +92,7 @@ mod linux_setup {
     ];
 
     pub fn run() -> io::Result<()> {
+        continue_after_launcher_registration(register_launcher());
         let mdo = sibling_binary("mdo")?;
         if !mdo.exists() {
             return Err(io::Error::new(
@@ -116,6 +128,23 @@ mod linux_setup {
         Ok(())
     }
 
+    pub fn register_launcher() -> io::Result<PathBuf> {
+        let setup_exe = std::env::current_exe()?;
+        mdo_cli::file_manager::install_linux_setup_launcher_for_exe(&setup_exe)
+    }
+
+    fn continue_after_launcher_registration(result: io::Result<PathBuf>) -> bool {
+        match result {
+            Ok(_) => true,
+            Err(error) => {
+                eprintln!(
+                    "mdo setup warning: could not register the application-menu launcher: {error}"
+                );
+                false
+            }
+        }
+    }
+
     fn spawn_setup_in_terminal(mdo: &Path) -> bool {
         for (program, lead) in preferred_terminals() {
             if !command_on_path(program) {
@@ -277,6 +306,23 @@ mod linux_setup {
                 );
             }
         }
+
+        #[test]
+        fn normal_onboarding_continues_after_launcher_registration_failure() {
+            let result = Err(io::Error::new(
+                io::ErrorKind::PermissionDenied,
+                "applications directory is read-only",
+            ));
+
+            assert!(!continue_after_launcher_registration(result));
+        }
+
+        #[test]
+        fn normal_onboarding_accepts_successful_launcher_registration() {
+            assert!(continue_after_launcher_registration(Ok(PathBuf::from(
+                "/tmp/applications/mdo-setup.desktop"
+            ))));
+        }
     }
 }