Files and Git

Markdown documents

Open, read, edit and save a Markdown file with the Rich, Source and Preview views.

On this page

Purpose

A Markdown file opens in a window with three views. Rich shows formatted text and you type in it. Source shows the plain Markdown text. Preview shows formatted text and is read-only. Use Rich to write fast, Source for exact control, and Preview to read.

Where to find it

  • Left sidebar, Files icon (tooltip "Files"). Double-click a file whose name ends in .md or .markdown. See Files panel.
  • Orkestra picks the Markdown view by the file name only. Letter case does not matter. Other file types open in the code editor. See File, image and HTML windows.
  • The file opens in a file window on the active workbench. From the Files panel it opens in focus. See Canvas windows.
  • The same editor edits the Description of a task. See Task window. This chapter describes the file window.

What you see

Title bar (the shared frame; see Canvas windows). Left to right:

  • Save state next to the file name, for example Saved or Unsaved changes. See File, image and HTML windows.
  • Three icon buttons, group name "Editor mode": Source (code icon), Rich (pencil icon), Preview (eye icon). The tooltip of each is its name. The active view is highlighted.
  • Reload — icon button. Tooltip "Reload from disk", or "Discard changes and reload from disk" when you have unsaved changes.
  • Save — icon button. Tooltip "Save changes" when there is something to save. The button is disabled when there is nothing to save.

Notices between the title bar and the text. See "States and messages".

Formatting toolbar (name "Markdown formatting"). It shows in Rich and Source, not in Preview. Left to right:

  • Undo and Redo.
  • Paragraph — a drop-down button. It opens the "Block style" menu: Paragraph, Heading 1, Heading 2, Heading 3, Quote. The button always says "Paragraph". It does not show the type of the current block.
  • Bold, Italic, Strikethrough, Inline code, Link.
  • Bulleted list, Numbered list, Task list.
  • Insert table, Insert image, Insert code block, Insert horizontal rule.
  • More Markdown actions — the "more" icon button. It shows when the window is too narrow for all groups. Its menu lists the hidden actions. Up to about 620 px of width the Paragraph, list and insert groups move into this menu. Up to about 280 px only Undo, Redo and this button stay.

Table editing strip (below the toolbar). It shows when the caret is inside a table, in Rich or Source. It has two groups:

  • Rows: Insert row above, Insert row below, Delete row.
  • Columns: Insert column left, Insert column right, Delete column.

Text area. It shows one of these:

  • Rich — the formatted document. Click anywhere in it and type. Each code block has a small pencil button (tooltip "Edit code block controls", then "Hide code block controls"). It opens a Language drop-down and a delete control for that block.
  • Source — the plain Markdown with colours and wrapped lines. It is the same editor as for code files.
  • Preview — the formatted document, read-only, with a Contents list on the right. The list has the heading buttons and a Collapse contents icon button. When the list is collapsed, one Show contents icon button stays.
  • An empty document shows the placeholder "Start writing…" in Rich and Source.

Pop-ups from the toolbar:

  • Link pop-up: fields Text and URL; icon buttons Open link, Copy URL, Unlink (it clears the URL field); buttons Cancel and Apply.
  • Image pop-up: fields Source, Alt text, Title; buttons Cancel and Apply.
  • "Code language" menu: a Search languages field and the languages Plain text, JavaScript, JSX, TypeScript, TSX, Python, Go, YAML, JSON, CSS, HTML, Shell, SQL, Markdown.

How to

Open a Markdown file

Before you start, the project must have a folder on disk.

  1. Open Files in the left sidebar.
  2. Double-click a file whose name ends in .md or .markdown.

Result: the file opens in a window in focus. The Rich view is active and the title bar shows Saved. If Rich is not available for this file, the window shows Preview and a grey notice gives the reason.

Switch between Rich, Source and Preview

  1. Click Source in the title bar of the window.
  2. Click Rich in the title bar.
  3. Click Preview in the title bar.

Result: the window shows the view you chose. The text is the same in all three views, including edits you did not save.

Edit text in the Rich view

Before you start, make sure Rich is active.

  1. Click in a paragraph of the document.
  2. Type your text.

Result: the text changes at once and the title bar shows Unsaved changes. The file on disk does not change until you save. In a table cell, the text is applied when you leave the cell. See "Limits and tips".

Format text

  1. Select the words in the document.
  2. Click Bold in the toolbar.

Result: the words are bold. Italic, Strikethrough and Inline code work the same way. In Source, the button adds the Markdown marks around the selection.

Change the block style

  1. Click in a paragraph.
  2. Click Paragraph in the toolbar.
  3. Click Heading 2 in the menu.

Result: the paragraph becomes a level 2 heading. Paragraph in the menu turns a heading back into plain text.

  1. Select the text to link.
  2. Click Link in the toolbar.
  3. Click the URL field in the Link pop-up.
  4. Type the full address, for example https://example.com.
  5. Click Apply.

Result: the link is inserted at the caret. The Text field starts with the text you selected.

Add an image

  1. Click Insert image in the toolbar.
  2. Type the picture address in the Source field of the Image pop-up.
  3. Click Apply.

Result: Orkestra inserts the image in the document. A picture from a web address does not load. See "Limits and tips".

Add a table and a row

  1. Click Insert table in the toolbar.
  2. Click in a cell of the new table.
  3. Click Insert row below in the Table editing strip.

Result: the table has two columns and one body row at first. The new row appears below the caret row.

Add a code block

  1. Click Insert code block in the toolbar.
  2. Click a language in the "Code language" menu, for example Python.

Result: a code block with that language is inserted. Selected text goes inside the block. To change the language later in Rich, click the pencil button of the block and use the Language drop-down.

Save the document

  1. Click Save in the title bar.

You can also press Ctrl+S (Cmd+S on macOS) when the caret is in the text, the toolbar or the title bar.

Result: Orkestra first applies any open table-cell text. Then it writes the file. The title bar shows Saved.

Read a document in Preview

  1. Click Preview in the title bar.
  2. Click a heading name in the Contents list.

Result: Preview scrolls to that heading. The current heading is highlighted as you scroll. Preview shows your current text, including unsaved edits.

  1. Click Preview in the title bar.
  2. Click the link text.

Result: a link to a local file opens it in an Orkestra window. Relative links use the folder of the Markdown file. A link to a local picture or HTML page opens its matching Orkestra window. A missing or out-of-project link shows an error message. A web or email link opens outside Orkestra in the usual application. A link such as #details scrolls to that heading in the current Preview.

Continue editing when Rich is not available

  1. Read the grey notice above the text.
  2. Click Source in the title bar.
  3. Edit the text.
  4. Click Save in the title bar.

Result: you edit the exact Markdown. After you remove the cause and save, click Rich to try again. If Rich is still disabled, the cause is still in the file.

Find text in the Markdown source

  1. Click Source in the title bar.
  2. Click in the text.
  3. Press Ctrl+F (Cmd+F on macOS).

Result: the Find bar opens at the top right of the text. It is the same bar as for code files. See File, image and HTML windows.

States and messages

Rich is not available. A grey notice with an info icon shows above the text. The Rich button is disabled and its tooltip shows the same reason. Each text starts with "Rich editing is off for this document — " and ends with one of these:

  • "it exceeds the 256 KiB size limit"
  • "it contains reference-style links"
  • "it contains footnotes"
  • "it contains raw HTML"
  • "the Markdown could not be parsed safely"
  • "its tables have more than 500 cells"
  • "the edit was not applied because the original Markdown could not be safely preserved. Your original Markdown is still intact; switch to Source to continue editing safely."

If you ask for Rich on such a file, the window shows Preview, and Preview is highlighted. Source stays available.

An edit in Rich cannot be applied. Orkestra drops that edit and switches to Source at once. The notice stays above the text. Your text before the edit is intact. One more reason has its own text: "Rich edit was not applied because this document has mixed line endings that cannot be safely restored. Your original Markdown is intact; switch to Source to continue editing."

Rich crashed. An alert shows "Rich editor crashed — showing Source." with a Retry button. The window shows the Source text meanwhile.

The file changed on disk. Orkestra reloads the file or shows the notice "This file changed on disk while you were editing", with Keep mine, Use disk version and Compare. This works the same way as for all files. See File, image and HTML windows.

A refresh failed. The alert says "This editor may be stale because the latest disk refresh failed — <reason>. Retry when the file is available."

Save errors, saved drafts and the Discarded unsaved changes message are the same for all files. See File, image and HTML windows.

In the Link pop-up a red text shows under the fields. It can say "Enter a URL first.", "Enter a complete http, https, or mailto URL." or "Only http, https, and mailto links can be opened." It disables only Open link. Apply still inserts the link.

In the Table editing strip a button can be disabled. Its tooltip gives the reason: "Tables require a header row", "There is no body row to delete", "Tables require at least one body row" or "Tables require at least one column".

In Preview these notes can show:

  • "Not rendered here — source preserved (<name>)" at the top, once per feature that Preview cannot draw: github alerts, wiki-links, definition lists, abbreviations, subscript, superscript, emoji shortcodes, frontmatter, highlight mark, mdx JSX.
  • The same note under a code block whose language Preview cannot draw (for example plantuml, graphviz or vega). The block shows its source.
  • A diagram (a code block with the language mermaid) shows "Rendering diagram…" and then the picture. If it fails: "This diagram could not be rendered — its source is unchanged". A rendered diagram has the icon buttons View diagram source (then View diagram rendering) and Copy diagram source.
  • Maths between dollar signs shows "Rendering mathematics…". If it fails: "Mathematics could not be rendered — source is unchanged".

Limits and tips

  • When Rich is allowed. The file as loaded must be at most 256 KiB, have at most 500 table cells, and have no raw HTML, footnotes or reference-style links (a line like [docs]: https://…). Tables, task lists, strikethrough, highlighted text, front matter and HTML comments are fine. The check uses the file as loaded. When you save or reload, Orkestra checks it again.
  • Rich keeps the rest of your file. Orkestra changes only the part you edit. Spacing and style of the other parts stay as written. Source is always exact.
  • Rich shortcuts. Typed Markdown works: # starts a heading, - a bullet list, 1. a numbered list, > a quote, **text** makes bold. Tab and Shift+Tab indent and outdent a list item.
  • Source. The toolbar adds Markdown text. Bold wraps the selection in marks. With no selection it inserts the marks around a placeholder word. List buttons and the Paragraph menu change the start of each touched line.
  • Table cells are applied later. In Rich, text you type in a table cell is "pending" until you leave the cell. Pending text shows Unsaved changes and enables Save. Orkestra applies it when you click out of the cell, press Ctrl+S, click Save, Reload, a mode button, or close the window.
  • Leaving focus. Exit focus (Esc), the Esc key and a click on the dim backdrop all first apply the pending table-cell text. Then the window leaves focus. This does not save the file. The title bar keeps Unsaved changes until you save. Orkestra tracks only table-cell text as pending. Other Rich text is applied as you type. See Canvas windows.
  • Esc in menus. Esc closes an open toolbar menu, pop-up or code-block control first. It does not leave focus mode.
  • The view is not saved. Each window starts in Rich, also after a restart. The canvas copy and the focused copy of a window share one view.
  • Undo and redo. Ctrl+Z (Cmd+Z) undoes. Ctrl+Y or Ctrl+Shift+Z (Cmd+Shift+Z) redoes. They work in Rich and Source. See File, image and HTML windows.
  • Find works in Source only. Rich and Preview have no Find bar.
  • Preview is read-only. Raw HTML in the file does not show. Task list boxes are display only.
  • Pictures. Orkestra blocks content from the web, so a picture with a web address does not load. A picture with a data address shows.
  • Link pop-up. Rich has no pop-up to edit an existing link. To change a link address, use Source.