Preview markdown files formatted, with a raw toggle (#780)

* Preview markdown files formatted, with a raw toggle

Markdown files are typed text/markdown (libmagic reports them as text/plain, or
as a programming language when they hold code) and keep the text indexer, so
they stay deep-searchable.  Existing files switch type on their next refresh.

The file preview renders markdown with markdown-it into the page, so it follows
the theme tokens and the night media filter.  A Formatted/Raw toggle shows the
source instead, and the choice is remembered.  Relative links and images
resolve against the file's directory; URLs that climb out of /media/ are
dropped.  Raw HTML in a file is escaped rather than parsed, and the output is
also sanitized with DOMPurify.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Do not load images from other sites in the markdown preview

An image from another site (http:, https:, or protocol-relative //) loaded as
soon as the preview opened, telling that site who was reading the file and
when.  Such an image now becomes a link labeled with its alt text, so the
reader chooses whether to follow it.  Inside a link (a README badge) it becomes
the outer link's text, since links cannot nest.  Media and embedded data:
images still load.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
lrnselfreliance 2026-10-05 13:26:37 -06:00 • committed by Roland
parent 9739dc9e1b
commit 04779b8557
No known key found for this signature in database
GPG key ID: 1BA620CE6C9A4680
13 changed files with 828 additions and 10 deletions

View file

@ -1165,7 +1165,7 @@ export function mimetypeIconName(mimetype, lowerPath = '') {
return 'file code';
} else if (mimetype.startsWith('application/pdf')) {
return 'file pdf';
} else if (mimetype.startsWith('text/plain')) {
} else if (mimetype.startsWith('text/plain') || mimetype.startsWith('text/markdown')) {
return 'file text';
} else if (mimetype.startsWith('image/')) {
return 'image';

View file

@ -14,6 +14,7 @@ import {pathDirectory} from "./FileBrowser";
import {InlineErrorBoundary} from "./ErrorBoundary";
import {useLocation} from "react-router";
import {ThemeContext} from "../contexts/contexts";
import {isMarkdownFile, MarkdownPreview} from "./MarkdownPreview";
// Routes where file views should not be tracked
const EXCLUDED_TRACKING_ROUTES = [
@ -607,6 +608,9 @@ export function FilePreviewProvider({children}) {
if (mimetype.startsWith('text/') && size > MAXIMUM_TEXT_SIZE) {
// Large text files should be downloaded.
window.open(downloadURL);
} else if (isMarkdownFile(mimetype, lowerPath)) {
setModalContent(<Modal.Content><MarkdownPreview url={url}/></Modal.Content>, url, downloadURL, path,
taggable);
} else if (mimetype.startsWith('text/') || mimetype.startsWith('application/json')) {
setModalContent(getIframePreviewModal(previewFile), url, downloadURL, path, taggable);
} else if (mimetype.startsWith('video/')) {

View file

@ -101,6 +101,26 @@ describe('preview gate remounting (source contract)', () => {
});
});
describe('markdown preview routing (source contract)', () => {
/*
* Markdown is text/*, so the generic text branch would also accept it and show it raw in an
* iframe. The markdown branch has to be tested first for the formatted view to be reachable.
*/
const fs = require('fs');
const path = require('path');
const source = fs.readFileSync(path.join(__dirname, 'FilePreview.js'), 'utf8');
test('markdown is routed to MarkdownPreview before the generic text preview', () => {
const markdownBranch = source.indexOf('} else if (isMarkdownFile(mimetype, lowerPath)) {');
const textBranch = source.indexOf("} else if (mimetype.startsWith('text/') || mimetype.startsWith('application/json')) {");
expect(markdownBranch).toBeGreaterThan(-1);
expect(textBranch).toBeGreaterThan(-1);
expect(markdownBranch).toBeLessThan(textBranch);
expect(source.slice(markdownBranch, textBranch)).toContain('<MarkdownPreview url={url}/>');
});
});
describe('IframePreview color scheme', () => {
/*
* The previewed file is a bare document with no styles of its own, so it renders with the

View file

@ -0,0 +1,170 @@
import React from "react";
import MarkdownIt from "markdown-it";
import DOMPurify from "dompurify";
import {useLocalStorage} from "./Common";
import {Button, ButtonGroup, Loading, Message} from "./ui";
/*
* Raw HTML in the file is escaped, not parsed: markdown files arrive with downloads, and the preview
* renders on the API's origin. `validateLink` (on by default) refuses javascript:, vbscript:, file:,
* and non-image data: URLs. DOMPurify runs anyway, so neither guard is the only one.
*/
const markdown = new MarkdownIt({html: false, linkify: true});
// A URL with a scheme (https:, mailto:, ...) points somewhere other than the media directory.
const URL_WITH_SCHEME = /^[a-z][a-z0-9+.-]*:/i;
/**
* Resolve a URL written in a markdown file against the file's own media URL, the way a browser
* would resolve it against a document in that directory.
*
* Returns the URL unchanged if it is not relative, or null if it climbs out of the media directory;
* only media is served relative to a file.
*/
function resolveRelativeURL(url, fileURL) {
if (!url || URL_WITH_SCHEME.test(url) || url.startsWith('/') || url.startsWith('#')) {
return url;
}
const resolved = new URL(url, new URL(fileURL, window.location.origin));
if (!resolved.pathname.startsWith('/media/')) {
return null;
}
return resolved.pathname + resolved.search + resolved.hash;
}
function rewriteURL(token, attr, fileURL) {
const url = token.attrGet(attr);
if (url === null) {
return;
}
const resolved = resolveRelativeURL(url, fileURL);
if (resolved === null) {
token.attrs = token.attrs.filter(([name]) => name !== attr);
} else {
token.attrSet(attr, resolved);
}
}
function openInNewTab(token) {
const href = token.attrGet('href');
// Following a link would close the preview; a fragment stays within the document.
if (href && !href.startsWith('#')) {
token.attrSet('target', '_blank');
token.attrSet('rel', 'noopener noreferrer');
}
}
/** An image the preview may load: one served by this WROLPi, or embedded in the file. */
function isLocalImage(src) {
return !src || src.startsWith('data:') || (src.startsWith('/') && !src.startsWith('//'));
}
/**
* Replace an image from another site with a link to it. Loading it would tell that site who is
* reading the file and when (a tracking pixel), so the reader chooses whether to follow it.
*
* Inside a link (a README badge) the image becomes the outer link's text; links cannot nest.
*/
function replaceRemoteImage(state, image, insideLink) {
const src = image.attrGet('src');
const text = new state.Token('text', '', 0);
text.content = image.content || src;
if (insideLink) {
return [text];
}
const linkOpen = new state.Token('link_open', 'a', 1);
linkOpen.attrSet('href', src);
openInNewTab(linkOpen);
return [linkOpen, text, new state.Token('link_close', 'a', -1)];
}
markdown.core.ruler.push('wrolpi_media_urls', (state) => {
const {fileURL} = state.env;
for (const token of state.tokens) {
if (!token.children) {
continue;
}
let insideLink = false;
token.children = token.children.flatMap(child => {
if (child.type === 'image') {
rewriteURL(child, 'src', fileURL);
return isLocalImage(child.attrGet('src')) ? [child] : replaceRemoteImage(state, child, insideLink);
} else if (child.type === 'link_open') {
insideLink = true;
rewriteURL(child, 'href', fileURL);
openInNewTab(child);
} else if (child.type === 'link_close') {
insideLink = false;
}
return [child];
});
}
});
/** Render markdown to sanitized HTML. Relative URLs resolve against `fileURL`, the file's /media/ URL. */
export function renderMarkdown(text, fileURL) {
const html = markdown.render(text, {fileURL});
return DOMPurify.sanitize(html, {ADD_ATTR: ['target']});
}
export function isMarkdownFile(mimetype, lowerPath) {
// By suffix too, so a markdown file whose stored type is still text/plain (or a language libmagic
// guessed) is not shown raw; the 2026_10_05_1200 migration retags those rows, a refresh does not.
return mimetype.startsWith('text/markdown')
|| (mimetype.startsWith('text/') && (lowerPath.endsWith('.md') || lowerPath.endsWith('.markdown')));
}
/** Preview a markdown file, formatted or as its raw source. */
export function MarkdownPreview({url}) {
const [formatted, setFormatted] = useLocalStorage('markdownPreviewFormatted', true);
const [text, setText] = React.useState(null);
const [error, setError] = React.useState(null);
React.useEffect(() => {
const controller = new AbortController();
setText(null);
setError(null);
fetch(url, {signal: controller.signal})
.then(response => {
if (!response.ok) {
throw new Error(`${response.status} ${response.statusText}`);
}
return response.text();
})
.then(setText)
.catch(e => {
if (e.name !== 'AbortError') {
console.error(e);
setError(e.message);
}
});
return () => controller.abort();
}, [url]);
const html = React.useMemo(() => text === null ? null : renderMarkdown(text, url), [text, url]);
let body;
if (error) {
body = <Message kind='error' title='Could not load file'>{error}</Message>;
} else if (text === null) {
body = <Loading/>;
} else if (formatted) {
body = <div className='markdown-body' dangerouslySetInnerHTML={{__html: html}}/>;
} else {
body = <pre className='markdown-raw' data-testid='markdown-raw'>{text}</pre>;
}
return <>
<ButtonGroup>
<Button size='small' variant={formatted ? 'filled' : 'default'} onClick={() => setFormatted(true)}>
Formatted
</Button>
<Button size='small' variant={formatted ? 'default' : 'filled'} onClick={() => setFormatted(false)}>
Raw
</Button>
</ButtonGroup>
<div className='markdown-preview'>
{body}
</div>
</>
}

View file

@ -0,0 +1,198 @@
import React from 'react';
import {fireEvent, screen, waitFor} from '@testing-library/react';
import {isMarkdownFile, MarkdownPreview, renderMarkdown} from './MarkdownPreview';
import {renderUI} from '../test-utils';
const FILE_URL = '/media/notes/water/storage.md';
/** Render markdown into a detached element so assertions read the DOM, not the HTML string. */
const renderToDOM = (text, fileURL = FILE_URL) => {
const div = document.createElement('div');
div.innerHTML = renderMarkdown(text, fileURL);
return div;
};
describe('renderMarkdown', () => {
test('formats headings, emphasis, lists, code, and tables', () => {
const div = renderToDOM([
'# Water',
'',
'Rotate *every* barrel.',
'',
'- one',
'- two',
'',
'```',
'boil 1 minute',
'```',
'',
'| a | b |',
'|---|---|',
'| 1 | 2 |',
].join('\n'));
expect(div.querySelector('h1').textContent).toBe('Water');
expect(div.querySelector('em').textContent).toBe('every');
expect(div.querySelectorAll('ul li')).toHaveLength(2);
expect(div.querySelector('pre code').textContent).toBe('boil 1 minute\n');
expect(div.querySelectorAll('table td')).toHaveLength(2);
});
test('raw HTML in the file is shown as text, never parsed', () => {
const div = renderToDOM('<script>alert(1)</script>\n\n<img src=x onerror="alert(2)">');
expect(div.querySelector('script')).toBeNull();
expect(div.querySelector('img')).toBeNull();
expect(div.textContent).toContain('<script>alert(1)</script>');
});
test('script URLs are not turned into links', () => {
const div = renderToDOM('[click](javascript:alert(1))');
expect(div.querySelector('a')).toBeNull();
});
test('relative images resolve against the markdown file directory', () => {
const div = renderToDOM('![pump](images/hand%20pump.png)\n\n![tank](../tank.jpg)');
const [pump, tank] = div.querySelectorAll('img');
expect(pump.getAttribute('src')).toBe('/media/notes/water/images/hand%20pump.png');
expect(tank.getAttribute('src')).toBe('/media/notes/tank.jpg');
});
test('relative links resolve against the markdown file directory and open a new tab', () => {
const a = renderToDOM('[filters](filters.md#ceramic)').querySelector('a');
expect(a.getAttribute('href')).toBe('/media/notes/water/filters.md#ceramic');
expect(a.getAttribute('target')).toBe('_blank');
});
test('a relative URL that climbs out of the media directory is dropped', () => {
const div = renderToDOM('[api](../../../api/status)\n\n![x](../../../../x.png)');
expect(div.querySelector('a').hasAttribute('href')).toBe(false);
expect(div.querySelector('img').hasAttribute('src')).toBe(false);
});
test.each([
['https://tracker.example/pixel.gif'],
['http://tracker.example/pixel.gif'],
// Protocol-relative: starts with a slash, but loads from another host.
['//tracker.example/pixel.gif'],
])('an image from another site (%s) is not loaded, it becomes a link', (src) => {
const div = renderToDOM(`![pixel](${src})`);
expect(div.querySelector('img')).toBeNull();
const a = div.querySelector('a');
expect(a.getAttribute('href')).toBe(src);
expect(a.textContent).toBe('pixel');
expect(a.getAttribute('target')).toBe('_blank');
expect(a.getAttribute('rel')).toBe('noopener noreferrer');
});
test('an image from another site with no alt text is labeled by its URL', () => {
const a = renderToDOM('![](https://example.com/a.png)').querySelector('a');
expect(a.textContent).toBe('https://example.com/a.png');
});
test('an image from another site inside a link becomes the link text, not a nested link', () => {
// The badge pattern common in READMEs.
const div = renderToDOM('[![build status](https://ci.example/badge.svg)](https://ci.example/project)');
expect(div.querySelector('img')).toBeNull();
const links = div.querySelectorAll('a');
expect(links).toHaveLength(1);
expect(links[0].getAttribute('href')).toBe('https://ci.example/project');
expect(links[0].textContent).toBe('build status');
});
test('media and embedded data images still load', () => {
const [media, data] = renderToDOM('![a](/media/x/a.png)\n\n![b](data:image/png;base64,AAAA)')
.querySelectorAll('img');
expect(media.getAttribute('src')).toBe('/media/x/a.png');
expect(data.getAttribute('src')).toBe('data:image/png;base64,AAAA');
});
test('external links open in a new tab without an opener', () => {
const a = renderToDOM('<https://example.com/page>').querySelector('a');
expect(a.getAttribute('href')).toBe('https://example.com/page');
expect(a.getAttribute('target')).toBe('_blank');
expect(a.getAttribute('rel')).toBe('noopener noreferrer');
});
test('absolute and fragment URLs are left alone', () => {
const [root, fragment] = renderToDOM('[root](/files)\n\n[top](#top)').querySelectorAll('a');
expect(root.getAttribute('href')).toBe('/files');
expect(fragment.getAttribute('href')).toBe('#top');
expect(fragment.hasAttribute('target')).toBe(false);
});
});
describe('MarkdownPreview', () => {
const SOURCE = '# Water storage\n\nRotate *every* six months.\n';
beforeEach(() => {
window.localStorage.clear();
global.fetch = jest.fn(() => Promise.resolve({
ok: true,
text: () => Promise.resolve(SOURCE),
}));
});
afterEach(() => {
delete global.fetch;
});
test('fetches the file and shows it formatted', async () => {
renderUI(<MarkdownPreview url={FILE_URL}/>);
const heading = await screen.findByRole('heading', {name: 'Water storage'});
expect(heading.tagName).toBe('H1');
expect(global.fetch).toHaveBeenCalledWith(FILE_URL, expect.anything());
});
test('Raw shows the unformatted source, and the choice is remembered', async () => {
const {unmount} = renderUI(<MarkdownPreview url={FILE_URL}/>);
await screen.findByRole('heading', {name: 'Water storage'});
fireEvent.click(screen.getByRole('button', {name: 'Raw'}));
expect(screen.queryByRole('heading')).toBeNull();
expect(screen.getByTestId('markdown-raw').textContent).toBe(SOURCE);
// The next preview opens in the mode the reader chose last.
unmount();
renderUI(<MarkdownPreview url={FILE_URL}/>);
await waitFor(() => expect(screen.getByTestId('markdown-raw').textContent).toBe(SOURCE));
expect(screen.queryByRole('heading')).toBeNull();
fireEvent.click(screen.getByRole('button', {name: 'Formatted'}));
expect(screen.getByRole('heading', {name: 'Water storage'})).toBeTruthy();
});
test('a failed fetch shows an error instead of loading forever', async () => {
global.fetch = jest.fn(() => Promise.resolve({ok: false, status: 404, statusText: 'Not Found'}));
renderUI(<MarkdownPreview url={FILE_URL}/>);
expect(await screen.findByText(/404 Not Found/)).toBeTruthy();
});
});
describe('isMarkdownFile', () => {
test.each([
['text/markdown', 'notes/a.md', true],
// A stored type from before text/markdown existed; refresh does not retag unchanged files.
['text/plain', 'notes/a.md', true],
['text/plain', 'notes/a.markdown', true],
['text/plain', 'notes/a.txt', false],
// A suffix alone is not enough; a binary file named .md is not markdown.
['application/octet-stream', 'notes/a.md', false],
])('%s %s -> %s', (mimetype, lowerPath, expected) => {
expect(isMarkdownFile(mimetype, lowerPath)).toBe(expected);
});
});