The Contents
The contents down the left side show everything in your project. Documents are listed by their titles, and folders appear as small headings. To hide the contents, or bring them back, choose View ▸ Hide Contents (⌃⌘S).
Projects
A project is a folder of Markdown files, nothing more.
- File ▸ Open Folder (⇧⌘O) opens a folder. You can also drop a folder on Grasmere’s icon in the Dock. An empty folder is a fine place to start.
- Double-click a Markdown file in Finder (new in 1.1) to open it in its project, if it’s in one you’ve opened before, or on its own if not. This works once Grasmere is the app that opens Markdown files, which you can set in Settings ▸ General ▸ Markdown files or in Finder’s Get Info ▸ Open with.
- Quick Look (new in 1.1). Press Space on a Markdown file in Finder to see it set as Grasmere sets it, light or dark to match your Mac.
- File ▸ Open Recent Project lists the folders you’ve used. Grasmere reopens your last project where you left it.
- File ▸ New Window (⇧⌘N) opens a second project alongside.
- Project ▸ Ignored Folders leaves out folders you don’t want in the contents, search or links, such as a folder of build output. You can also right-click a folder and choose Ignore This Folder.
A document opened on its own gets a window of its own. It’s just the page, with its folder named at the top and a button to open that folder as a project. Its links open the documents beside it, and Back and Forward work. So do Export as PDF, Copy as Context, Ask a Follow-up Question and Writing Replay. The things that need a project wait until you open one: the contents, backlinks, history, Tasks and Ask Your Documents.
The first time a document on its own links to other files, Grasmere asks once for permission to open the folder they’re in. That’s the document’s own folder, or one above it for links like ../people/Rosa.md. macOS only lets an app read the file you opened, not the files next to it. Once you’ve said yes, links that lead nowhere are underlined with dots, as in a project, and counted beneath the page (“3 links · 2 broken”).
Documents and folders
- File ▸ New Document (⌘N) and New Folder (⌥⌘N) make a new item with its name ready to type. Where it goes depends on what you last did in the contents. If you’ve just clicked a folder open, it goes inside. If you’ve just clicked a folder closed, it goes at the top level. Otherwise it goes beside the open document.
- Double-click a document to rename it. The file name changes and links to it are updated.
- Drag a document onto a folder to move it. Links follow.
- ⌘1 (Go ▸ Select in Contents) moves the keyboard to the contents. The arrow keys move up and down, → and ← open and close folders, and Return opens a document. Type a few letters to jump to a name. Tab or esc takes you back to the document.
Right-click a document for Rename, Show in Finder, Copy Relative Path, Copy Absolute Path, Open in Split View and Move to Trash. Right-click a folder for Open as Manuscript, Publish to PDF, Set Word Target, Export Folder to Anki, its order, and Ignore This Folder.
New in 1.3: sources in the research folder have an icon for what they are, such as a book, a globe for a web page or a page for an article. The research folder also has research.md, Grasmere’s table of your sources. See Citations.
Several documents at once
To work on several documents together, ⌘-click or ⇧-click to pick them, then right-click.
- Merge joins them into one document, with a section for each. Every link to the originals points at the right section, and the originals go to the Trash. Undo brings them back. It’s also in Project ▸ Merge Selected Documents.
- Export sends them to Anki. See Publishing.
- Move puts them in the Trash. ⌘⌫ does the same.
Deleted documents go to the Mac’s Trash, so you can get them back from there. Grasmere asks first before trashing a folder or more than five items.
The order of a folder
Left alone, a folder lists its subfolders first and then its documents by name, the way the Finder does. You can give any folder an order of its own, either by hand or by a rule.
By hand. Drag a document onto the top or bottom half of another document’s row and it moves there. Grasmere keeps the order in the folder’s index.md. The folder is listed in the order that file’s links reach its documents, and anything not linked comes after. A folder without an index.md gets one the first time you drag something into a new place, listing its items as they were. To open it, right-click the folder and choose Edit Order of … (index.md). To make one straight away, choose Order … with index.md.
The index.md is an ordinary document, so you can write something about the folder in it too. This project’s Guides are kept in reading order this way.
By a rule. Right-click a folder and choose Sort Folder By ▸ Name, Date Created or Date Modified, each either way round. The rule goes into the folder’s index.md as an invisible comment, such as <!-- sort: modified, newest first -->, and the folder stays in that order as documents change. If you then drag an item, the rule becomes a list of links in the order shown, and the menu says Sort Folder By ▸ Custom (Drag to Reorder). If you didn’t mean it, there’s Undo in the bar.
The top level can have a rule too. Right-click the contents list itself, away from any row, and choose Sort Top Level By. That rule is kept in project.md’s Order section.
project.md
Every project has a project.md at its top, made the first time the project is opened. It’s an ordinary document, and Grasmere reads a few of its sections:
- Summary is a short overview of the project, shown at the top of the contents. Write it yourself, or let Project ▸ Generate Summary write it (see Ask Your Documents and AI). It’s also the home page when you build a website.
- Order links to the top-level documents and folders, in the order the contents list them. Dragging at the top level rewrites it.
- Writing holds word targets and the words written each day. See Writing Goals.
Anything else you write in project.md is left as it is.
Settings
In Settings ▸ Appearance:
- Name documents in the sidebar by Title (the first heading), File name, or File name with .md.
- Show images in the contents lists pictures alongside documents. Click one to look at it, double-click to rename it (links follow), or drag it into a document to link it.
- Show project.md in the contents and Show index.md in the contents list those files as documents. They’re hidden by default, and the order they set applies either way.
- Show research.md in the contents and Manuscripts (new in 1.3) lists the research folder’s table of sources. It’s on by default. Turn it off and the table is still kept up to date.