Built-in Code & Markdown Editors
Relevant source files
The following files were used as context for generating this wiki page:
Termul provides integrated editing environments for source code and rich markdown documentation. These editors allow you to modify project files directly within the workspace layout, supporting features like syntax highlighting, live previews, and automated diagram rendering.
The system utilizes specialized stores for state management and tracks file buffers to handle dirty states and save operations. Markdown editing is powered by BlockNote for a block-based rich text experience, while code editing supports multiple programming languages.
Sources: README.md:27-32, README.md:120-120
Markdown Editor Architecture
The Markdown editor implements a block-based editing experience. It separates document metadata (frontmatter) from the content body to allow specialized editing for each.
Content Lifecycle and Syncing
The MarkdownEditor component manages the synchronization between the raw file content and the editor state. It uses the useBlockNote hook to interface with the underlying editor engine.
The diagram shows how incoming file content is split into metadata and body before being routed to respective UI components. Rejoining occurs before any changes are emitted back to the system.
Sources: src/renderer/components/editor/MarkdownEditor.tsx:87-105, src/renderer/components/editor/MarkdownEditor.frontmatter.test.tsx:84-98
Key Features
| Feature | Implementation |
|---|---|
| Rich Editing | Powered by BlockNote with support for headings, lists, and tables. |
| Mermaid Diagrams | Renders Mermaid charts inline within the document. |
| Frontmatter | Dedicated FrontmatterProperties panel for YAML metadata. |
| TOC Navigation | Side panel with smooth-scroll heading navigation. |
| Save Shortcut | Custom Mod-s extension triggers local file saves. |
Sources: README.md:29-31, src/renderer/hooks/use-blocknote.ts:63-74, src/renderer/components/editor/MarkdownEditor.tsx:254-266
Block-Based Content Management
Termul uses the useBlockNote hook to configure the editor schema and handle internal content transformations.
Mermaid Block Conversion
The system automatically detects code blocks marked with the mermaid language and converts them into custom mermaid blocks. This ensures diagrams render visually instead of appearing as raw code.
function convertMermaidBlocks(blocks: Array<Record<string, unknown>>): Array<Record<string, unknown>> {
return blocks.map((block) => {
if (block.type === 'codeBlock' && (block.props as Record<string, string> | undefined)?.language === 'mermaid') {
const source = Array.isArray(block.content) ? /* extract text */ '' : '';
return { ...block, type: 'mermaid', props: { source }, content: undefined };
}
// recursive processing for children
return block;
});
}
Sources: src/renderer/hooks/use-blocknote.ts:14-41
Debounced Updates
To prevent excessive disk I/O, the editor debounces content changes. When the user stops typing, the editor converts the current block document into markdown and notifies the parent component.
Metadata and Frontmatter Handling
Termul treats YAML frontmatter as a distinct data object. The MarkdownEditor renders a FrontmatterProperties component above the main document when metadata is detected.
- Extraction: The editor uses
splitFrontmatterto isolate YAML from the markdown body. - Editing: Users edit keys and values in a grid-based UI rather than raw text.
- Rejoining: The component rejoins the modified metadata with the current body before saving.
- Echo Protection: The editor tracks
pendingLocalEmitsto distinguish between local changes and external file reloads, preventing unnecessary re-renders.
Sources: src/renderer/components/editor/MarkdownEditor.tsx:169-188, src/renderer/components/editor/MarkdownEditor.frontmatter.test.tsx:103-120
Code Editor and Styling
The built-in code editor supports syntax highlighting and file buffers. The UI is integrated into the Termul dark-first design system.
Dependencies and Languages
According to package.json, the editor environment includes:
- CodeMirror Extensions: Support for JavaScript, TypeScript, Rust, Python, HTML, CSS, JSON, and YAML.
- Theming: Custom CSS tokens for dark mode consistency.
Sources: package.json:115-125
Styling normalizations
The index.css file defines specific overrides for the editor surfaces to ensure readability and integration with the workspace:
- Typography: Uses "Ioskeley Mono" for the code editor and "Inter Variable" for markdown prose.
- Container Queries: The
.markdown-editoruses container queries to adjust layout (padding, font sizes) based on the panel width. - Dark Mode: Forces
color-scheme: darkto ensure native scrollbars and dropdowns match the application theme.
Sources: src/renderer/index.css:564-573, src/renderer/index.css:700-730
Conclusion
The Built-in Editors in Termul provide a seamless transition between terminal commands and file modifications. By utilizing a block-based engine for Markdown and robust libraries like CodeMirror for source files, Termul maintains a high-performance editing environment within its project-centric workspaces.