8000 feat: follow relative Markdown links and live-reload relative images by jkellz-dev · Pull Request #12 · jkellz-dev/mdpreviewer · GitHub
[go: up one dir, main page]

Skip to content
{"props":{"contextRegion":{"crumbs":[{"crumb_type":"user","label":"jkellz-dev","is_root":false,"href":"/jkellz-dev"},{"crumb_type":"repository","label":"mdpreviewer","is_root":false,"href":"/jkellz-dev/mdpreviewer"}],"localNavigation":[{"id":"code","icon":"code","label":"Code","href":"/jkellz-dev/mdpreviewer","selectedLinks":["repo_source","repo_downloads","repo_commits","repo_releases","repo_tags","repo_branches","repo_packages","repo_deployments","repo_attestations"],"popoverTarget":false,"commandId":"repositories:go-to-code","reactNav":{"appTarget":"code-view","anchor":"code-view-repo-link"},"turboNav":{"frame":"repo-content-turbo-frame"}},{"id":"issues","icon":"issue-opened","label":"Issues","href":"/jkellz-dev/mdpreviewer/issues","selectedLinks":["repo_issues","repo_labels","repo_milestones"],"count":0,"popoverTarget":false,"commandId":"repositories:go-to-issues","reactNav":{"appTarget":"repo","anchor":null},"turboNav":{"frame":"repo-content-turbo-frame"}},{"id":"pull-requests","icon":"git-pull-request-locked","label":"Pull requests","tooltip":"Only collaborators can create PRs","href":"/jkellz-dev/mdpreviewer/pulls","selectedLinks":["repo_pulls","checks"],"count":1,"popoverTarget":false,"commandId":"repositories:go-to-pull-requests","reactNav":{"appTarget":null,"anchor":null},"turboNav":{"frame":"repo-content-turbo-frame"}},{"id":"actions","icon":"play","label":"Actions","href":"/jkellz-dev/mdpreviewer/actions","selectedLinks":["repo_actions"],"popoverTarget":false,"commandId":"repositories:go-to-actions","reactNav":{"appTarget":"repo","anchor":null},"turboNav":{"frame":"repo-content-turbo-frame"}},{"id":"projects","icon":"table","label":"Projects","href":"/jkellz-dev/mdpreviewer/projects","selectedLinks":["repo_projects","new_repo_project","repo_project"],"popoverTarget":false,"commandId":"repositories:go-to-projects","reactNav":{"appTarget":"repo","anchor":null},"turboNav":{"frame":"repo-content-turbo-frame"}},{"id":"security-and-quality","icon":"shield","label":"Security and quality","href":"/jkellz-dev/mdpreviewer/security","selectedLinks":["security","overview","alerts","policy","token_scanning","code_scanning"],"count":0,"popoverTarget":false,"commandId":"repositories:go-to-security","reactNav":{"appTarget":null,"anchor":null},"turboNav":{"frame":"repo-content-turbo-frame"}},{"id":"insights","icon":"graph","label":"Insights","href":"/jkellz-dev/mdpreviewer/pulse","selectedLinks":["repo_graphs","repo_contributors","dependency_graph","dependabot_updates","pulse","people","community"],"popoverTarget":false,"commandId":"repositories:go-to-insights","reactNav":{"appTarget":null,"anchor":null},"turboNav":{"frame":"repo-content-turbo-frame"}}],"localNavigationUpdateChannel":null,"selectedLink":"repo_pulls"},"owner":null,"headerLogo":{"href":"/","aria-label":"Homepage "},"notifications":{"indicatorMode":"disabled","websocketChannel":null,"fetchIndicatorSrc":"/notifications/indicator","fetchIndicatorEnabled":false},"issues":{"href":"/issues"},"pulls":{"href":"/pulls"},"contributedRepos":{"href":"/repos"},"copilot":{"show":false,"showAgentsButton":false,"showRelaunchAnnouncement":false,"licenseGrantNudge":null,"copilotChatUrl":null,"copilotApiUrl":"https://api.githubcopilot.com"},"search":{"show":true,"showCommandPalette":false,"isSearchPage":false,"isJumpToSearch":false,"searchContext":{"scope":"repo:jkellz-dev/mdpreviewer","current_repo_name":"mdpreviewer","current_repo_nwo":"jkellz-dev/mdpreviewer","user_id":"jkellz-dev"}},"commandPalette":null,"enterpriseBar":{"show":false},"globalTransactionalMessage":[],"payloadsUrl":"/_global-navigation/payloads.json?can_toggle_site_admin_and_employee_status=0\u0026is_admin_mode_on=0\u0026is_ui_opted_out=0\u0026show_ui_opt_out=0\u0026v=8","contextRegionUrl":null}}

feat: follow relative Markdown links and live-reload relative images - #12

Merged
jkellz-dev merged 2 commits into
mainfrom
jkellz/cleanup
Sep 26, 2026
Merged

jkellz-dev merged 2 commits into
mainfrom
jkellz/cleanup

Conversation

@jkellz-dev
Copy link
Copy Markdown
Owner

Summary

The preview page always lives at /, so a document's relative references were resolved against the wrong
directory: clicking [setup](docs/setup.md) opened a bare 404 page, ../ was lost before the server saw it,
and relative images did not load. The server now resolves them against the current document's directory.

Relative links and images

  • Links: clicking a relative link to a .md/.markdown file switches the preview to that file, starting at
    the top. The client posts the link to POST /open, which switches the document the same way a control-socket
    open does. Ctrl-, shift- and middle-clicks do the same: the server shows one document to every tab, so a new
    tab could not show a different file anyway.
  • Broken links: a link to a missing file, a non-Markdown file, or a server that has gone away shows a notice
    at the top of the window saying why.
  • Images: relative images load through GET /file?path=<link>. The client rewrites their src before the
    fragment is inserted, so the unresolved URL is never requested.
  • Image reload: replacing an image file on disk updates it in place. The server watches every image it has
    served for the current document and sends an images SSE event. The client bumps a version in the image URLs,
    so only the images are fetched again and the text does not flicker. The browser reuses an image it already
    holds for a URL even under no-cache, so a new URL is needed.

Security

  • POST /open requires an X-Mdpreviewer header. A browser will not send it cross-origin without a CORS
    preflight, which the server never grants, so another web page cannot switch the preview. Other methods get 405.
  • /file serves image extensions onon the canonical path, so a symlink or ..
    cannot reach other files. Responseicy: sandboxandnosniff`, so an SVG opened on
    its own runs no script.

Fixes from review

  • --restart fails if the old serve within 2 s, instead of handing thefile to the
    server it meant to replace.
  • --quit reports an unsafe socket directory instead of saying no server is running.
  • A control quit always removes thd by a test.
  • format_request matches every Request variant, so a future one cannot go out on the wire as
    quit.
  • The expand_tilde test no longer changes HOME while other tests run in parallel.
  • A single click on a code block or ick window before zooming, sodouble-clicking to
    select a word no longer opens the

CI

  • A new msrv job checks the build oninCargo.toml`.
  • The release workflow calls ci.yml as a reusable workflow before release-plz publishes, so a commit
    that fails
    CI is never released. As a result every push to main runs CI twice.
  • The call uses ./.github/workflows comment. The pinned actionlint doesnot accept GitHub's newer $/` form yet.

Testing

  • cargo test: 64 tests pass. New iing links (including refusals andCORS),
    serving images, image-change eventn the document switches, and quitremoving the
    socket.
  • mise run lint is clean, and cargo +1.88 check --locked --all-targets builds.
  • Checked by hand in a browser: plain link, and the broken-link notice.
    examples/basics.md now has a working and a broken relative link to try this.
  • Not yet checked by hand: zoom on a, and replacing an image the previewis showing.
  • The release gate only runs on a puecks do not exercise it.

Known limitations

  • An image that does not exist yet ifter the page loads shows up on thenext save of
    the Markdown file.
  • A relative link to a file that is neither Markdown nor an image still gives a 404.
  • "Open link in new tab" from the ri404. Page code cannot intercept it.

The page always lives at `/`, so the browser resolved a document's
relative references against the wrong directory: `[b](other.md)`
navigated the preview to a bare 404 page, and `../` was lost before the
server saw it. Resolve them on the server instead, against the current
document's directory.

- `POST /open` takes a link as written in the document and switches the
  preview to it, through the same `switch_to` a control-socket `open`
  uses. The client catches plain clicks on relative `.md`/`.markdown`
  links and posts them; the switch comes back as a `reload` and the new
  document starts at the top. A link that cannot be followed (missing
  file, not Markdown, server gone) shows a toast saying why. It requires an `X-Mdpreviewer` header,
  which a browser will not send cross-origin without a CORS preflight the
  server never grants, so another web page cannot switch the preview.
- `GET /file?path=<link>` serves relative images. The client rewrites
  each relative `img` source on the parsed fragment, before insertion, so
  the unresolved URL is never requested. Only image extensions are
  served, checked on the canonical path so a symlink or `..` cannot reach
  other files, and `Content-Security-Policy: sandbox` keeps an SVG
  opened on its own from running script on this origin.

`is_markdown` moves to `render.rs` so the server can share it with the
CLI.

The `basics.md` fixture gains a relative link to `mermaid.md` to try it
by hand.

fix(client): follow Markdown links on modified and middle clicks

Left to the browser, a ctrl-, shift- or middle-click on a relative
Markdown link opened it in a new tab resolved against `/`, which is a
404. The server shows one document to every tab, so a second tab could
not show a different file anyway: follow the link in place instead.
Middle clicks arrive as `auxclick`, so listen for that too.

feat: reload relative images when they are replaced on disk

Only the Markdown file was watched, so replacing an image the document
shows changed nothing until the text was saved, and not even then: a
page reuses an image it already holds for a URL, `no-cache` or not.

- The server records each image `/file` serves for the current document
  and watches it, one watch per directory through the new
  `watch::watch_files`. A change sends a new `images` SSE event. The set
  belongs to `Current`, so switching documents drops it.
- Image URLs carry `&v=<n>`. The client bumps `n` on `images` and
  re-points every relative image, so only the images refetch and the text
  does not flicker. An open zoom is re-cloned once they have decoded.
  Between replacements the URL is stable, so saving the text does not
  refetch every image.
- `--restart` fails if the old server has not released the socket after
  2 s, instead of handing the file to the server it meant to replace.
- `--quit` reports an unsafe socket directory instead of claiming no
  server is running. `--restart` still falls through to a standalone
  preview there.
- A control `quit` removes the socket even when the process is not going
  to exit, so an in-process test can check it. New test:
  `quit_removes_the_control_socket`.
- `format_request` matches every `Request` variant, so a new one cannot
  go out on the wire as `quit`.
- `expand_tilde` takes `HOME` through `expand_home`, so its test no
  longer mutates the environment of a multi-threaded test runner.
- Drop a stale doc comment and duplicate `#[cfg(unix)]` above `Stop`.
- A single click on a code block or table waits out the double-click
  window before zooming, so double-clicking to select a word does not open
  the overlay.
- CI checks the MSRV (1.88), and the release workflow runs CI first, so a
  commit that fails it is never published.
@jkellz-dev
jkellz-dev merged commit 847e7f2 into main Sep 26, 2026
4 checks passed
@jkellz-dev
jkellz-dev deleted the jkellz/cleanup branch September 26, 2026 05:46
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant

0