mirror of
https://github.com/lrnselfreliance/wrolpi.git
synced 2026-10-26 19:01:39 -04:00
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:
parent
9739dc9e1b
commit
04779b8557
13 changed files with 828 additions and 10 deletions
|
|
@ -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';
|
||||
|
|
|
|||
|
|
@ -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/')) {
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
170
app/src/components/MarkdownPreview.js
Normal file
170
app/src/components/MarkdownPreview.js
Normal 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>
|
||||
</>
|
||||
}
|
||||
198
app/src/components/MarkdownPreview.test.js
Normal file
198
app/src/components/MarkdownPreview.test.js
Normal 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('\n\n');
|
||||
|
||||
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');
|
||||
|
||||
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(``);
|
||||
|
||||
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('').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('[](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('\n\n')
|
||||
.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);
|
||||
});
|
||||
});
|
||||
Loading…
Add table
Add a link
Reference in a new issue