Labnote Assistant (LabnoteV)

v0.54.4 · 한국어 → README.ko.md

A VS Code extension that helps you write experiment notes in Markdown. It opens .labnote.md files in a webview-based Section Editor, providing a UI optimized for lab note keeping — Front Matter forms, workflow checklists, unit operation accordions, sample definition buttons, clipboard image paste/thumbnails, and more.

Starting from v0.53.0, all UI strings and command labels in the extension are English by default. When VS Code's display language is set to Korean (ko), the command palette entries (%key% references) and runtime messages (vscode.l10n.t() calls) are automatically displayed in Korean via l10n/bundle.l10n.ko.json and package.nls.ko.json. User-written note content — Korean text, folder names, aliases, descriptions — is never auto-translated and is preserved exactly as you wrote it.

Quick Start

If you are new to LabnoteV, follow these steps:

1. Open the command palette (Ctrl+Shift+P / Cmd+Shift+P / F1).
2. Run Labnote: Create New Labnote Folder to create a new experiment.
3. Enter the experiment title and author name.
4. A labnote/{number}_{title}/ folder is created and README.labnote.md opens in the Section Editor.
   • The Section Editor is a form-based structured editor showing Front Matter (title/author/dates), Experiment Objective, Related Workflows, and Summary and Discussion as visual sections.
   • images/: folder for images pasted or saved during experiments.
   • resources/: folder for sample/workflow data.
5. Fill in the Experiment Objective section.
6. Add a workflow:
   • Click the flask icon in the Activity Bar → click the [Create] button next to a workflow in the workflow tree view.
   • Or run Labnote: Create Workflow from the command palette.
   • The workflow file is created immediately and linked as a checklist item under Related Workflows.
   • The workflow description can be edited inline in the Section Editor (changes are automatically reflected back in README.labnote.md).
7. Click a workflow title to open its .labnote.md file in the Section Editor.
   • A "Back to Lab Note" link is shown at the top of the workflow file so you can return to the original experiment note.
8. Add unit operations to the workflow:
   • Click [Insert] next to the desired unit operation in the Activity Bar.
   • Unit operations are displayed as accordions; reorder them by drag-and-drop.
   • HW (hardware): Input, Reagent, Consumables, Equipment, Method, Output, Results & Discussions.
   • SW (software): Input, Output, Parameters, QC Metrics, Method, Environment, Discussion.
   • Each section heading (including Output) has a flask (+Sample) button to insert a sample definition.
   • When new workflows/unit operations are created, the body content (section placeholders, the "Unit operations are appended here automatically" hint, etc.) is always stored in English regardless of the active VS Code locale, ensuring file compatibility across users. Existing Korean content from older notes is treated as user data and never rewritten.
9. Define samples:
   • Click +Sample next to a section heading → enter type/alias/description in the modal → a line in the form - @type;ID;alias;description is inserted in that textarea.
   • Custom types can also be defined directly in the modal.
   • Or right-click a type in the Sample TreeView (Activity Bar) → Add Sample. The newly created sample appears under the type; use [Insert to Editor] to reference it from any Section Editor textarea.
10. Reference samples:
    • Place the cursor in any textarea inside a unit operation.
    • Click the [Insert to Editor] button in the Sample TreeView (Activity Bar).
11. Images:
    • Paste clipboard images at the cursor position with Ctrl+V.
    • Images are saved to the images/ folder and a Markdown image link is inserted.
    • A thumbnail appears below the textarea; if you write ![Title](https://github.com/sblabkribb/labnotev/raw/HEAD/link), the title is shown under the thumbnail.
    • File attachment (clip icon next to a section heading): files inside the experiment folder are inserted as relative links only; files outside are copied into resources/attachments/ and then linked. Image attachments are also previewed as thumbnails.
12. Tables:
    • Click the table icon next to a section heading → specify rows/columns → a table template is inserted.
    • Inside a table, Tab moves to the next cell, Shift+Tab to the previous cell (Tab in the last cell adds a new row).
    • Pasting data from Excel/Google Sheets is automatically converted into a Markdown table.
    • The align button auto-aligns table columns (CJK character widths are taken into account).
13. Miscellaneous:
    • The document is auto-saved 1.5 seconds after edits stop; a status badge at the top shows the current state.
    • Dark mode: toggle dark/light mode via the moon/sun icon at the top-right of the editor (the setting is auto-saved).
    • The top-right of the editor title bar provides quick switches between Text Editor, Section Editor (flask icon), and Preview.
    • Markdown preview line breaks: the extension applies markdown.preview.breaks: true as the default so that a single Enter is rendered as a line break in the built-in preview (an explicit false in your settings.json takes precedence).

Features

Section Editor (default editor)

When you open a .labnote.md file, the Section Editor is shown automatically. It parses the Markdown into a structured form UI and serializes edits back to Markdown when saving.

Lab Note mode (README.labnote.md)

• Front Matter form: edit Title, Author, Experiment Type, Created Date, and Last Updated in a form UI.
  • Date fields use a DatePickerInput (calendar) plus a time input (auto-formatted, with a "Now" button).
• Experiment Objective: a free-form textarea for the experiment objective.
• Related Workflows: checklist of linked workflows.
  • Clicking a workflow title opens that workflow's .labnote.md in the Section Editor.
  • On save, a ## Related Unit Operations section is generated below the checklist with anchor links to each workflow and unit operation. The Markdown preview can be used to navigate to those headings.
• Results & Discussion: free-form textarea for experiment results and discussion.
• Summary and Discussion: free-form textarea for the overall experiment summary.

Workflow mode (workflow .labnote.md)

• Back to Lab Note link: appears at the top so you can return to the original lab note.
• Front Matter form: edit Title, Experimenter, Created Date, Last Updated, and End Date.
• Workflow Header: shows the workflow title and an inline-editable description. Editing the description automatically synchronizes the matching checklist entry in README.labnote.md.
• Unit Operations: shown as an accordion UI.
  • Reorder by drag-and-drop.
  • The unit operation alias is editable inline next to the name.
  • Meta section: Experimenter (text input) plus Start/End Date (calendar + time picker) shown as structured fields.
  • Typos such as #### Reagen are auto-normalized back to #### Reagent when saving/loading.
  • Other sections (Input, Output, Method, etc.) are free-form textareas.
  • Unit operation IDs inserted from the catalog follow the UHW… (hardware) / USW… (software) prefix scheme. The Section Editor's HW/SW indicator and Meta Equipment / Software fields are aligned to that prefix (the recognition is stable even after editing the body via a text editor).
  • The +Sample button opens the sample creation modal: choose a type (8 built-ins + custom), enter an alias, enter a description, all in one place.
  • For Reagent/Labware, the "Search product" button opens a QuickPick over the local reference catalog at resources/labsamples/{Reagent|Labware}_*.json (plus the workspace-level catalog and, for Labware only, the SBLIMS MongoDB Item_Catalog when labnotev.enableMongo is on). If no candidates are found, an information toast explains what to add or which setting to enable.
  • "Add new type" lets you define a custom sample type (stored in workspace settings).
• Conclusions and Discussion: textarea for the overall workflow summary and discussion. When saving, the Markdown always includes a ## Conclusions and Discussion section, kept in sync between the Section Editor UI and the body so they don't duplicate.

Common features

• Auto-save: edits are saved 1.5 seconds after the last change; the status badge at the top shows Saved / Unsaved changes / Saving.
• Image paste: every textarea (including Conclusions and Discussion) accepts clipboard images via Ctrl+V.
  • Images are saved into images/ and a Markdown image link is inserted.
  • After insertion, the cursor is positioned at the end of the inserted text (the same behavior applies to sample/text insertions).
  • Thumbnails appear below the textarea; writing ![Title]() shows the title under the thumbnail.
  • Click a thumbnail to open the image in a zoomable modal.
• File attachment: clicking the attachment icon next to a section heading lets you pick a file. Files inside the same experiment folder as the open .labnote.md (under images/, resources/, etc.) are referenced via a relative link without copying. Files outside the experiment folder are copied into resources/attachments/ and linked from there. Unlike clipboard paste, attachments are always inserted in [name](https://github.com/sblabkribb/labnotev/blob/HEAD/path) form.
  • Attachment links appear below the textarea; clicking opens the file (Office files prefer the OS default app).
  • Image-extension attachments are previewed as thumbnails like pasted images, while PDFs/spreadsheets/etc. show only a paperclip link row.
• Auto-grow textarea: all SectionEditor textareas grow to fit their content (no inner scrollbar).
• Sample ID highlighting: sample IDs inside textareas are highlighted per type color (including custom types).
  • Clicking a highlighted ID jumps to its definition.
• Markdown table support: every textarea (SectionEditor and UnitOp sections) helps you author Markdown tables.
  • Click the table icon next to a heading → specify rows/columns → insert a table template.
  • Tab/Shift+Tab navigates cells; Tab in the last cell adds a new row.
  • Pasting from Excel/Google Sheets auto-converts to a Markdown table.
  • The align button auto-aligns columns (CJK widths considered).
• Tab indent / Shift+Tab outdent: outside of tables, Tab inserts 2 spaces and Shift+Tab removes up to 2 leading spaces. Selecting multiple lines applies the operation to all selected lines (useful for Markdown list indentation).
  • Column alignment is triggered only via the toolbar align button (there is no dedicated keyboard shortcut).
• Dark mode: toggle dark/light via the moon/sun icon (auto-saved).
• Open as text: a top-bar button opens the raw Markdown in VS Code's text editor.
• 3-way editor switcher: top-right buttons switch between Text Editor, Section Editor, and Preview.
  • Text Editor / Preview modes: click the flask icon to switch to Section Editor.
  • Section Editor mode: click the Markdown editor / preview icon to switch to the corresponding mode.

Sample ID management

Sample IDs are defined in the form @type;ID;alias;description and referenced in the form ID;alias. (Legacy | and : separators are still supported.)

Sample management in the Section Editor

• Sample creation modal: click the +Sample button next to any section heading inside a unit operation. The modal lets you pick a type (8 built-ins + custom), enter an alias, and enter a multi-line description, then inserts - @type;ID;alias;description.
  • For Reagent/Labware, the "Search product" button searches the local + workspace resources/labsamples/{type}_*.json catalogs, plus the SBLIMS MongoDB Item_Catalog for Labware when labnotev.enableMongo is enabled. If the catalog is empty, a toast points you to the file path or the MongoDB setting so the button is never a silent no-op.
  • "Add new type" defines a custom type usable for highlighting and extraction/storage.
• Highlighting: sample IDs in textareas are color-coded by type.
• Navigation: clicking a highlighted sample ID jumps to its definition.

@ autocomplete in text editors (.md files)

When a regular .md file is opened in the text editor:

• @dna:, @rna:, @plasmid:, @reagent:, @primer:, @labware: — type-specific sample search.
• @sample: — search across all types.
• @equip: — equipment search (MongoDB / local).
• Typing the colon (:) opens the autocomplete list; further typing filters it.
• The list includes "Generate new ID" and "Enter info" actions.

Sample storage

• On save, sample information is automatically written to resources/labsamples/{TYPE}.json.
• Even when an experiment folder is opened as the workspace root (where the local and global labsamples paths coincide), consecutive saves no longer wipe the local JSON.
• Supported formats: @type;ID;alias;description, ID;alias;description, ID;alias, ID: description (and the legacy | / : separators).
• Aliases may contain spaces or special characters (e.g. Reagent-1|UltraPure™ DNase/RNase-Free Water:description).
• Reference DB: {TYPE}_{name}.json files provide read-only product catalogs.
  • Examples: reagent_buffer.json, labware_plate.json.

Sample TreeView (Activity Bar)

• Tree view: a sample panel with the flask icon is shown in the VS Code Activity Bar.
• Local / Global split: samples in the experiment folder and the workspace root are shown separately.
  • Local samples are loaded from resources/labsamples/ inside the experiment folder of the currently active .labnote.md.
  • Switching to a .labnote.md from a different experiment automatically swaps in that experiment's local samples (in both the text editor and the Section Editor).
  • Custom sample types (via the labnotev.customSampleTypes setting) appear in the tree alongside built-ins; the tree refreshes automatically when the setting changes.
• Hierarchy:
  • Samples (Local) / Samples (Global): root nodes.
  • DNA [3], RNA [1], etc.: per-type nodes (built-in + custom).
  • DNA-123 | SampleA: individual sample.
• Context menu:
  • Double-click a sample (or click the inline [Insert to Editor] icon): insert ID;alias into the active Section Editor textarea (reference). If the file is open as a plain markdown text editor instead, a nudge points you to Labnote: Search Sample — use that command (or the search icon in the tree view title bar) to insert at the cursor in text mode.
  • Right-click → Move to Definition: scroll the active Section Editor webview to the sample's @type;ID... definition inside the current document. The command stays inside the Section Editor and does not open the markdown text editor.
  • Right-click a type → Add Sample: add a new sample.
  • Right-click a sample → Edit Sample: rename/redescribe.
  • Move to Global / Move to Local: move the sample's scope.
• Drag-and-drop: dragging a sample node into any editor inserts @type;ID;alias;description. Multi-select inserts multiple lines.
• Reordering: dropping a sample on another sample within the same type (e.g. DNA) reorders them and persists to the JSON file. Dropping on the type node moves to the end. Multi-select preserves relative order. Drops across types or scopes are ignored — use the "Move to Global/Local" commands instead.
• Per-type icon color: the type node icon uses the same palette as body highlighting, making types easy to distinguish at a glance.
• Empty state: when a type has no samples, a "No samples" row is shown (Local hints at the right-click "Create Sample" action; Global explains that saving an @type;id definition anywhere registers the sample automatically).
• Sample search: the search icon in the tree view title bar, or run Labnote: Search Sample from the Command Palette. The QuickPick searches every Local + Global sample by ID, alias, and description.
  • The selected sample is inserted at the cursor in both the Section Editor and the plain markdown text editor, so this is the recommended path for inserting samples while editing the raw .labnote.md as text. (The tree view inline Insert to Editor action stays Section Editor-only by design.)

Workflow TreeView (Activity Bar)

• Workflow tree view: shown alongside Lab Samples in the Activity Bar, displays the workflow catalog.
• Hierarchy:
  • Workflows [50]: root.
    • Design [13]: design workflows (WD prefix).
    • Build [17]: build workflows (WB prefix).
    • Test [19]: test workflows (WT prefix).
    • Learn [10]: learn workflows (WL prefix).
    • General [1]: general workflows (WG prefix) — Blank Workflow and other DBTL-independent workflows.
  • HW Unit Operations: hardware unit operations (UHW prefix).
  • SW Unit Operations: software unit operations (USW prefix).
• Workflow commands:
  • [Create] button: create the workflow file from README.labnote.md.
  • Right-click → Edit, Delete: edit/remove the JSON entry.
  • Right-click a category → Add Workflow: add a new workflow.
• Unit operation commands:
  • [Insert] button: insert the unit operation template into the currently open workflow.
  • Right-click → Edit, Delete: edit/remove the JSON entry.
  • Right-click the root → Add Unit Operation: add a new unit operation.
• Search: the search icon in the tree view title bar searches workflows and unit operations.
• Auto resource copy: on first run, the extension's JSON files are copied to the workspace so users can freely edit them.

Image handling

• Image paste in the Section Editor: every textarea accepts clipboard images via Ctrl+V.
  • Images are saved into images/ and a Markdown image link (![](https://github.com/sblabkribb/labnotev/raw/HEAD/images/img_xxx.png)) is inserted.
  • A thumbnail appears below the textarea automatically.
  • Clicking the thumbnail opens a zoomable modal.
• Attachment-style images: image references inserted as [filename](https://github.com/sblabkribb/labnotev/blob/HEAD/images/…) / [filename](https://github.com/sblabkribb/labnotev/blob/HEAD/resources/…) are also rendered as thumbnails and previewable in the modal (deduplicated against any matching ![](https://github.com/sblabkribb/labnotev/raw/HEAD/same-path)).
• Image preview panel: clicking an image link opens a dedicated preview panel.
  • Zoom controls (+, -, Reset).
  • Keyboard shortcuts: Esc (close), +/- (zoom), 0 (reset).

Experiment folder structure

• Create a new experiment: Labnote: Create New Labnote Folder prompts for title and author.
• Location: labnote/{number}_{title}/.
• Auto numbering: 001, 002, ...
• Auto-generated entries:
  • README.labnote.md: the main experiment overview (opens in the Section Editor).
  • images/: image folder.
  • resources/: samples/workflows data folder.
• Workflow filename format: {number}_{workflowID}_{name}.labnote.md (e.g. 001_WD010_General_Design_of_Experiment.labnote.md).
• Rename Workflow: the Labnote: Rename Workflow command (v0.52+) renames a workflow across five places at once — file name, front matter title, body H1 heading, and the matching checklist label/link in README.labnote.md.

Date management

• Section Editor: edit Front Matter's Created Date, Last Updated, and End Date via calendar + time input.
  • Click the time input to clear it; typing digits auto-formats to HH:MM (auto-confirmed at 4 digits).
  • The "Now" (clock icon) button immediately sets the current date+time.
• Text editor: keyboard shortcuts to insert/update dates.
  • Ctrl+Shift+D / Cmd+Shift+D: insert date/time.
  • Ctrl+Shift+U / Cmd+Shift+U: update date fields.

MongoDB integration (optional, disabled by default)

Equip and Labware samples can be loaded from the SBLIMS MongoDB. Since v0.48.0, this is off by default — you must enable it explicitly before any connection is attempted.

Configuration

1. Open VS Code settings (Ctrl+,).
2. Search for "Lab Note Editor".
3. Configure:
   • Enable Mongo: enable SBLIMS MongoDB integration (default: false).
   • Mongo Url: MongoDB connection URL.
   • Mongo Db Name: database name (default: SBLIMS).

Connection URL format

mongodb://username:password@host:port/?authMechanism=SCRAM-SHA-256&authSource=SBLIMS

Lazy loading and opt-in behavior

• When labnotev.enableMongo is false, the extension does not load the MongoDB driver at all, and Equip/Labware autocomplete/pickers source data only from local/global JSON. This eliminates the 5–10 second blocking caused by unreachable servers.
• When labnotev.enableMongo is true, the MongoDB connection is established lazily — not at activation time, but on the first call to an Equip/Labware-related feature (autocomplete, sample tree Equip type, Labware product picker, etc.) — and only once.
• Changing any of labnotev.enableMongo / labnotev.mongoUrl / labnotev.mongoDbName triggers an automatic reload without restarting VS Code. To retry immediately, run Labnote: Reload Remote Data (MongoDB) from the command palette. The sample tree's Equip/Labware list is refreshed automatically when the reload finishes.

Localization

• The extension's UI strings and command labels are English by default. When VS Code's display language is set to Korean (ko), command palette entries (%key% references) and runtime messages (vscode.l10n.t()) are automatically rendered in Korean.
• Translation sources:
  • package.nls.json / package.nls.ko.json: translations for declarative strings in package.json (e.g. command titles).
  • l10n/bundle.l10n.ko.json: translations for runtime messages and prompts.
• User-written note content is never auto-translated. Korean text, folder names, aliases, and descriptions are preserved exactly.
• Newly created body content is always English-fixed: when creating new workflows/unit operations, the body strings written to disk (section placeholders, the "Unit operations are appended here automatically" hint, etc.) are stored in English regardless of the active locale. This guarantees file compatibility across users with different display languages.
• To switch VS Code's display language: command palette → Configure Display Language → pick a language → restart.

Installation

Install from GitHub Releases

1. Download the latest .vsix from the Releases page.
2. In VS Code, run Ctrl+Shift+P → Extensions: Install from VSIX...
3. Select the downloaded .vsix.
4. After installation, restart VS Code, open your workspace, press F1, and run any command starting with Labnote.

Commands

Troubleshooting

When the Section Editor does not open

If a .labnote.md file opens in the regular text editor instead of the Section Editor, configure the default editor as follows.

Option 1: "Open With" menu

1. Right-click a .labnote.md file → "Open With..."
2. Choose "Lab Note Section Editor".
3. Click "Configure default editor for '*.labnote.md'" to make it the default.

Option 2: edit settings.json directly

Add the following to VS Code's settings.json:

{
  "workbench.editorAssociations": {
    "*.labnote.md": "labnotev.sectionEditor"
  }
}

Option 3: use the editor title bar button

When a .labnote.md is opened in the text editor or the preview, the editor title bar shows a flask icon that switches to the Section Editor. While in the Section Editor, the Markdown editor and preview icons let you switch back.

Normally, installing the extension automatically registers the Section Editor as the default. The settings above may be required when other Markdown extensions conflict with it.

When @ autocomplete doesn't appear

• @ autocomplete only works in the text editor. In the Section Editor, use the per-section sample definition buttons.
• Make sure the .md file is open in the text editor (you can switch from the Section Editor via "Open in text editor").
• Autocomplete is triggered after prefixes like @dna:, @rna:, @sample:.
• If the sample tree in the Activity Bar looks stale, click the refresh icon to re-read it.

When MongoDB is not used

• Since v0.48.0, MongoDB integration is disabled by default (labnotev.enableMongo = false), so you can use all local/global JSON-based sample management, workflows, and unit operations without any additional setup.
• Only turn on labnotev.enableMongo and configure the connection URL if you want to load external lists like Equip/Labware.

File format

• Experiment notes are saved as .labnote.md Markdown files.
• The Section Editor parses Markdown into structured UI and serializes edits back to Markdown when saving, preserving the original Markdown compatibility.
• Standard Markdown — image links, YAML front matter, etc. — is fully supported.

- @dna:DNA-123|SampleA:assembly template

DNA-123|SampleA

In the example above, the first line is a sample definition (starts with @) and the second is a body reference (just the ID without @).

Requirements

• VS Code: ^1.85.0

Developer notes

To run or develop from source, clone the repository and use:

npm run install:all
npm run build
npm test

• npm test: host-side Vitest unit tests (src/__tests__/**).
• cd webview-section && npm test: webview-side Vitest component tests.
• npm run build: bundles the host with esbuild and the webview with Vite.
• The English/Korean UI is switched automatically based on VS Code's display language. To add or modify Korean translations, edit l10n/bundle.l10n.ko.json and package.nls.ko.json in the workspace root.

License

MIT License