From 2c7299145ef56e2dd1ca59e469a1486971f6140c Mon Sep 17 00:00:00 2001 From: Mark Pitman Date: Tue, 13 Oct 2026 21:40:35 -0700 Subject: [PATCH] Fill the man page version at build time and refresh docs The man page header had a hardcoded Version 1.4.0. Use an @VERSION@ placeholder that just manpage replaces, defaulting to the latest git tag. goreleaser passes its own version to the hook, so release builds get the release version. The generated mdview.1 stays untracked. Add the missing -o and -b options to the SYNOPSIS, make the option spelling consistent, and describe flag placement and temp file cleanup. In CLAUDE.md, drop the mise.toml reference (the file is not tracked), document the placeholder rule, and record how to find and update the vendored mermaid.min.js version. Closes #71 --- .goreleaser.yaml | 2 +- CLAUDE.md | 11 +++++++++-- justfile | 5 +++-- mdview.1.md | 18 ++++++++++++------ 4 files changed, 25 insertions(+), 11 deletions(-) diff --git a/.goreleaser.yaml b/.goreleaser.yaml index af29cfe..c8376f1 100644 --- a/.goreleaser.yaml +++ b/.goreleaser.yaml @@ -2,7 +2,7 @@ version: 2 before: hooks: - - just manpage + - just manpage {{ .Version }} builds: - id: mdview diff --git a/CLAUDE.md b/CLAUDE.md index da5e9ac..1c10d43 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -10,7 +10,7 @@ default browser. It's essentially one file, `main.go`, plus a handful of embedde ## Build & run -Requires Go (see `go.mod`/`mise.toml` for version) and, for packaging, `just`, `pandoc`, and +Requires Go (see `go.mod` for the version) and, for packaging, `just`, `pandoc`, and [`goreleaser`](https://goreleaser.com/). - Quick local build: `go build` (produces `./mdview`) @@ -23,7 +23,7 @@ Requires Go (see `go.mod`/`mise.toml` for version) and, for packaging, `just`, ` - `just check` — validates `.goreleaser.yaml` - `just snap` — build snap package via `snapcraft` (kept separate; goreleaser doesn't build snaps) - `just clean` — remove build artifacts (`dist/`, `mdview.1`, `*.snap`) - - `just manpage` regenerates `mdview.1` from `mdview.1.md` via pandoc; goreleaser runs this automatically as a `before.hooks` step. + - `just manpage [version]` regenerates `mdview.1` from `mdview.1.md` via pandoc, replacing the `@VERSION@` placeholder in the man page header with `version` (default: `git describe --tags --always`). goreleaser runs this automatically as a `before.hooks` step and passes `{{ .Version }}`. Never write a literal app version in a source or packaging file; use a placeholder that the build replaces. - Versioning is read directly from git tags by goreleaser (embedded via `-ldflags -X main.appVersion={{.Version}}`) — there's no `VERSION` env var to pass anymore. - Run tests with `go test ./...`. There is no lint target configured; `go vet ./...` and `gofmt` are reasonable sanity checks before committing. @@ -47,6 +47,13 @@ Everything happens in `main()` in `main.go`, in a straight-line pipeline: Output location resolution order: `MDVIEW_DIR` env var → (if running as a Snap, per `SNAP_USER_COMMON` env var) `~/mdview-temp` → OS default temp dir. `MDVIEW_DIR` and `~/mdview-temp` are created with `MkdirAll`. Before writing a temp file, `removeStaleTempFiles` deletes generated `mdview<32 hex>.html` files older than 24 hours from that directory (the browser reads the new file after mdview exits, so mdview cannot delete it right away). This exists because Snap-sandboxed browsers (e.g. Snap Firefox) can't read from `/tmp`, only from the user's home directory — `check()` writes errors to stderr, names the failing path, and prints a Snap-specific hint for permission and not-found errors for this reason. +### Vendored `mermaid.min.js` + +`mermaid.min.js` is a vendored copy of the Mermaid library, embedded with `//go:embed`. Print its +version with `grep -o 'version:"[0-9.]*"' mermaid.min.js`. To update it, download +`https://cdn.jsdelivr.net/npm/mermaid@/dist/mermaid.min.js` over the file, render a markdown +file with a mermaid block (light and dark mode), and commit the new file. + ### Packaging `.goreleaser.yaml` drives cross-platform binary builds, archives (`.tar.gz`/`.zip`), and `.deb`/ diff --git a/justfile b/justfile index 506033f..8ea0f18 100644 --- a/justfile +++ b/justfile @@ -24,5 +24,6 @@ clean: # snapcraft clean mdview -s pull -manpage: - pandoc --standalone --to man mdview.1.md -o mdview.1 \ No newline at end of file +# The version defaults to the latest git tag; goreleaser passes its own. +manpage version=`git describe --tags --always`: + sed 's|@VERSION@|{{version}}|g' mdview.1.md | pandoc --standalone --to man -o mdview.1 diff --git a/mdview.1.md b/mdview.1.md index 67d3f43..93fc816 100644 --- a/mdview.1.md +++ b/mdview.1.md @@ -1,4 +1,4 @@ -% MDVIEW(1) Version 1.4.0 | "Markdown View" Documentation +% MDVIEW(1) Version @VERSION@ | "Markdown View" Documentation # NAME @@ -6,21 +6,27 @@ # SYNOPSIS -**mdview** _filename_ -**mdview** **-** -**mdview** \[**-h**|**--help**|**-v**|**--version**] +**mdview** \[**-b**] \[**-o** _output_] _filename_ +**mdview** \[**-b**] \[**-o** _output_] **-** +**mdview** **-h**|**-help**|**-v**|**-version** # DESCRIPTION Formats a markdown file as HTML, writes it to a temporary file and then launches that file in the default web browser. By default, it will use the operating system's default temporary directory unless the -environment variable MDVIEW_DIR is set. +environment variable MDVIEW_DIR is set. Generated temporary files that +are more than 24 hours old are removed from that directory the next +time mdview writes one. If _filename_ is a single dash (**-**), the markdown is read from standard input. Relative image paths are then resolved against the current working directory. +Options can be given before or after _filename_, with one or two +leading dashes (for example **-help** or **--help**). Use **--** to end +the options. + ## Options **-b**, **-bare** @@ -31,7 +37,7 @@ Bare HTML with no style applied. Prints mdview help message. -**-o** _filename_ +**-o** _output_ Output filename. (Optional)