This guide provides detailed documentation for developers using SquibView in their applications.
npm install squibview
<!-- Latest version --><scriptsrc="https://unpkg.com/squibview/dist/squibview.standalone.min.js"></script><linkrel="stylesheet"href="https://unpkg.com/squibview/dist/squibview.css">
SquibView is available in multiple formats:
<!-- Optional dependencies for advanced features --><scriptsrc="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.5.1/highlight.min.js"></script><scriptsrc="https://unpkg.com/mermaid/dist/mermaid.min.js"></script><!-- SquibView (markdown-it is now bundled!) --><linkrel="stylesheet"href="../dist/squibview.css"><scripttype="module">importSquibViewfrom'../dist/squibview.esm.min.js';
const editor = newSquibView('#editor');
</script>
<!-- Import map for external dependencies --><scripttype="importmap">
{
"imports": {
"markdown-it": "https://esm.sh/markdown-it@14.1.0",
"tiny-emitter": "https://esm.sh/tiny-emitter@2.1.0",
"diff-match-patch": "https://esm.sh/diff-match-patch@1.0.5"
}
}
</script><!-- Optional dependencies --><scriptsrc="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.5.1/highlight.min.js"></script><!-- SquibView lean build --><scripttype="module">importSquibViewfrom'../dist/squibview.esm-lean.min.js';
const editor = newSquibView('#editor');
</script>
<!-- Optional dependencies for advanced features --><scriptsrc="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.5.1/highlight.min.js"></script><scriptsrc="https://unpkg.com/mermaid/dist/mermaid.min.js"></script><!-- SquibView (markdown-it is now bundled!) --><linkrel="stylesheet"href="../dist/squibview.css"><scriptsrc="../dist/squibview.umd.min.js"></script><script>const editor = newSquibView('#editor');
</script>
<!-- Required dependencies --><scriptsrc="https://cdnjs.cloudflare.com/ajax/libs/markdown-it/14.1.0/markdown-it.min.js"></script><scriptsrc="https://unpkg.com/tiny-emitter@2.1.0/dist/tinyemitter.min.js"></script><scriptsrc="https://unpkg.com/diff-match-patch@1.0.5/index.js"></script><!-- Optional dependencies --><scriptsrc="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.5.1/highlight.min.js"></script><!-- SquibView lean build --><scriptsrc="../dist/squibview.umd-lean.min.js"></script><script>const editor = newSquibView('#editor');
</script>
<!-- SquibView --><linkrel="stylesheet"href="../dist/squibview.css"><scriptsrc="../dist/squibview.standalone.min.js"></script><script>const editor = newSquibView('#editor');
</script>
const editor = newSquibView('#editorContainer', {
// Configuration options
});
// Set Markdown content
editor.setContent('# Hello World\n\nThis is a test.', 'md');
// Set HTML content
editor.setContent('<h1>Hello World</h1><p>This is a test.</p>', 'html');
// Set CSV content
editor.setContent('name,age\nJohn,30\nJane,25', 'csv');
// Switch to source view
editor.setView('src');
// Switch to rendered view
editor.setView('html');
// Switch to split view
editor.setView('split');
const editor = newSquibView('#editorContainer', {
initialContent: '', // Initial content to loadinputContentType: 'md', // Type of content ('md', 'html', 'reveal', 'csv', 'tsv')showControls: true, // Whether to show control buttonstitleShow: false, // Whether to show the title sectiontitleContent: '', // Content for the title sectioninitialView: 'split', // Initial view mode ('src', 'html', 'split')baseClass: 'squibview', // Base CSS class for styling
});
const editor = newSquibView('#editorContainer', {
preserveImageTags: true, // Whether to keep original image URLs in source view// When true: images remain as <img> tags with original URLs// When false: images are converted to data URLs// Note: Images are always converted to data URLs when copying
});
Detailed Explanation of preserveImageTags
:
The preserveImageTags
option (boolean, defaults to true
) controls how SquibView handles <img>
tags when processing and displaying Markdown content, particularly in the source view and during copy operations.
preserveImageTags: true
(Default Behavior):
<img>
tags will retain their original src
attributes (e.g., https://example.com/image.png
or ../images/local.jpg
). This is generally preferred for maintaining a clean and readable Markdown source, as it keeps image references as links rather than embedding large data strings.src
URLs.preserveImageTags: false
:
src
attribute of the <img>
tag. Both the source view (if you were to inspect the HTML generated by renderMarkdown
before it’s placed in the DOM) and the live rendered view will use these data URLs.crossOrigin = 'anonymous'
for images, which helps for CORS-enabled servers).Behavior during copyHTML()
(Copy Rendered):
preserveImageTags
setting, when the user clicks the “Copy Rendered” button (which calls the copyHTML()
method), SquibView will always attempt to convert all images within the copied content to data URLs.When to Use Which Setting:
preserveImageTags: true
(default) if:
preserveImageTags: false
if:
const editor = newSquibView('#editorContainer', {
onReplaceSelectedText: (selectionData) => {
// Handle text selectionreturn'replacement text'; // Return string to replace selection
}
});
// Content Management
editor.setContent(content, contentType) // Set content
editor.getContent() // Get current content
editor.getMarkdownSource() // Get markdown source
editor.getHTMLSource() // Get HTML source// View Management
editor.setView(view) // Set view mode
editor.toggleView() // Toggle between views
editor.controlsShow(show) // Show/hide controls
editor.titleShow(show) // Show/hide title
editor.titleSetContent(content) // Set title content
editor.titleGetContent() // Get title content// Copy Operations
editor.copySource() // Copy source content
editor.copyHTML() // Copy rendered HTML// Revision History
editor.revisionUndo() // Undo last change
editor.revisionRedo() // Redo last change
editor.revisionSet(index) // Set to specific revision
editor.revisionNumRevsions() // Get number of revisions
editor.revisionGetCurrentIndex() // Get current revision index// Diff Viewing (New in v1.0.13)
editor.getSourceDiff(options) // Get diff data between revisions
editor.getSourceDiffHTML(options) // Get side-by-side diff HTML
editor.getSourceDiffInline(options) // Get inline diff HTML (blue/red)
Compare different revisions of your content with visual diff displays.
Returns raw diff data between two revisions.
// Get diff between current and previous revisionconst diffData = editor.getSourceDiff();
// Get diff between specific revisionsconst diffData = editor.getSourceDiff({
fromIndex: 0, // Starting revision (-1 for initial state)toIndex: 3// Ending revision
});
// Returns: { added, removed, changed, stats, patches }
Returns side-by-side diff visualization as HTML.
// Compare current vs previousconst diffHTML = editor.getSourceDiffHTML();
// Compare specific revisionsconst diffHTML = editor.getSourceDiffHTML({
fromIndex: 1,
toIndex: 5,
showLineNumbers: true// Optional
});
// Insert into pagedocument.getElementById('diff-view').innerHTML = diffHTML;
Returns inline diff with blue additions and red strikethrough deletions.
// Get inline diffconst inlineHTML = editor.getSourceDiffInline({
fromIndex: 0,
toIndex: -1// Compare against current
});
// Styling: additions in blue, deletions in red with strikethrough
// Get current selectionconst selection = editor.getCurrentSelection();
// Replace selected text
editor.replaceSelectedText('new text', selection);
// Make selection editable/non-editable
editor.setSelectionEditable(true, selection);
// Toggle selection lock
editor.toggleSelectionLock(selection);
// Register selection callbackconst unsubscribe = editor.onTextSelected((selectionData) => {
console.log('Selected:', selectionData.text);
});
import { SquibViewReact } from'squibview/react';
functionApp() {
return (
<SquibViewReactinitialContent="# Hello World"inputContentType="md"showControls={true}
/>
);
}
<SquibViewReact// Basic props
initialContent=""
inputContentType="md"
showControls={true}
titleShow={false}
titleContent=""
initialView="split"// Image handling
preserveImageTags={true}
// Event handlers
onContentChange={(content, type) => {}}
onViewChange={(view) => {}}
onTextSelected={(selectionData) => {}}
/>
const myPlugin = {
name: 'myPlugin',
init: (editor) => {
// Plugin initialization
},
destroy: () => {
// Cleanup
}
};
// Register plugin
editor.registerPlugin(myPlugin);
editor.registerRenderer('custom', {
render: (source) => {
// Render source to HTMLreturn html;
},
sourceToOutput: (source) => {
// Convert source to output formatreturn output;
},
outputToSource: (output) => {
// Convert output back to sourcereturn source;
},
operations: {
customOp: (source) => {
// Custom operationreturn modifiedSource;
}
},
buttons: [
{
label: 'Custom',
action: 'customOp',
title: 'Custom operation'
}
]
});
editor.events.on('content:change', (content, type) => {});
editor.events.on('view:change', (view) => {});
editor.events.on('text:selected', (selectionData) => {});
editor.events.on('markdown:rendered', (markdown, html) => {});
editor.events.on('html:rendered', (html) => {});
editor.events.on('revision:undo', (content, type) => {});
editor.events.on('revision:redo', (content, type) => {});
editor.events.on('revision:set', (index, content, type) => {});
editor.events.on('controls:visibility', (show) => {});
editor.events.on('title:visibility', (show) => {});
editor.events.on('title:content', (content) => {});
editor.events.on('layout:change', (view, dimensions) => {});
editor.events.on('renderer:registered', (type, config) => {});
const editor = newSquibView('#editor', {
initialContent: '# Hello World\n\nThis is a test.',
inputContentType: 'md',
showControls: true,
initialView: 'split'
});
const editor = newSquibView('#editor', {
initialContent: 'name,age\nJohn,30\nJane,25',
inputContentType: 'csv',
showControls: true,
initialView: 'html'
});
const editor = newSquibView('#editor', {
initialContent: '# Slide 1\n\nContent\n\n---\n\n# Slide 2\n\nMore content',
inputContentType: 'reveal',
showControls: true,
initialView: 'html'
});
import { SquibViewReact } from'squibview/react';
functionApp() {
return (
<SquibViewReactinitialContent="# Image Example\n\n"inputContentType="md"preserveImageTags={true}onContentChange={(content,type) => {
console.log('Content changed:', content);
}}
/>
);
}
This section provides information for developers contributing to SquibView or setting up a local development environment.
For local development, a convenient script dev-bump-build-test.sh
is provided in the root of the repository. This script automates several common tasks:
0.0.38
to 0.0.39
).0.0.39-dev.0
). This uses npm version prepatch --preid dev
internally.src/version.js
: The script runs tools/updateVersion.js
to propagate the new version from package.json
to src/version.js
, ensuring the library reports the correct version at runtime.tests/log.out
for easier debugging.Usage:
To run the script, navigate to the root of the SquibView repository in your terminal and execute:
./dev-bump-build-test.sh
This script is particularly useful for quickly testing changes with an updated version number in a development context without creating git tags.
For more comprehensive information on the development workflow, versioning strategy, running tests, and debugging, please refer to the CONTRIBUTING.md file.
For browser environments, you can use a <script>
tag pointing to a CDN:
<scriptsrc="https://unpkg.com/squibview/dist/squibview.standalone.umd.min.js"></script>
Or, if you have it locally:
<scriptsrc="../dist/squibview.standalone.umd.min.js"></script>
const editor = newSquibView('#editorContainer', {
// Configuration options
});