The Archive: Help

Back to the Project Page

How to Get Help Inside the App

  • For a quick overview of The Archive‘s philosophy, check out the welcome note. You can add the note to your current archive directory from the Help menu: Help ‣ Create Welcome Note…
  • To get tips on how to use the user interface, use the App Guide for a guided tour: Help ‣ Show App Guide…

Check Out Our Forums

Out community of users is pretty amazing. You should get to know them! We’ll answer any app-related questions on the forums, too, so those coming after you can benefit from your question.

Find discussions about The Archive here: https://forum.zettelkasten.de/categories/the-archive

Hidden Preferences

Some settings in the app are not exposed as user-customizable preferences. But they can be changed via the thearchive:// URL scheme. For some changes to take effect, you may have to relaunch the app.

To open these URLs, use the Terminal and use the open command, e.g.:

open thearchive://preference/thePreferenceName/set/1234
  • To set a preference, use the format thearchive://preference/<PREFNAME>/set/<VALUE>.
  • To reset a changed preference to its built-in value, use the format thearchive://preference/<PREFNAME>/delete.

Currently supported preferences (replace <PREFNAME> with these):

  • debugMode (boolean).
    Default value: false.
    Shows additional tools to help diagnose problems, and develop themes and scripts.

  • enableInlineImagePreview (boolean).
    Default value: true.
    Turn the image preview on and off.

  • isHighlightingMarkdown (boolean).
    Default value: true.
    Turn Markdown highlighting on and off.

  • isRestoringScrollPosition (boolean).
    Default value: true.
    Turn restoring of the previously saved position when revisiting a note on and off. Turned off (false), selecting a note will always scroll to the top.

  • maxInlineImagePreviewHeight (number).
    Default value: 400 pixels.
    Preview images will always shrink to fit to the text column’s width. This value determines tha maximum height, so you don’t fill multiple screens worth of scrolling with tall screenshots. We recommend a value no larger than half your screen height.

  • resultsCellHeightFactor (fractional number).
    Default value: 2.2.
    Changes the height of the search result list rows in relation to the text.

  • splitViewDividerAreaExpansion (number).
    Default is unset, effectively 0 pixels.
    Affects the padding around the divider hairline that activates the resize functionality, indicated by the ←|→ mouse cursor.

  • timeZoneOverride (string).
    Default is unset, effectively using the system’s time zone.
    <VALUE> can be an abbreviation like UTC or CEST and is case-sensitve. New note IDs will be generated for the current time in that time zone.

Frequently Asked Questions

How can I import Finder tags? (Applies to nvALT and DEVONthink, too)

nvALT stores the tags as so-called “Finder tags” in the file metadata. Same for DEVONthink’s exported notes.

This is brittle and only works on Mac. The Archive does not recognize these on purpose, so you don’t tag yourself into a corner.

We provide a converter utility that inserts missing #hashtags into your notes to match the Finder metadata. This should help with the transition!

(back to top)

How do I create notes?

There are different ways to create a note, each with pros and cons depending on your workflow.

  1. Type the note title you want into the Omnibar and hit Return. If you type a term in the Omnibar that is not used as the name of a note already, The Archive will create a matching note for you; if a note exists, it will be opened instead.
  2. Use a Wiki-Link: create a link that leads nowhere, click on it to follow the link. There’ll be no note to show, but the Omnibar contains the link now. Then create a note from the Omnibar as you would above. The Wiki-link feature is built on top of the search. Similar rules apply to entering a term in the Omnibar: if a note with the linked text exists, it will be displayed for you. If there is no matching note, you can hit Return from the Omnibar to create a note with the title set to the search term.
  3. Create an empty note in The Archive without changing your search. Just hit ⌘N (or pick Note ‣ New from the menu). The Archive will create a note for you that will be named “Untitled” and take you right into the editor. After you complete the note you can rename it by hitting ⌘R (or via Note ‣ Rename from the main menu).
  4. Use the “Quick Entry” popup window from anywhere on your system to capture a thought. You have to configure the shortcut in the application preferences (⌘,) to make it globally accessible.

(back to top)

To create links between notes, you need to define how to target a note first. On the web, it is simple: each website has its own unique address that you can copy from the address bar of your web browser.

When you work with plain text files, it might sound obvious to use the file names. And if you want to have clickable links, you might use the full path to a note, like file:///Users/JaneDoe/Archive/some-note.txt. But that’s fragile, since the links break when you rename the note or move your archive to a different path.

This is how we do it: every Zettel note gets its own unique ID. We choose the timestamp-like IDs like 201402260939 which would be based on the date “2014-02-26 9:39a.m.” Moments in time are unique; and the ID should be fixed, so the note title is not a good candidate as it may change over time.

When you reference a note from someplace else, you paste the ID there. You will soon learn to recognize such sequences of digits as IDs because of the way they look. Then you know, “there’s a Zettel with this ID, I should check it out!”

The Archive tries to be helpful and aid you with these nifty [[Double Bracket Wiki-Links]], which trigger a search. Adhering to the double-square-bracket convention of wikis, you get clickable links using Zettel IDs without buying into any proprietary file format or fragile file paths.

Read more about identifiers.

(back to top)

As with internal connection, using a file-based link isn’t a very durable way to point into your note archive from outside. We suggest you simply paste the ID for maximum durability.

If you really want to create a link to click on that launches The Archive and opens an appropriate note, we got you covered with a external link URL scheme:

  • thearchive://search/TERM searches for TERM as if you typed it in
  • thearchive://match/TERM works like the search but displays a good match directly; this is similar to [[Wiki-Links]].
  • thearchive://matchOrCreate/TERM will create a note of the exact title TERM if that doesn’t exist; it’s similar to entering a search term into the Omnibar and hitting the return key.

(back to top)

Yes! Here’s how.

Operators are all caps: AND, OR, and NOT. NOT is alternatively expressed by the ! prefix. NOT b is equal to !b and will show notes that have no “b” inside them. ! b (note the space) evaluates as ! AND b.

When you write foo bar, that’s the same as writing foo AND bar. You can also connect phrases with OR to form a set union. Usually, phrases are “words”, i.e. strings of characters separated by whitespace. You can group words into larger phrases with the use of quotation marks: "the archive" will only find this very phrase, sans quotation marks, and not each occurrence of “the” in your notes.

Phrase search wins: "!b" is a phrase search for “!b”, matching the literal exclamation mark and letter. Instead of quotation marks, escaping works, too: \!b. Escaping inside phrase searches will also work: hello "you \"lovely\" specimen". You can also escape parts of reserved words, like the beginning of an operator: \AND will not be treated as an operator.

You can parenthesize expressions: !(foo OR (baz AND !bar) is equivalent to the expanded version, !foo OR !baz AND !foo OR !bar. Be aware that OR and AND do not have correct operator precedence. If you don’t know what that means, you probably do not need to care.

(back to top)

Sending in Log Files for Errors

You can send log files from within the app by choosing Help ‣ Send Log Files…. This will attach log files of up to 5 days of app activity. You can remove irrelevant log files from the email draft.

Please make sure to delete confidential information from the log if necessary using any text editor.

Sending in Crash Reports

macOS 10.12 and later:

  • Open the built-in Console.app: Open Finder, choose Go ‣ Utilities, open the Console application.
  • Click on User Reports under Reports at the left side of the window. (If there’s no sidebar to your left, choose View ‣ Show Sources.)
  • In the middle, a list of files will appear, showing a collection of all crash reports. Choose the file or files starting with “The Archive”, like “The Archive_2018-03-14.crash”.
  • Click the Share button in the toolbar and select Mail. (If you do not use Apple Mail as your email client, you can instead Copy and Paste the whole crash report into your email client.)

macOS 10.11 and earlier:

  • Open the built-in Console.app: Open Finder, choose Go ‣ Utilities, open the Console application.
  • Expand User Diagnostics Reports under Diagnostics and Usage Information from the left sidebar of the window.
  • A list of crash reports will appear. Choose the file or files starting with “The Archive”, like “The Archive_2018-03-14.crash”.
  • Right-click and choose Reveal in Finder. Then attach the selected files to an email and send it to us.