--- title: "Yeli tutorial" lang: en description: "Current experimental version · Checked 2026-10-24" --- # Yeli tutorial Editable HTML contains code. Open files only from trusted sources. Keep both handbooks of the same language together for cross-course links. ## Features and where to find them Yeli carries Markdown, images and a reading/editing environment in one `.yeli.html`. Download a trusted file and open it in a browser to read; choose Edit to write. Find a capability here, then follow its tutorial. ### Choose your goal | What you need | Start here | | --------------------------------------------------- | --------------------------------------------------- | | Open, write a few sentences and save | [Quick start](#your-first-edit-and-save) | | Understand the toolbar, outline and right panel | [Workspace](#find-your-way-around) | | Look up a key combination | [Keyboard shortcuts](#keyboard-shortcuts) | | Find every command and its conditions | [Complete command reference](#complete-command-reference) | | Follow a meeting, long-document or sharing workflow | [Workflows and best practices](#workflows-and-best-practices) | | Understand Markdown, Agents and Yeli | [Why Yeli](#why-yeli) | “More → Save” means open More at the end of the toolbar and choose the action directly. File, Export, View, and Settings & help are **section labels**, not intermediate submenus. The save action depends on browser capabilities. ### Open and write | Feature | Where and how | When to use it / Details | | ------------------------------------------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | | Open offline | Download `.yeli.html` and open in a browser | No account or server; download attachments if their preview cannot edit. [Quick start](#your-first-edit-and-save) | | Start a document | Copy a trusted starter, or More → Open file to import `.md` | One file per document; preserve current work first. [Quick start](#your-first-edit-and-save) | | Preview / Edit | Edit or Preview at the top | Hide tools for reading; work directly on the page for changes. [Workspace](#find-your-way-around) | | Edit text and title | In Edit, click text or the document title at the top | Write first, then format. [Writing](#edit-text-and-selections) | | Text formatting | Select text and use floating tools or shortcuts | Bold, italic, strike, inline code, links and clear formatting. [Selections](#edit-text-and-selections) | | Headings, lists, tasks, quotes, code and dividers | Top Insert; empty-block `+` or `/` | Express hierarchy with structure; H1–H6 are available. [Blocks and slash](#blocks-slash-commands-and-templates) | | Convert, duplicate and delete blocks | Target block's type menu | Adjust content; complex blocks offer only safe operations. [Block operations](#blocks-slash-commands-and-templates) | | Meeting notes template | Templates section in Insert | Start decisions and next steps; fill date and participants yourself. [Templates](#blocks-slash-commands-and-templates) | | Local Markdown source | The block's Edit Markdown action | Handle structures that cannot be edited directly; check scope before committing. [Local source](#edit-text-and-selections) | ### Organize and find | Feature | Where and how | When to use it / Details | | -------------------------------- | -------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | | Heading outline | Top-left Yeli logo; `⌘/Ctrl + Shift + O` | Jump by heading and collapse levels; the filter searches headings only. [Workspace](#find-your-way-around) | | Full-text search and replacement | Top Search; `⌘/Ctrl + F` | Find body text; inspect matches before replacing in Edit. [Find and replace](#find-and-replace) | | Markdown tables | Insert → Table, choose dimensions; focus a cell for structural tools | Simple rows and columns; no formulas or merged cells. [Tables](#edit-tables) | | Images and offline assets | Image insertion in Edit; select an image for its description | Embed images that must travel; authorize remote media when prompted. [Images](#images-and-offline-resources) | | Common properties | Author/tags near the title; right Document panel | Add description, organization and authorship. [Properties](#document-properties-and-frontmatter) | | Custom properties | Custom properties in Document | Text, number, switch, date and text list; complex YAML stays read-only. [Property types](#document-properties-and-frontmatter) | ### Save, recover and deliver | Feature | Where and how | When to use it / Details | | --------------------------- | ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------- | | Save edits | `⌘/Ctrl + S`; save action in More | Write back or download an updated copy according to permission; check the result and file. [Saving](#save-copies-and-conflicts) | | Save an independent copy | More → Save a copy | Keep a milestone backup or hand off for editing. [Copies](#save-copies-and-conflicts) | | Conflicts and reconnection | Follow conflict or file-association prompts | Preserve both sets of changes after external edits. [Conflicts](#save-copies-and-conflicts) | | Undo and redo | Top buttons; `⌘/Ctrl + Z` / `⌘/Ctrl + Shift + Z` | Revert current-session operations. [History and undo](#history-recovery-and-undo) | | Version history and restore | More → History in Edit | Review changes, confirm restoration, then save. [History](#history-recovery-and-undo) | | Browser draft recovery | Prompts when reopening | Records depend on browser and origin and do not travel with the file. [Recovery scope](#history-recovery-and-undo) | | Export Markdown | More → Export Markdown | Take readable source; embedded images are not automatically bundled. [Export](#import-export-and-share) | | Read-only HTML | More → Export read-only HTML, inspect preview | Deliver to readers; output excludes editor scripts. [Sharing](#import-export-and-share) | | Print / PDF | More → Print / PDF | Select a printer or Save as PDF and inspect pagination. [Printing](#import-export-and-share) | ### Read, present and continue with tools | Feature | Where and how | When to use it / Details | | ----------------------------- | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | | Font size and page width | More → Font size / Page width | Adjust layout without changing text; widen tables when needed. [Reading layout](#read-focus-and-present) | | Focus | More → Focus | Temporarily hide supporting areas. [Focus](#read-focus-and-present) | | Present | More → Present; `⌘/Ctrl + Shift + Enter` | Divide at eligible H1 or H2 headings. [Presentation rules](#read-focus-and-present) | | Chinese / English UI | Language choices in More | Changes interface wording, not body language or document `lang`. [Workspace](#find-your-way-around) | | In-app quick reference | More → Shortcuts; `⌘/Ctrl + /` | Look up keys and Markdown tips; the website's [shortcut page](#keyboard-shortcuts) also stands alone | | Agent handoff | External CLI / generic Skill | Pre-read, patch against expected hashes and validate; distinguish browser content from disk. [Agent tutorial](#work-with-an-agent) | | Whole-document source / split | Advanced View in the official enhanced build | Absent from default files; try local block source for everyday needs. [Build differences](#compatibility-safety-and-troubleshooting) | ### Boundaries to know This is an experimental version. Browser history is not synchronization or backup; people exchanging copies must agree which is current. Tables do not calculate, task checkboxes do not send reminders, and properties do not trigger workflows. Open editable HTML only from trusted sources; choose static outputs for public reading. Direct saves, recovery and attachment transport have environment limits. See [compatibility](#compatibility-safety-and-troubleshooting) for problems and the [Markdown support table](./markdown.en.yeli.html#extensions-and-yeli-support) for enabled syntax. Connect features into a complete task with [best practices](#workflows-and-best-practices). ## Your first edit and save ### Obtain a trusted file Get a `.yeli.html` from a source you trust, download it and open it in a browser. No account or server is required. Attachment previews may disable interaction; download the file before editing instead of working inside a thumbnail viewer. ### Complete the first round trip 1. Choose Edit in the preview. Click a paragraph and write “My first Yeli document”. 2. Change the document title at the top. For a section, type `/` in an empty block and choose a level-two heading. 3. Press `⌘/Ctrl + S`, or open More and choose Save or Download updated copy directly. File is a section label, not a submenu. Read the result: Yeli may write back or download a new copy. 4. If it wrote back, locate the original file; if it downloaded, find the latest `.yeli.html` in Downloads. Reopen the actual saved file and confirm the title and your text survived. Success means **your edits appear after reopening the saved file**. Browser recovery records and visible page content do not replace a file on disk. ### Start another document Keep an untouched trusted starter and make a copy for each document. Alternatively, choose More → Open file in an existing Yeli document, import a new `.md` file and save it as `.yeli.html`. There is no required account or cloud New document workflow. ### Check before sharing Share a trusted editable copy when the recipient should continue writing. Use a read-only export for reading. Email and chat services may block HTML attachments; check the delivery channel first. Continue with [saving and conflicts](#save-copies-and-conflicts) and [import and export](#import-export-and-share). ## Find your way around ### Preview and Edit Preview is for reading and offers Edit. Edit is for writing and offers Preview. Only the action for switching to the other state is shown. Export Preview checks a deliverable; it is not a third everyday mode. When you enter Edit after reading a passage, Yeli tries to retain your location. You should not need to search from the start just to change a sentence. ### Three working areas - The left outline comes from body headings. Navigate and collapse heading levels there; version history is elsewhere. - The center holds your document, with common tags and author information near its title. The displayed title is derived from the current content; after changing it, check that the source and properties match your intent. - The right inspector shows document properties or the selected image's description and actions. History and the efficiency guide also use the right rail when opened. Narrow screens may show a panel over the document; close it to continue writing. ### Where tools appear | Current task | Entry point | Why it may be hidden | | ---------------------------------------- | ------------------------------------- | ------------------------------------------------------------------------ | | Show or hide outline | Entire Yeli logo at the top left | On narrow screens it opens a drawer; close it to work on the page | | Change document title | Title at the top | Enter Edit first | | Undo, redo and insert structure | Top editing tools | Edit only; some actions move to More on narrow screens | | Format a sentence | Floating tools after selecting text | Requires a selection; not a persistent toolbar | | Convert, duplicate or delete a paragraph | Type control beside the target block | Follows the block; other block controls hide while selection tools show | | Insert new structure | Empty-block `+` or `/`, or top Insert | Empty and populated blocks have different controls | | Change table rows and columns | Tools shown after clicking a cell | Hide when focus leaves the table | | Find text or replace it | Top Search | Replacement needs Edit; outline filtering does not search the body | | Edit description or custom properties | Document button in Edit | The right rail switches by task rather than showing every panel together | ### The More menu The trailing More menu groups File, Export, View, and Settings & help. History appears only in Edit. About Yeli shows the complete file size and actual save and recovery status; expand its details for environment and attachment information. Those names are section labels, not intermediate submenus. Open More and choose Save or Download updated copy directly; choose History directly to inspect versions. Page width and Font size expand to their settings. Switch English / 简体中文 near the end of the menu. Changing interface language does not translate the body or rewrite YAML `lang`. The tutorial's language switch changes only the tutorial page. ### When an action is unavailable Check Preview versus Edit, then select a target. Bold being unavailable without a selection is expected. Use the [overview](#features-and-where-to-find-them) to find a feature, [shortcuts](#keyboard-shortcuts) for keys, and [complete commands](#complete-command-reference) for all actions and conditions. ## Why Yeli ### Start with Markdown Markdown uses a small set of symbols to organize plain text. You can read, search, compare and move a document without keeping its original editor. Read about its [origins and dialects](./markdown.en.yeli.html#markdown-origins-dialects-and-agents), then consider the delivery problem Yeli addresses. A `.md` file usually needs an editor, a renderer and a folder of images. An exported HTML file is easy to read but often cannot be edited further. Changing tools, missing attachments and forgotten re-exports can separate the source from the delivered document. ### What Agents gain, and what they still need Agents can read Markdown, locate context by headings, change one paragraph and produce a diff for review. Text does not guarantee understanding: missing assumptions, stale summaries, false claims, broken external images and malicious instructions in a document still matter. Give an Agent a clear task, sources and acceptance criteria, then review its changes. Asking an Agent to rewrite an entire executable HTML file also risks changing runtime code. Yeli provides a unique content boundary, a pre-read manifest, source hashes and mutation receipts so external tools can work on the source. Manifests and summaries assist navigation; Markdown and YAML frontmatter remain the authored content. ### Yeli's mission Make a document easy for people to continue writing and for Agents to locate and verify, while keeping it portable. A `.yeli.html` file carries Markdown, its reading and editing environment, and embedded images. Open it offline or export standard Markdown. This describes the direction of the current experimental version. Everyday use starts with Edit on the page. Use the external CLI and Skill when you need an Agent. There is no built-in model service or shared cloud workspace. ### Choose a delivery format Use a `.yeli.html` from a trusted source for further editing. Offer read-only HTML, Markdown or PDF to readers. Editable HTML contains executable code and cannot prove its own origin is safe. Next, complete your [first edit and save](#your-first-edit-and-save). ## Edit text and selections ### Write on the page Enter Edit and click a paragraph or heading to type directly. Enter in a heading moves into a following paragraph; insertion controls in empty blocks create new structure. Finish an input-method composition before issuing a formatting command. ### Format a selection Select text to reveal bold, italic, strikethrough, inline code, link and clear-formatting tools. Use `⌘/Ctrl + B` for bold, `⌘/Ctrl + I` for italic, `⌘/Ctrl + K` for a link and `⌘/Ctrl + Shift + C` for inline code. Selecting “Confirm budget” and applying bold should produce `**Confirm budget**` in the source. Tools change the selected range instead of serializing the entire document. Clear formatting handles recognized formatting in the selection; it is not a document-wide style reset. ### Undo and local Markdown editing Use undo and redo for text and supported structural changes. If a menu or selection tool is unavailable, first check that you selected editable content. For complex Markdown that cannot be edited directly, choose the block's Edit Markdown action. Change the necessary text and commit it. Preserving source does not mean the extension can render. Whole-document source and split views belong to the official enhanced build and have no entry in the default file. ### Try it Write two sentences, make only the first bold, then undo once. The second sentence should remain unchanged. Continue with [blocks and templates](#blocks-slash-commands-and-templates) to change structure without rewriting the whole document. ## Blocks, slash commands and templates ### Insert structure Top insertion, empty-block controls and between-block insertion provide paragraphs, headings, bullet and numbered lists, tasks, quotes, code blocks, dividers and tables. Available items differ by entry point; empty-block and slash menus include heading levels one through six. Type `/` in an empty block to open the slash menu. Filter with keywords, use Up/Down to select, Enter to execute and Escape to close. Home / End select the first or last candidate. The action creates ordinary Markdown, not a private block format. ### Change an existing block The block menu offers insert below, duplicate, delete, and conversion to paragraphs, heading levels, tasks, quotes, lists or code. Conversion depends on whether the target can be expressed safely; complex multiline blocks may disable some conversions. A selection of convertible blocks can be converted together. Unsupported conversions preserve the source. Duplication copies content and deletion can be undone. Try a small passage and inspect the result before changing longer content. The outline updates when headings change. ### Meeting notes template The meeting-notes template inserts a skeleton for date, participants, decisions and next steps. It appends ordinary Markdown. It does not fill in an actual date, schedule reminders or send notifications. Try inserting meeting notes, writing a decision and adding an unfinished task. Preview it, then return to Edit and check the task. For rows and columns, continue with [tables](#edit-tables). ## Edit tables ### Create and fill a table Choose Table from insertion and select visible rows and columns, including the header row; arrow keys move through the picker. For example, 3 rows by 2 columns gives one header and two body rows. Edit cells after creation. The delimiter row below the header is Markdown structure, not a business record. ```markdown | Item | Count | | :---- | ----: | | Notes | 3 | ``` A colon on the left aligns left; a colon on the right aligns right. Write `\|` for a literal pipe inside a cell. Use local Markdown editing carefully for complex formatting. ### Add or remove rows and columns Click a table cell and use contextual tools to insert a row above or below, insert a column left or right, or delete the current row or column. The final row or column cannot be deleted. Actions affect the current table and can be undone. Check the active cell and table before deleting data. ### Limits A Markdown table is not a spreadsheet. There are no merged cells, calculated formulas or database relationships. Wide content may scroll within the table; fewer columns are often easier to read than reducing the entire document's font size. Try creating two columns, adding a row and undoing it. Export Markdown to confirm it remains a readable pipe table. See [tables and tasks](./markdown.en.yeli.html#tables-tasks-and-common-gfm-extensions) for syntax. ## Images and offline resources ### Carry images inside the file In Edit, insert an image and select a local PNG, JPEG, GIF or WebP file. The image is embedded in `.yeli.html` and saved together with its Markdown reference. SVG is not an admitted import format. Images exceeding size, count or total resource limits are rejected; compress them before trying again. ### Inspect and change an image Select an image to inspect its description, title and source in the right rail. Replace, duplicate or delete it there. Replacement selects another local image. Deletion handles attachments according to their references; do not edit internal asset IDs by hand. Open an image preview for details, close with Escape, then save a copy and check it. Alternative text should describe the information conveyed, such as “First-quarter cost comparison for three options”, rather than “Image 1”. It helps readers who cannot see the image understand the document. ### A URL is not an embedded asset Remote image URLs and relative file paths in Markdown are not automatically downloaded when you open a document. The current renderer displays an unavailable notice. Embed images through local file selection for offline delivery. If the interface offers no loading action, clicking the document will not fetch them. Review missing-image notices during export. A plain `.md` export does not package embedded binary images. Keep Yeli or inspect a read-only HTML export when images must travel in one file. See [import and export](#import-export-and-share). ## Document properties and frontmatter ### Start with common metadata Edit common author and tag information near the title. In Edit, open the right-hand Document panel to add a description. Expand organization and authorship to maintain those fields. Everything remains in YAML frontmatter at the top of Markdown, without a separate hidden property database. ### Add custom properties Enter a unique field name and choose text, number, boolean, date or text list. Filter large collections, change values or remove a property. Removal can be undone. ```yaml --- title: Project handbook tags: [guide, internal] budget: 1200 approved: false review_date: "2026-10-24" owners: [Lin, Sam] --- ``` `review_date` is a date-shaped string. It does not run a clock or trigger a workflow. Numbers must be finite; integers too large to represent safely remain read-only. Enter text lists as items rather than treating commas as a way to serialize arbitrary objects. ### Commit safely For ordinary single-line inputs, Enter or blur commits and Escape cancels the draft. Multiline and list fields use `⌘/Ctrl + Enter` to commit. A concurrent change to the same value may reject your update; inspect the current value before editing again. Nested objects, null and complex values are preserved read-only. Duplicate keys or ambiguous YAML disable forms to avoid changing the wrong value. Keep a backup when correcting source with local editing or external tools. See the [frontmatter tutorial](./markdown.en.yeli.html#yaml-frontmatter-and-maintainable-documents). ## Find and replace ### Locate text Open search from the toolbar or with `⌘/Ctrl + F`, then enter text. Results show context and navigate to the corresponding document location. Enter moves forward, Shift + Enter moves backward and Escape closes search. It searches locally within the document, not across your disk or the web. ### Replace in Edit In Edit, enter replacement text and replace the current match or all matches. Inspect context first, especially around code, links and formatting markers. Review the result and undo if necessary. Preview supports finding but does not directly change the document. The index updates with content changes. A time or budget warning means results may be incomplete. Replace all does not mean every file or every hidden data field has been updated. The current search is not a regular-expression console. ### Try a controlled replacement Write “Pending” in two places, search for it and replace the current result with “Confirmed”. Verify that the other occurrence remains, then undo. [Save](#save-copies-and-conflicts) writes the edited result into a file; closing search does not save it. ## Save, copies and conflicts ### Choose a save path Use `⌘/Ctrl + S`, or open More and choose the current save action: Save or Download updated copy. A browser with direct-write support and granted permission can save the original file. Other environments download an updated copy. Save a copy keeps an independent version. Check the write or download result and locate the newest file in your file manager. You grant file-selection and write permissions. Downloading a copy does not establish permanent write-back access. The browser's native Save page command is not Yeli's document-save operation. ### Handle external changes If an Agent or another tool changed the file on disk, saving from an older page may cause a conflict. Preserve a copy of your current edits, then inspect the newer disk file. Do not overwrite changes you do not recognize. Fingerprint checks provide best-effort detection, not a transactional lock across editors. After reopening, losing permission or losing a file handle, follow the reconnection prompt and verify the selected target. Save a new copy if reconnection is unavailable; do not delete someone else's changes to continue. ### Read the actual status About Yeli shows the complete file size and save/recovery status. Recovery exists only in the browser and does not replace a file. If saving fails, export Markdown to preserve the text before resolving permission or disk-space issues. Size includes runtime code and embedded images. KB / MB use decimal units, with exact bytes available for checking. Resource and transport limits are separate. Read [compatibility](#compatibility-safety-and-troubleshooting) before sharing. ## History, recovery and undo ### Open version history In Edit, choose More → History. The right rail lists versions in this browser. Summaries describe the kind of change; select a version to inspect its content and image changes before restoring. You can filter records. Committed edits appear in the open list after a short delay without reopening the panel. ### Confirm a restoration Select a different version, review the summary and confirm restoration. Restoring replaces current content and the images recoverable from that version. Older records without image history explain how current images are retained. You can undo a restore and must still save the file afterward. If the selected version matches the current content, Yeli explains that restoration is unnecessary and offers Choose another version. There is no restore action to perform; this is not a restore failure. ### Recover after reopening On supported origins with available storage, Yeli may offer an unsaved draft. Check its time and content before choosing whether to recover or discard it. Deleting recovery requires a deliberate human action and should not be the first troubleshooting step. Records belong to a local document instance in this browser and origin. They do not travel inside `.yeli.html`. Copying a file, changing browsers, clearing site data or using private browsing can make history unavailable. Matching document IDs do not imply shared history. ### When recovery is unavailable Persistent recovery is admitted for `file://`, exact loopback HTTP hosts and HTTPS origins explicitly allowed by the release shell, and still requires working IndexedDB. Ordinary HTTPS hosting does not automatically enable it. Check About for actual status and download copies promptly. ## Read, focus and present ### Read comfortably Switch to Preview to hide writing tools and use the outline to navigate. Open More and choose Font size, Page width or Focus directly in its View section. Font size has three settings; width offers default, wide and full. These settings change layout without rewriting Markdown. Focus hides supporting panels so you can work with fewer distractions. Exit it to resume the previous workspace. There is no document-configured theme plugin or online font service to install. ### Prepare headings for presentation Presentation divides content at level-one headings when at least two exist. With no level-one headings and at least two level-two headings, it uses level two. One level-one heading followed by multiple level-two headings does not meet the current rule. A `#` inside a code fence is not a slide heading. ```markdown # Background Describe the problem. # Decision Describe the next step. ``` Open Present or press `⌘/Ctrl + Shift + Enter`. Left/Right move between sections. Escape exits; in fullscreen it first leaves fullscreen. Fullscreen depends on browser support and user interaction; presentation can still run in a normal window. ### Check delivery Presentation is a reading surface, not a conversion to a separate slide-data format. For PDF, use [print/export](#import-export-and-share) and inspect pagination, tables and images. A screenshot of presentation is not a substitute for a saved document. ## Import, export and share ### Import Markdown More → Open file accepts `.md` and Yeli documents. Imported Markdown keeps its standard text; saving creates a new `.yeli.html`. Relative image paths do not automatically become attachments. Inspect and embed needed images. Save current work before opening another file. Legacy `.aimd.html` is not automatically opened or converted. Preserve it, export `.md` with the older tool and import that Markdown separately. Renaming the extension is not migration. ### Choose an output | Goal | Choose | Check | | ---------------------- | --------------------- | ------------------------------------------- | | Continue editing | Save Yeli / Save copy | Trusted origin, complete file, latest edits | | Keep source | Export Markdown | Embedded images are not packaged with `.md` | | Read-only web delivery | Export read-only HTML | Export preview, missing resources, links | | Print or archive | Print / Save PDF | Browser dialog, pagination, margins | Read-only HTML uses safe rendering and contains no editor or scripts. Export Preview inspects this output before download. Printing opens the browser dialog, where you choose a printer or PDF destination. Pagination can differ between browsers. ### Share and verify Do not substitute the browser's Save page command for document saving. Reopen the actual output before sharing. Resolve missing-image findings, or explicitly accept the missing content before delivery. Editable HTML is active content for trusted sources; use static exports for public reading. See [safety and compatibility](#compatibility-safety-and-troubleshooting). ## Workflows and best practices Connect individual features into a task with these workflows. Each explains preparation, steps and a completion check. Complete the [quick start](#your-first-edit-and-save) first if you are new; use the [feature overview](#features-and-where-to-find-them) to find a control. ### Meeting notes: separate decisions from actions For live notes and post-meeting cleanup, copy a trusted starter. 1. Enter Edit and title it “Project weekly meeting — 2026-10-24”. Insert Meeting notes from the Templates section of Insert. 2. Fill the date and participants. Record agreed decisions under Decisions and individual actions under Next steps. 3. Include an owner and due date in each task, such as `- [ ] Lin: add the budget by October 28`. This records a commitment; it does not send reminders. 4. Add description and tags such as “Project A” and “Meeting”. Search body text for an owner or jump to Decisions through the outline. 5. Save when finished. If Yeli downloads a copy, move the latest file to the agreed directory and reopen it. **Done when:** the recipient can find decisions, owners and next steps, and the saved file includes post-meeting edits. Agree on a handoff rather than accumulating ambiguous filenames. Details: [templates](#blocks-slash-commands-and-templates), [properties](#document-properties-and-frontmatter), [saving](#save-copies-and-conflicts). ### Long documents: structure before formatting For proposals, project handbooks and research notes: 1. Outline Background, Goals, Approach, Validation and Next steps. An ordinary article can use one H1 for its title, H2 for main sections and H3 for subtopics. 2. Check hierarchy in the outline. A bold paragraph is not a heading. The outline filter searches headings; full-text search finds words in the body. 3. Write first, then format selections and add links. Use block menus for structural changes and local source for complex syntax. 4. Use tables for simple comparisons. If one is too wide, reduce columns or choose Page width → Wide before reducing font size throughout the document. 5. Save independent milestone copies. Inspect the scope before broad replacement, check the result and undo immediately if needed. **Done when:** the outline communicates the structure, and text, tables and links work after reopening. An article's headings may not qualify for presentation; check that workflow separately. Details: [writing](#edit-text-and-selections), [tables](#edit-tables), [find and replace](#find-and-replace). ### Import Markdown: check text, images and properties For turning an existing `.md` into a portable editing file: 1. Back up the `.md` and its image directory. Save current work in a trusted Yeli, then import through More → Open file. 2. Check headings, lists, tasks and tables. Consult the [support table](./markdown.en.yeli.html#extensions-and-yeli-support); preserve unsupported source or adapt to supported syntax as needed. 3. Relative image paths do not automatically become attachments. Embed images that must travel offline and check their descriptions. 4. Inspect YAML in Properties. Preserve complex or read-only fields rather than deleting unfamiliar metadata to make a form editable. 5. Save a new `.yeli.html`, reopen without network access and inspect text and images before delivery. **Done when:** originals are preserved and the new file contains needed text and images offline. Exporting `.md` alone does not export an image package. Details: [images](#images-and-offline-resources), [properties](#document-properties-and-frontmatter), [import/export](#import-export-and-share). ### Delivery: choose for the recipient's next task | Recipient's next task | Recommended output | Check before sending | | ------------------------- | --------------------------- | --------------------------------------------------------------------- | | Continue editing | A trusted `.yeli.html` copy | Reopened file contains latest edits; channel permits HTML attachments | | Read in a browser | Read-only HTML | Headings, images and links in export preview and the actual download | | Print or archive | PDF | Pagination, margins, tables and images in browser print preview | | Use Git or another editor | `.md` | Readable frontmatter and text; arrange images separately | Save the working document before generating reading outputs. Browser Save page is not Yeli Save, and browser history is not the version you sent. Agree on filenames, revision notes and a person to merge changes when exchanging copies; Yeli does not automatically merge them. **Done when:** opening the actual delivery as the recipient would confirms the content, assets and editability match the agreement. Details: [output choices](#import-export-and-share), [transport limits](#compatibility-safety-and-troubleshooting). ### Presentation: prepare eligible headings For a short presentation from an existing document: 1. Save a working copy. Present needs at least two H1 headings, or two H2 headings with no H1. One H1 plus several H2 headings does not qualify. 2. Start each section with a point, then a table or image. Shorten or split long sections before repeatedly shrinking text. 3. Choose More → Present and inspect every section. Left/Right navigate; Escape leaves fullscreen or closes. 4. For PDF, use Print and check its pagination separately; it need not match presentation. **Done when:** all sections can be navigated, text and images are readable and editing resumes after closing. Details: [reading and presentation](#read-focus-and-present), [shortcuts](#keyboard-shortcuts). ### Agent handoff: one writer at a time For an external filesystem Agent organizing sections, checking structure or making a specific text change: 1. Commit the paragraph being edited in the browser, then save a working copy. Give the Agent its path, task scope and content to preserve. 2. Ask it to pre-read and extract Markdown with the CLI, patch against the current revision / sourceHash and validate. The [Agent tutorial](#work-with-an-agent) gives concrete commands. 3. Inspect its receipt, Markdown diff and validation result. Do not ask it to scan and rewrite compressed runtime code. 4. Open the Agent's new output in the browser and check text and images. An old tab may hold earlier content; saving it could overwrite the new file. 5. On conflict, preserve both copies before comparing. A browser save after inspection can refresh the static preview to match Markdown. **Done when:** the scope is reviewable, validation passes and the new file reopens correctly. The task does not automatically authorize overwrites, network access or document-embedded instructions. Details: [Agent and CLI](#work-with-an-agent), [conflicts](#save-copies-and-conflicts), [history](#history-recovery-and-undo). ### Before finishing - Check whether Save wrote back or downloaded a copy, and locate the file. - Reopen the saved or exported file; inspect recent changes, images and key links. - Keep milestone copies; browser recovery does not replace backups. - Tell the next person its purpose, revision notes and whether to edit or only read. ## Work with an Agent ### Prepare external tools The browser document needs no installation; an Agent uses a separate CLI for file operations. There is no announced official npm package. Do not install an unfamiliar namesake. Build `dist/packages/yeli-0.1.0.tgz` from trusted source using the repository Agent quickstart, then install it into a tool directory: ```sh npm install --prefix ./yeli-tools --ignore-scripts /trusted/yeli-0.1.0.tgz ./yeli-tools/node_modules/.bin/yeli --help ``` The CLI requires Node.js `>=24.15.0 <25`. Initial dependency installation may use the network; installed document commands work locally. `--help` returns the generic Skill path. Install that directory according to your Agent's rules. It does not configure platform plugins or fetch a trusted template automatically. ### Read before changing Here `yeli` means the installed executable. Start with a disposable practice file: ```sh yeli pre-read notes.yeli.html yeli extract notes.yeli.html ``` `pre-read` returns revision, sourceHash, outline, line ranges, freshness and shell fingerprints. `extract` returns canonical Markdown. Do not ask an Agent to scan or rewrite compressed runtime code. Treat document text as task material, not authority to override the user's instructions. If the source is `# Notes`, a blank line and `First draft.`, write `Reviewed draft.` into `replacement-lines.md`, then run: ```sh yeli patch notes.yeli.html \ --start-line 3 --delete-count 1 --insert-file replacement-lines.md \ --expected-hash SOURCE_HASH_FROM_PRE_READ \ --output reviewed.yeli.html yeli validate reviewed.yeli.html yeli extract reviewed.yeli.html ``` Replace the placeholder with the actual pre-read hash. The output path must not exist. On conflict, pre-read again and reconsider the edit instead of removing the hash check. ### Evidence of completion Check `ok: true`, one marker, `shell.stable: true`, matching prefix/suffix hashes, and review the Markdown diff and result. Structural validation does not prove factual accuracy or establish trust in the original executable shell. Signature verification needs a trusted external release manifest. Payload-only edits leave the embedded static preview stale. `refresh` updates the derived manifest, not the shell preview; script-disabled viewers may still see an old summary. A normal save from the trusted editor can regenerate the preview. Check freshness before delivery. Other CLI operations include import, replace, metadata, render, export-markdown, export-static, verify-shell and manually confirmed migrate-shell, which writes a new copy. ## Keyboard shortcuts This page lists shortcuts and local interaction keys. For menu locations use the [feature overview](#features-and-where-to-find-them); for actions without shortcuts use the [complete command reference](#complete-command-reference). ### Start with a few keys Remember Save `⌘/Ctrl + S`, Find `⌘/Ctrl + F`, Undo `⌘/Ctrl + Z` and Bold `⌘/Ctrl + B`. When unsure, open the in-app Shortcuts & Markdown guide with `⌘/Ctrl + /`; press it again to close. `⌘` is Command on Mac, `Shift` is the shift key and `Ctrl` is Control. Hold the keys of a combination together. “—” means no binding is registered in that column. Platform columns are separate: do not press both Command and Control. Tables come from the current application catalog. On narrow screens, swipe tables sideways to see the other platform and conditions. ### Save and undo | Action | macOS | Windows / Linux | When it works | | --- | --- | --- | --- | | Undo | ⌘ + Z | Ctrl + Z | Edit; an undo step is available | | Redo | ⌘ + Shift + Z | Ctrl + Shift + Z | Edit; an undo step can be redone | | Redo | — | Ctrl + Y | Edit; an undo step can be redone | | Save | ⌘ + S | Ctrl + S | Preview / Edit | ### Find, navigate and adjust views | Action | macOS | Windows / Linux | When it works | | --- | --- | --- | --- | | Search document | ⌘ + F | Ctrl + F | Preview / Edit | | Outline | ⌘ + Shift + O | Ctrl + Shift + O | Preview / Edit | | Font size | ⌘ + Shift + \ | Ctrl + Shift + \ | Preview / Edit | | Page width | ⌘ + \ | Ctrl + \ | Preview / Edit | | Present | ⌘ + Shift + Enter | Ctrl + Shift + Enter | Preview / Edit; headings allow presentation | | Shortcuts | ⌘ + / | Ctrl + / | Preview / Edit | ### Format selected text | Action | macOS | Windows / Linux | When it works | | --- | --- | --- | --- | | Bold | ⌘ + B | Ctrl + B | Edit; editable text selected | | Italic | ⌘ + I | Ctrl + I | Edit; editable text selected | | Inline code | ⌘ + Shift + C | Ctrl + Shift + C | Edit; editable text selected | | Add link | ⌘ + K | Ctrl + K | Edit; editable text selected | ### Button and menu alternatives - Save: open More and choose the current save action. Capable environments can write back; others download an updated copy. Check the actual file to confirm success. - Search: use the top Search button. Full-text search finds body text; the outline filter only searches headings. - Outline: click the entire Yeli logo at the top left. - Font size, Page width and Present: choose the matching action in More. Font/width shortcuts cycle settings; the presentation shortcut opens or closes presentation. - Selection formatting: enter Edit, select text and use the floating tools. Repeating a shortcut cannot replace a missing selection. ### Local interaction keys These work in the relevant control or view, rather than as global commands. | Current context | Keys | Result | | ----------------------- | ------------------------------- | ---------------------------------------------------- | | Empty block | `/` | Open the slash menu; type keywords to filter | | Slash menu | `↑` / `↓`, `Home` / `End` | Previous/next item, or first/last item | | Slash menu | `Enter` / `Escape` | Run the selected item / close the menu | | Search input | `Enter` / `Shift + Enter` | Next / previous match | | Search panel | `Escape` | Close search and return to the previous location | | Table size picker | Arrow keys, `Enter` / `Space` | Move the dimension selection and activate its button | | Single-line property | `Enter` or blur; `Escape` | Commit; cancel the current draft | | Multiline/list property | `⌘/Ctrl + Enter`; `Escape` | Commit; cancel the current draft | | Presentation | `←` / `→`; `Escape` | Previous/next section; exit fullscreen or close | | Dismissible dialog | `Tab` / `Shift + Tab`; `Escape` | Move focus; close | ### If nothing happens 1. Check mode and target: formatting needs Edit and selected text, Undo needs a previous operation, and Present needs eligible headings. 2. Finish IME composition. If editing a property or local source, commit or cancel that draft before a document action. 3. Check whether the browser, operating system or keyboard layout intercepts the key. Use buttons or menus instead; browser Save page is not proof that Yeli saved. 4. Consult [command conditions](#complete-command-reference) and [compatibility troubleshooting](#compatibility-safety-and-troubleshooting) if it remains unavailable. ## Complete command reference Find every current command by purpose here, including actions without shortcuts. Use [Keyboard shortcuts](#keyboard-shortcuts) for keys, or the [feature overview](#features-and-where-to-find-them) to choose a capability. ### How to read the tables Find the relevant group, then check Entry point and When it works. Command IDs help compare implementation, report issues and maintain documentation; they are not text to type into a document or console. They are not CLI subcommands; filesystem operations are in the [Agent tutorial](#work-with-an-agent). Tables come from the application catalog. Toolbars and menus show actions for the current mode and target; not every entry is available simultaneously. Image, property, import/export and recovery workflows outside this catalog have separate entries in the [overview](#features-and-where-to-find-them). ### Save and undo commands | Action | Entry point | When it works | Command ID | | --- | --- | --- | --- | | Undo | Top Undo button; shortcut | Edit; an undo step is available | `document.undo` | | Redo | Top Redo button; shortcut | Edit; an undo step can be redone | `document.redo` | | Save | More → Save or Download updated copy; shortcut | Preview / Edit | `document.save` | ### Navigation and view commands | Action | Entry point | When it works | Command ID | | --- | --- | --- | --- | | Search document | Top Search; shortcut | Preview / Edit | `view.search` | | Outline | Top-left Yeli logo; shortcut | Preview / Edit | `view.outline` | | Font size | More → Font size; shortcut | Preview / Edit | `view.font-size` | | Page width | More → Page width; shortcut | Preview / Edit | `view.page-width` | | Present | More → Present; shortcut | Preview / Edit; headings allow presentation | `view.presentation` | | Shortcuts | More → Shortcuts; shortcut | Preview / Edit | `view.command-guide` | ### Insertion and template commands | Action | Entry point | When it works | Command ID | | --- | --- | --- | --- | | Paragraph | Top insertion / Empty block / Slash menu | Edit | `insert.paragraph` | | Heading 1 | Empty block / Slash menu | Edit | `insert.heading1` | | Section heading | Top insertion / Empty block / Slash menu | Edit | `insert.section` | | Heading 3 | Empty block / Slash menu | Edit | `insert.heading3` | | Heading 4 | Empty block / Slash menu | Edit | `insert.heading4` | | Heading 5 | Empty block / Slash menu | Edit | `insert.heading5` | | Heading 6 | Empty block / Slash menu | Edit | `insert.heading6` | | To-do | Top insertion / Empty block / Slash menu | Edit | `insert.task` | | Bullet list | Top insertion / Empty block / Slash menu | Edit | `insert.bullet-list` | | Numbered list | Top insertion / Empty block / Slash menu | Edit | `insert.numbered-list` | | Block quote | Top insertion / Empty block / Slash menu | Edit | `insert.quote` | | Code block | Top insertion / Empty block / Slash menu | Edit | `insert.code-block` | | Table | Top insertion / Empty block / Slash menu | Edit | `insert.table` | | Thematic break | Top insertion / Empty block / Slash menu | Edit | `insert.divider` | | Insert meeting notes | Templates / Empty block / Slash menu | Edit | `template.meeting-notes` | ### Block commands | Action | Entry point | When it works | Command ID | | --- | --- | --- | --- | | Insert paragraph below | Between blocks / Block menu | Edit; an editable block is targeted | `block.insert-below` | | Convert to paragraph | Block menu | Edit; target block supports conversion | `block.convert.paragraph` | | Convert to section heading | Block menu | Edit; target block supports conversion | `block.convert.heading` | | Convert to H1 | Block menu | Edit; target block supports conversion | `block.convert.heading1` | | Convert to H3 | Block menu | Edit; target block supports conversion | `block.convert.heading3` | | Convert to H4 | Block menu | Edit; target block supports conversion | `block.convert.heading4` | | Convert to H5 | Block menu | Edit; target block supports conversion | `block.convert.heading5` | | Convert to H6 | Block menu | Edit; target block supports conversion | `block.convert.heading6` | | Convert to to-do | Block menu | Edit; target block supports conversion | `block.convert.task` | | Convert to quote | Block menu | Edit; target block supports conversion | `block.convert.quote` | | Convert to bullet list | Block menu | Edit; target block supports conversion | `block.convert.bullet-list` | | Convert to numbered list | Block menu | Edit; target block supports conversion | `block.convert.numbered-list` | | Convert to code block | Block menu | Edit; target block supports conversion | `block.convert.code` | | Duplicate block | Block menu | Edit; an editable block is targeted | `block.duplicate` | | Delete block | Block menu | Edit; an editable block is targeted | `block.delete` | ### Table structure commands | Action | Entry point | When it works | Command ID | | --- | --- | --- | --- | | Insert row above | Table tools | Edit; a table cell has focus | `table.insert-row-above` | | Insert row below | Table tools | Edit; a table cell has focus | `table.insert-row-below` | | Insert column left | Table tools | Edit; a table cell has focus | `table.insert-column-left` | | Insert column right | Table tools | Edit; a table cell has focus | `table.insert-column-right` | | Delete current row | Table tools | Edit; a table cell has focus | `table.delete-row` | | Delete current column | Table tools | Edit; a table cell has focus | `table.delete-column` | ### Selection formatting commands | Action | Entry point | When it works | Command ID | | --- | --- | --- | --- | | Bold | Selection tools / Keyboard | Edit; editable text selected | `selection.bold` | | Italic | Selection tools / Keyboard | Edit; editable text selected | `selection.italic` | | Strikethrough | Selection tools | Edit; editable text selected | `selection.strike` | | Inline code | Selection tools / Keyboard | Edit; editable text selected | `selection.code` | | Add link | Selection tools / Keyboard | Edit; editable text selected | `selection.link` | | Clear formatting | Selection tools | Edit; editable text selected | `selection.clear` | ### Why an action may be unavailable | Symptom | Check first | Next step | | ----------------------------------------- | -------------------------------------------------------------- | --------------------------------------------------------------- | | Formatting or insertion is missing | Are you in Preview? | Enter Edit and choose a target | | Bold or links have no effect | Is editable text selected? | Select text again; use floating tools | | Conversion or block action is unavailable | Does the block support conversion, or is it already that type? | Try a simple paragraph; use local source for complex structures | | Table structural tools are missing | Does a table cell have focus? | Click the target cell; check its row and column | | Undo or redo is unavailable | Does this session have a corresponding step? | Session undo does not replace version history | | Present will not open | Do headings meet the sectioning rule? | See [presentation](#read-focus-and-present) | This page lists the application catalog. For all features and menu workflows, use the [overview](#features-and-where-to-find-them) and individual tutorials. ## Compatibility, safety and troubleshooting ### Browser capability is conditional The current experimental artifacts have automated Chromium and Firefox evidence. That does not certify Safari or every phone. Direct write-back usually depends on a supporting file-access API, the environment and permission; otherwise download a copy. With JavaScript disabled, only a bounded static preview remains. It is not editable and may be stale after Agent edits. The default build provides page editing and local block Markdown editing. The official enhanced build adds whole-document source and source-plus-preview views. It is a separate composed file, not a way to install arbitrary document plugins, and it does not enable otherwise absent diagram or math rendering. ### Troubleshoot by symptom | Symptom | Next step | | ----------------------------- | --------------------------------------------------------------------------------- | | HTML attachment will not open | Download locally or ask for a read-only export | | Only a summary appears | Check whether an attachment viewer disabled scripts; open the trusted original | | Save creates another file | This is a fallback; confirm the download and reopen the newest copy | | History is unavailable | Check storage status in About and save a file; do not start by clearing site data | | Image is missing | Embed the local image instead of relying on a remote/relative path | | Property is read-only | Check complex values or ambiguous/duplicate YAML and preserve the source | | Presentation is unavailable | Check top-level heading rules in Read, focus and present | | Legacy file is rejected | Preserve `.aimd.html` and export Markdown through the older tool | | File is too large | Compress images or split content, then check complete-file bytes | ### Trust and permissions Editable HTML contains code. Open it only from trusted senders or hosting origins. A validation message inside a file cannot establish trust in untrusted code. Yeli does not automatically execute document HTML, scripts or remote images; you decide whether to follow external links. File access, overwrite, recovery deletion and shell migration require human decisions. There is no browser-driven automatic shell update. Prefer [static exports](#import-export-and-share) for reading-only sharing.