DOCSEARCHbyAlgolia
Submit Docs

Leo Editor

website·Indexed 30 days ago

https://boltex.github.io/leojs

A scriptable literate programming outliner available as a browser-based port (Leo-Web) and LeoJS. It features an Emacs-like minibuffer, a unique system of clones for personal information management, and directives like @<file> and @path for external file management. The editor supports JavaScript and TypeScript scripting, a plugin system, and uses the Mulder/Ream update algorithm for file synchronization.

Tokens
57.7K
Snippets
216
Records
464
Agent score
73%

What's inside Leo

  1. Overview of Leo-Web

    Leo-Web is a lightweight, browser-based port of the Leo Editor, a scriptable literate programming environment and outliner. It allows users to work with Leo outlines, script using JavaScript or TypeScript, and access local files via the browser File System API without requiring a local installation.

  2. Overview of Leo file creation directives

    Leo uses directives in node headlines to create or import external files. The choice of directive determines whether sentinels are used, if the file is write-only, and how data is stored in the .leo file.
    DirectiveSentinels@others.leo DataWrite Only
    @asis❌❌✔️✔️
    @auto❌✔️❌❌
    @clean❌✔️✔️❌
    @edit❌❌❌❌
    @file✔️✔️❌❌
    @nosent❌✔️✔️✔️

  3. Overview of Leo's data structure evolution (vnodes and tnodes)

    Leo's internal data structures evolved through several major phases:

    • Pre-4.2: Every node had its own vnode, causing performance issues during clone operations.
    • 4.2: Introduced sharing subtrees via tnodes to optimize clones.
    • 4.4.3: The 'big reorg' made vnode and tnode classes independent of the rest of the application.
    • 4.7: Unified vnodes and tnodes. tnodes were eliminated, and vnodes now contain all data, utilizing iterators and positions to allow a single node to appear in multiple places in a tree traversal.

  4. Overview of LeoJS

    LeoJS is a JavaScript implementation of the Leo Editor, designed as an extension for Visual Studio Code and VSCodium. It provides an outline-based editing experience with a focus on scriptability in JavaScript and TypeScript, allowing users to access the outline structure via a JavaScript API.

  5. Overview of @<file> directives for external file management

    Leo uses directives in node headlines to create or import external files. The choice of directive determines how sentinels are handled, whether other nodes (@others) are included, and if the file is write-only.

    Comparison Table:

    DirectiveSentinels@others.leo DataWrite Only
    @asis❌❌✔️✔️
    @auto❌✔️❌❌
    @clean❌✔️✔️❌
    @edit❌❌❌❌
    @file✔️✔️❌❌
    @nosent❌✔️✔️✔️

  6. Overview of LeoJS for VSCode

    LeoJS is a JavaScript and TypeScript implementation of the Leo editor, delivered as an extension for VSCode. It replaces the traditional flat-file editing model with a hierarchical outline structure (Directed Acyclic Graphs), allowing developers to organize data, programs, and scripts as a tree. It can run in the VSCode desktop application or as a web extension within GitHub and Azure Repos.

  7. Navigate the LeoJS User Interface

    LeoJS organizes data into nodes consisting of a headline (visible in the outline pane) and body text (visible in the body pane). The UI is available in a standalone LeoJS View and mirrored in the Explorer View. Key components include:

    • Body Pane: A text editor that updates based on the selected node in the outline.
    • Detached Body Panes: Independent panels opened via the 'Open Aside' command.
    • Log Window: An output channel located at the bottom of the window for system logs.
    • Documents Panel: Manages open Leo documents (supported formats: .leo XML, .leojs JSON, and .db SQLite).
    • Undo Panel: A multi-tiered system separating structural outline changes from text changes. Users can right-click undo steps to revert to a specific state.
    • Buttons Panel: Displays reusable commands or scripts assigned to buttons.

  8. Understand the Mulder/Ream update algorithm for @clean and @shadow files

    The Mulder/Ream algorithm allows Leo to update internal trees (@clean or @shadow) when the corresponding external text file has been modified outside of Leo. The algorithm is language-agnostic, performs no parsing, and relies exclusively on difflib.SequenceMatcher to determine changes.

    The update process follows these steps:

    1. Recreate Old Version (No Sentinels): The @clean x outline is written to a string without sentinels.
    2. Recreate Old Version (With Sentinels): The @clean x outline is written as an @file node to generate 'old sentinels' lines.
    3. Diffing: difflib.SequenceMatcher creates diffs between the old version (without sentinels) and the new external version of the file. In the code, a represents the old lines and b represents the new lines.
    4. Propagate Changes: The algorithm uses the old sentinels, the a and b line sets, and the diffs to create 'new sentinels lines' via a three-way merge (implemented in x.propagate_changed_lines).
    5. Tree Replacement: The @clean tree is replaced with a new tree generated by reading these new sentinel lines using @file read logic.

    Key Constraint: The algorithm never inserts or deletes nodes; it only updates the content within existing nodes. Users must manually create new nodes for new lines or delete nodes that become empty.

  9. Understand the Mulder/Ream update algorithm for @clean and @shadow files

    The Mulder/Ream algorithm allows Leo to update its internal tree structure when an external file (created with @clean or @shadow) has been modified outside of Leo. The algorithm is language-agnostic, performs no parsing, and relies exclusively on Python's difflib to synchronize lines while preserving 'sentinels' (markers that define node boundaries).

    The update process follows these steps:

    1. Recreate Old Version: The @clean outline is written to a string without sentinels.
    2. Recreate Sentinels: The @clean outline is written to a string with sentinels (referred to as 'old sentinels lines').
    3. Diffing: difflib.SequenceMatcher identifies differences between the old version (without sentinels) and the new version of the file.
    4. Propagate Changes: The algorithm uses a three-way merge (implemented in x.propagate_changed_lines) to create 'new sentinels lines' by combining old sentinels, the diffs, and the new file content.
    5. Tree Replacement: The @clean tree is replaced by a new tree generated from these new sentinel lines using @file read logic.

    Key Constraints:

    • The algorithm never changes sentinels, inserts nodes, or deletes nodes.
    • Users are responsible for creating new nodes for added lines or deleting nodes that become empty.

  10. Access LeoJS help and documentation

    Use these minibuffer commands to find documentation and support:

    • help-for-command: Prompts for a command name and displays its docstring.
    • help: General introduction to the help system.
    • help-for-settings, help-for-keystroke, help-for-scripting, help-for-minibuffer: Opens specific topic discussions.
    • open-online-home: Opens the LeoJS home page.
    • open-users-guide: Opens the LeoJS Users Guide.

  12. Understand the Leo User Interface layout

    Leo organizes data into nodes consisting of a headline and body text. The UI is divided into three primary areas:

    • Outline Pane: Displays node headlines and their status icons. Selecting a headline updates the body pane.
    • Body Pane: A text editor that displays the body text of the currently selected node. The orientation of the outline-body splitter (horizontal or vertical) and the color theme can be toggled via the top-right hover menu.
    • Log Window: A multi-tabbed area containing the Find panel, Nav panel, Undo pane, and a UI panel for customizing the hover menu.