olai
Plugins

Plugins › Browser UI

Markdown documents: the page and the editor

1 min read · 16 notes, one tap away

On this page
  1. The page of a document
  2. Edit a document
  3. Headings and links
  4. What still works without this plugin

olai calls a .md file a document. The markdown plugin draws the page you read a document on, and is the editor you type one in.1

The page of a document

Top to bottom:

Part What it is
the heading the file’s path, in a monospaced face
Edit and Delete… drawn together, only for a file in the directory olai serves
the line at the top a chat about this document23
the properties one chip per key in the file’s frontmatter, the keys at its top4
Contents the document’s headings, open by default5
the body the document, rendered
Referenced by N things what points at this document6

A page says Loading… until olai has read the file.7

Edit a document

Clicking Edit replaces the body with a plain-text box named Edit <file>, holding the file as it is on disk, frontmatter included.

Control Key What happens
Save Cmd + Enter writes the file and leaves the editor
Cancel Escape throws the text away and leaves the editor

Cmd is the modifier on a Mac and Ctrl elsewhere.8 If the file changes on disk, olai refuses the save.9 olai keeps text you have not saved for that pane and that file.10

Clicking a heading, or a line of Contents, goes to an address like /notes/plan.md#slug.11 Alt and a click open the same destination in a pane on the right.12 A link to a file this directory does not serve says so.13 Pictures load as you reach them.14

What still works without this plugin

Switching markdown off takes away document pages and the read and write procedures.15 Switching off outlines or the files sidebar leaves this page and its editor able to save.16

What other plugins contribute
Location Takes
markdown.body one occupant, which draws a document’s body somewhere else. The journal’s day note uses it
markdown.properties one occupant, which replaces the plain frontmatter chips with a richer drawer. Outlines contributes it

markdown.editing is how another plugin opens a document it has just made. The journal (The journal: a calendar, day pages and an agenda) names it on a component of its own, so with markdown off the calendar, the agenda and the day page are whole and simply draw no day-note button. markdown.browser-state carries the open documents, their unsaved text, and this plugin’s own undo history.

Footnotes

  1. The markdown plugin claims .md files. What a document is, and how it is written, is in Documents, references and the kinds olai shows. ↩

  2. The line is this plugin’s own place on a document’s page, under the path and above the properties, and chat fills it (Talking to an agent from a row or a page). With a chat about this document it says how that chat stands, carries Chat about this page, and Open beside ›, which opens the conversation in the pane to the right. Without one it holds a box reading Ask about plan…, where Enter starts the chat and opens it beside.

    The pages of the kinds olai only shows, such as a .csv or a picture, draw no line, and nor does any page with chat switched off. ↩

  3. A chat about this document is kept in the file’s own frontmatter, under two keys. chat-agent-session says which conversation the document is having. chat-opens says whether opening that chat brings the document with it. olai refuses a write by an agent that changes or drops the tie, so you move either key by editing the file yourself. ↩

  4. A property’s value is drawn as a link when it names a web address, or a file, a row or a day that this olai can open. ↩

  5. The list of headings is drawn only when the document has more than one heading. ↩

  6. The referrers section is closed until you open it, and splits what it found across three rows: Sees this, Mentions this and Links to this. A row that links to this document from its title or its note opens that row’s page; a document whose prose links here opens that file. ↩

  7. An address naming no such file says Page not found, with the detail There is no document named notes/plan.md. ↩

  8. To make a document, use New document in the sidebar’s + menu (The file list in the sidebar). A document you have just made opens with its editor already open. ↩

  9. The editor says This file changed while you were editing. Your text is safe here, and Save won't overwrite the change. Save is refused, and an Overwrite anyway button appears beside it once you have read the refusal. ↩

  10. Text you have not saved survives switching tabs, resizing, layout changes, and a file that goes missing and comes back during the same visit. Closing the pane or navigating away throws it away, and switching the plugin off and on again does not bring it back. ↩

  11. A plain click records the heading in the address and scrolls to it once the page’s typefaces have loaded, so where you land is measured in the type you will actually read. ↩

  12. The pane that opens on the right includes a preview card. A link to a part of the text you are already in, such as a footnote inside an outline’s note, scrolls in place and leaves the address alone. ↩

  13. A link to a file this directory does not serve keeps its words, and gains a sentence saying it is dead in the name a screen reader reads out. A keyboard and a screen reader meet it that way too, not only a pointer. The sentence goes as soon as the file is served.

    A title the author wrote, [x](y "…"), is still rendered as the document’s own tooltip. Code spans, code fences and frontmatter never raise the warning, and a query or a fragment on an address is not part of the check. ↩

  14. The first picture is fetched at once, and the rest as you scroll near them. The same renderer draws outline notes and chat replies, so this holds for each rendered block rather than for each page. ↩

  15. Outline editing, the sidebar and open outline pages are untouched, and outline notes and chat messages keep rendering markdown text, which a renderer that is always loaded draws, not this plugin. Switching it back on reads the files as they are now, with its editor state reset, and an address you kept can draw its page again. ↩

  16. A document page and its editor stand without those plugins, because the directory supplies access to the file and the navigation plugin supplies the address. ↩