Every file olai serves is an outline, a markdown document, or a kind olai only shows. References and pins point at them.
References
A reference points from one place to another, and olai works out what points back.1 Three things count as a reference.2
| Written as | What it says |
|---|---|
see |
a free cross-reference between two rows |
@<id> in a title, a note or a document |
a mention, if some row has that id3 |
a […](…) link |
the row or file it names4 |
Documents
A .md file olai serves is a document.5 Its title is its first line, and you can link to any heading inside it.6 Its properties are the key: value lines in the frontmatter at the top.789 olai writes a document whole, never a part of it.1011 Relative pictures and links are looked for beside the file.1213
Pins
A pin is an ordinary row whose title is an address, such as /#herbs; the sidebar lists your pins (The sidebar, tabs and the palette).1415 Write the address bare, or as a markdown link to name the pin.1617 A pin promises the address, not that what it names still exists.1819
The kinds olai only shows
Every file olai serves is claimed by a plugin; a file nothing claims is not loaded.20 Four kinds are drawn and never written: a .html page, a .csv, a picture and a .pdf.21
Web pages in your directory
A .html file is a web page, and olai draws it on a page at /<path>.2223 A link in it to another file with a page opens that page in olai.2425 A .html file that will not open says so.2627
When a mention is a reference but is not drawn as a tag
A note is read as plain text, because the part of olai that finds references has no markdown parser in it. An @ only starts a mention where a word starts: at the start of the text, or after a space, (, [ or {. The browser, on the other hand, styles tags in rendered markdown, so the two can disagree.
| A reference | Drawn as a tag | |
|---|---|---|
`@herbs` — a code span holding only that |
no | no |
`see @herbs here` — a space inside the span |
yes | no |
a fenced or indented code block, @herbs after a newline |
yes | no |
[@herbs](…) — a link’s text |
yes | no |
*@herbs* / **@herbs** — emphasis around it |
no | yes |
So @herbs can be styled as a tag on one row’s page while that row is missing from the list of what refers to the herb bed, because a * does not start a word.
What a pin's title may say
| Title | Opens |
|---|---|
/#<id> |
the row, shown in its outline |
/zoom/#<id> |
the row’s own page |
/<path> |
a file: a .md, a .html or an outline |
/<path>#<slug> |
a heading inside a document |
/<path>#<id>, where the path is an outline |
the row, in its own file |
/d/<ISO>, /today, /agenda, /trash |
that day, today, the agenda, the Trash |
A title may also address a whole workspace. Write /s/, then the addresses of the pages you have open, one per pane, each percent-encoded and without its leading slash. An example is [Orchestrating](/s/%23abc/orchestrator%2Flanes.olai). olai saves the pages only, under a name you supply, with no ?w= pane widths and no ?f= focus.
Those two, and ?a= and ?t=, are accepted when read, and opening such a pin gives every pane the same width and puts the focus in the first one. One you write by hand is a pin too.
A pins file that spells a row’s own page as /#<id> has it rewritten to /zoom/#<id> the first time olai reads the file, including the row parts of workspace titles.
{"id":"p-herbs","ord":"a0","title":"/#herbs"}
{"id":"p-late","ord":"a1","title":"[What is late](/agenda?q=is%3Atodo)"}
Every kind olai claims, and the ones it only draws
| Kind | Suffixes | Its page |
|---|---|---|
| Olai | .olai |
the outline (The outline file format) |
| Markdown | .md |
the text, drawn as markdown |
| Hypertext | .html |
the sandboxed frame |
| CSV | .csv |
a table |
| Image | nine picture suffixes, .svg among them |
the picture |
.pdf |
the browser’s own viewer | |
| Vault plugins | .ts and .tsx, under plugins/ only |
the plugin’s own page (Ask an agent for a plugin of your own) |
A .csv
Read when you open it and drawn as a table, with the first row as the header, which is a convention and is marked nowhere in the file. The header cells are marked as headers in the markup (scope="col"), and no column is treated as a row header (CSV files).
olai reads only part of a large file, and says so: “Showing the first 500 rows.” It stops at five hundred rows, a hundred columns, and two thousand characters in one cell. Nothing in olai writes a .csv back.
A picture
An <img> pointed at /media/<its path>, drawn at its own size, up to the width of the column. An .svg is drawn in that same element, which will not run it, and the /media/ route answers an SVG with default-src 'none'; sandbox, so reaching that URL another way gives an inert document. Markdown may name a picture, but not an .svg.
A .pdf
The browser’s own viewer, embedded as an <object> pointed at /media/<its path>. A browser that will not draw a PDF gets a sentence and the file itself, and the browser’s own separate viewer process is what keeps it apart from olai.
What a web page in your directory may load, and the policy it carries
The file is served at /media/<its path>, so a relative address inside it means the file next to it on disk.
| In the file | Loads |
|---|---|
<img src="art/shot.png"> in notes/report.html |
notes/art/shot.png |
<a href="other.html"> |
the page of the file next door |
a remote host, a data: URI, a path above the directory |
nothing |
The route answers with the page, its pictures, its stylesheet, its script and its font, and nothing else, behind the same check against climbing out of the directory that markdown’s pictures go through. A .md, an .olai, a .json and a .csv are not on that list, because they have pages of their own.
The response carries a content policy: sandbox allow-scripts; default-src <host>/media/; script-src <host>/media/ 'unsafe-inline' 'unsafe-eval'; style-src <host>/media/ 'unsafe-inline'; frame-src 'none'; form-action 'none'; base-uri 'none'. Every directive that allows a fetch names this directory on the host you asked for, and base-uri 'none' refuses the file’s own <base href>.
A script can navigate its own frame, and no directive covers that, so a page can tell somebody else’s server what it is by leaving, once. Nothing it fetches leaves this directory, and a nested frame or a form post is refused.
The sandbox survives a navigation and the policy does not, so olai brings the frame back. A navigation to a file of this directory is kept; anything else is replaced by the file again, a limited number of times, and after that by an empty frame.
Footnotes
-
One index answers the question “what points at this”, so the row’s backlinks, the document page’s list of referrers, and
referencedByin the answer fromoutlines_readare all one list. A source that refers twice is one referrer listed with two ways of referring, out ofsee,mentionandlink. A reference to a mirror counts as a reference to the row it shows, and nothing refers to itself. ↩ -
Three things are not references. A
mirrorsays “draw this row here too”, and where else a row is drawn is inmirrorsin the answer fromoutlines_read. Anafteror ablocksis the ordering between tasks (Marks, days and repeating). A row in an_olai/Trash.olaiis drawn on the Trash page and nowhere else. ↩ -
@also starts a tag, so@herbsis a tag whether or not anything has the idherbs. Whether a row has that id is asked when the reference is read, so a row created today turns every@its-idalready written into a reference to it. A#herbsis never a reference. ↩ -
A link points at an address:
[x](#id)names the row with that id, and[x](doc.md),[x](doc.md#heading)and[x](art/handle.png)name the file. A picture with no label,, is still a link, so a picture’s page lists the documents that show it. A link to a heading counts as a link to the whole document. ↩ -
For each served file olai keeps its path, its title, the addresses it points at and the tags its text holds, all worked out from the file. Notes link to documents, and properties declared
docname them.A document’s text is stored exactly as written, drawn as markdown and never checked, so a
.mdfile can never make the directory invalid. Every file is loaded at startup; the text of a document is sent when a reader asks for it, at a named revision. ↩ -
A document is called by its first line that is not empty, with the
#marks taken off, and by its filename when the body has no such line. You can link to any heading by its slug, taken in the order the headings appear, which is whatREADME.md#installnames, so rewording a heading breaks that address. What the document points at is wherever its[…](…)links land, read by the same rule a note is read by. ↩ -
Frontmatter is a
---line at the very top of the file, closed by another---, holdingkey: valuelines. It answersprop:in a search, in the same set of names a row’s own properties use (Search), soprop:agent=claude-opusfinds both documents and rows. A---that is never closed is just a horizontal rule, and a note under a row has no frontmatter at all. ↩ -
A frontmatter value is text, or a list of text:
[a, b]and a block of-lines are both lists, and a number, a boolean or a date is read as the text somebody typed. A key whose value is a nested map, a block scalar (|,>), a flow map or an anchor is not read, so the document does not carry that key at all. ↩ -
Frontmatter properties are not a row’s properties: a
date:is not the day the journal reads, adone:is not a mark, and atags:is not a tag, sois:done,has:dateanddate:todaynever match a document. The page draws them as chips, the way a row’s page does, under the path heading and above the body. They are hidden while the editor is open, andmarkdown_indexreports them. ↩ -
olai writes a whole document at a time, never a range of bytes.
createrefuses a path that already exists, and refuses anything but a relative.mdpath, judged one path segment at a time.writerefuses a path that does not exist, so a typo cannot create a file.deleterefuses a file anything still names, and an outline that is not empty. ↩ -
A write may carry
was, the text the caller last read, and is refused if the file changed in the meantime, which is checked on every retry. A delete looks for links in live titles and notes, links in document bodies, and values of properties declareddocin_olai/Properties.olai. Links from trashed rows do not hold a file back; declared property values still do. ↩ -
A relative
in a document is looked for in that document’s own directory, where the same link in a note is looked for beside the note’s outline. It is served from/media/, and only picture suffixes are allowed. A..that would climb above the served directory stops at its root. Nothing else is drawn: no remote host, nodata:URI, no absolute path, no.svg. olai knows pictures by their paths and never loads their bytes.The first picture of a block is fetched straight away, and the rest wait until you scroll near them. ↩
-
A relative
[the deck](../projects/deck.md)opens that document’s page in olai, as does a link to any other file that has a page. A filename with a space in it still works, writtenthe%20brief.md,<the brief.md>orthe brief.md. A[shot](art/handle.png)opens that picture’s page, whiledraws the picture itself from/media/. Anhttp:orhttps:link opens in a new tab; everything else opens in this tab. ↩ -
The pins are the rows of the file named
Pinsdirectly inside_olai/, whatever its capitals, with any suffix that holds rows (How olai checks your files, and how it writes them). A directory without that file has no pins, and when the configured outline plugin is off the sidebar says so. olai creates_olai/Pins.olaiwith that plugin’s suffix. The top level of the file is the list of pins, inordorder, one row per pin; what you nest under a pin is your own business. ↩ -
A pin’s title is an address: a document, then
#, then a place inside it, with a slash in front. Either half may be left out. An address may also carry?q=<filter>, which is how you pin a saved search (Filtering a page).An address naming a row is the one whose file half can go out of date, because a row moves and its id does not. The id may name a mirror: the pin then lands on the mirror’s own row where its file draws it, and otherwise on the row the mirror shows. ↩
-
A pin written as a bare address stores no name, so the list draws that row’s title as it stands now, and a pin to a file is called by its filename. A pin written as a markdown link is a named pin, and you rename it by editing that row’s text. A label keeps the words somebody chose, so a
#homeinside one stays four characters of text. ↩ -
Clicking a named pin’s label opens the address; clicking a bare address opens the editor. olai writes a name only when somebody typed one, and asks for one only for a page carrying a
?q=. A row whose title is an address is drawn as that address in any outline, with the pin mark, the file’s name and the search, in either spelling. The editor opens the title exactly as stored. ↩ -
A pin promises the address somebody saved, and the name of a row read fresh each time. It does not promise that what it points at is still there.
A pin to an id nothing declares draws its own address, such as
/#gone. A pin to a trashed row draws that row’s title and opens its page, without saying that it was put away. A pin to a document is a path, so renaming or deleting the.mdleaves a row named for a file that is not there. ↩ -
A row that is not an address is not a pin. A heading, a note, or a title that merely starts with a slash is not one. olai’s own address parser decides, so
/etc/passwdis read as text, and/%is skipped rather than causing an error. A mirror is never a pin, because it would pull the pinned row’s children into the pins file.An agent pins by adding a row with
outlines_addtoPins.olai, orfiles_createwhen there is no such file, reorders pins withoutlines_move, and unpins withoutlines_trash. ↩ -
The list of file kinds is called
vault.file-kindsand belongs to the vault plugin. It matches suffixes exactly as they are registered, soIMG_1234.JPGanda.OLAIare claimed by nothing. A plugin may claim more suffixes, as hledger does for its ledger files (Reading hledger journal files). A picture is the one kind with a list of suffixes, because.pngand.webpare two encodings of the same thing. ↩ -
The four kinds olai only shows have no editor and no tool that creates one.
markdown_create,markdown_write,markdown_indexandmarkdown_readtake a.mdfile and refuse the rest. olai does not hold the contents of these files: it holds the path, and reads the contents when a reader opens the file.A
.htmlpage, a picture and a.pdfare served from/media/; a.csvis sent as text, the way a document’s body is, which the/media/route will not do. ↩ -
The sidebar lists a
.htmlfile under the folder it lives in, with a mark of its own. The page runs the file’s own JavaScript in a frame sandboxed withoutallow-same-origin, so the page belongs to no site: nodocument.cookie, nolocalStorage, no reading the page around it and no reach into olai. An inline script and an old-style<script src>run; a module script andfetchdo not, because both are requests from a page that belongs to no site. ↩ -
The frame is as tall as the page inside it, between
6remand two screens, and70dvhtall when the page reports no height. The height the page reports comes from a page olai does not trust, so olai holds it to those limits rather than believing it (HTML files). ↩ -
A plain left click follows a link out of the frame when the link lands inside this directory’s
/media/space and names a file olai has a page for. A#part naming another file is carried along, soother.html#bedslands on that section: on the frame’s own URL for a.htmlfile, and on the heading’s slug for a.mdfile. A#part naming nothing leaves you at the top of the page. ↩ -
olai scrolls to that place once, when you arrive, so coming back to the page puts you where you had scrolled to. A link to a picture, a stylesheet or a font is followed inside the frame; a link to another site, or a move the page makes by itself, is left alone.
An in-page
#topis the frame’s own jump. A file that olai’s walk over the directory skips, under a dot-directory ornode_modules, is claimed and then dropped, in a notice that does not quote it. ↩ -
A
.htmlfile that is served and will not open says so on its page:This file couldn't be opened, so there's nothing to show.It does not say why it could not be opened: that would describe your disk to anybody who can reach the port. ↩ -
A
.htmlpage follows the file on disk. The frame asks for the file’s details and its revision, then fetches the bytes itself, so the page arrives one fetch after a document’s text would, and two readers mean two reads. An agent that reads the bytes reads them again at every later revision. ↩