Guidelines

This page walks you through everything MarkView does, from first install to the small features you probably want to know about. Read top to bottom on your first visit, or jump to a section from the sidebar on the left.

Installation

MarkView ships as a notarised-free macOS app. There are three install paths, all of them clean. They all skip the usual "developer cannot be verified" first-launch warning.

Easiest: one-line installer

curl -fsSL https://markdown.kuberscan.com/install.sh | bash

Works on any Mac with curl (built in). The script asks GitHub for the latest .dmg, downloads it to a temporary folder, copies MarkView.app to /Applications, strips the macOS quarantine attribute, and ejects the disk. No Homebrew required. Re-run the same command later to update.

Homebrew

brew install --cask enderphan94/tap/markview

If you already have Homebrew, this is the most natural fit. Update with brew upgrade --cask markview.

Direct DMG

Grab the latest .dmg from the Releases page, drag MarkView.app into /Applications, and eject. The first launch needs a right-click then Open the first time, because the DMG is not signed by an Apple developer account. The other two install paths above skip this dance entirely.

First launch

The first time you open MarkView, a small picker asks where your notes should live. The default is iCloud Drive, which is recommended if you have more than one Mac. Toggle that off and you can pick any folder on disk.

The folder you pick is your vault. Everything you write goes there as a real .md file. You can move, rename, or back up the folder later, MarkView remembers the path in its per-Mac config.

If you previously used the SQLite-backed v2.1 release, MarkView migrates those notes to real files in your new vault on the first launch of v2.2 or later. The old database is renamed to *.imported as a backup.

Updating

From v2.1.0 onwards MarkView checks GitHub Releases on every launch. If a newer version exists, a small modal appears with Update Now and Skip.

• Update Now downloads the new .dmg, swaps the app in place, strips the quarantine attribute, and relaunches. One click, no Gatekeeper reprompt.
• Skip dismisses for this session. The modal returns on the next launch.
• Settings → Check for updates runs the same check on demand.

Going from any older version straight to the newest is a single hop. You do not need to install intermediate versions.

Writing markdown

The editor is two panes by default (three with the workspace sidebar open). Type on the left, see the rendered preview on the right. Every change is reflected as you type, no save button needed. MarkView uses GitHub-flavoured markdown.

Syntax cheat sheet

# Heading 1
## Heading 2

**bold**, *italic*, ~~strike~~, `inline code`, [link](https://kuberscan.com)

- bullets
- with **inline** styling
  - nested

1. ordered
2. lists

- [x] task list
- [ ] still to do

> A blockquote.

| col A | col B |
|-------|-------|
| 1     | 2     |

```python
def hello():
    print("syntax highlighting via highlight.js")
```

Code fences support 180+ languages through highlight.js. Inline code, images, horizontal rules, and tables all work the same way you would expect from any markdown renderer.

Mermaid diagrams

Mermaid v11 is bundled inside MarkView. Open a fenced code block with mermaid as the language and your diagram renders live, fully offline.

```mermaid
flowchart LR
  A[Idea] --> B(Note)
  B --> C{Share?}
  C -->|Yes| D[48-hour link]
  C -->|No|  E[Stays local]
```

Supported diagram types include flowchart, sequence, state, class, pie, gantt, mindmap, ER, journey, and git graph. The palette follows your theme, so switching to dark mode redraws every diagram in dark mode colours.

Export to PDF

Click Export PDF in the toolbar. A small dialog asks how the PDF should look.

• Default is pure black and white, mermaid forced to grayscale. Smallest file, prints fine on any printer.
• Styled keeps the preview colours, including syntax highlighting and full-colour mermaid diagrams.

Tall diagrams scale to fit one page. There are no overlaps with surrounding sections and no blank trailing pages.

Workspace sidebar

The leftmost pane lists every note and folder in your vault. It is built to feel like Obsidian and Finder at the same time.

Creating things

The two icons in the sidebar header create a new note and a new folder respectively. Each starts with a default name in inline edit mode, so you can type the real name immediately without a popup dialog interrupting you.

Renaming and duplicating

• Double-click any item to rename in place, same behaviour as Finder or Obsidian.
• Right-click for the full menu: rename, duplicate, copy and share URL, reveal in Finder, delete.
• Duplicate on a folder is recursive. The copy is named with a _copied suffix and collisions auto-number.

Sorting

Six modes, picked from the sort menu in the sidebar header:

• File name A to Z, or Z to A
• Modified, newest first or oldest first
• Created, newest first or oldest first

Drag and drop

Drag any note or folder onto another folder to move it. The vault on disk follows in real time, so an open Finder window updates live.

Vault on disk

MarkView stores your notes the same way Obsidian and VS Code do: one folder per folder, one file per note, plain markdown.

~/Library/Mobile Documents/com~apple~CloudDocs/MarkView Vault/
  Projects/
    Roadmap.md
    Notes from Monday.md
  Reading list.md
  Welcome.md

That layout means three things:

• iCloud Drive syncs it for free. Edit on one Mac, the change appears on the other within seconds. No SQLite, no risk of database corruption from concurrent sync.
• Other editors can open the same vault. Point Obsidian, VS Code, vim, or anything else at the folder and your notes are right there.
• Backups are trivial. Copy the folder. That is the whole backup.

Change the vault location anytime under Settings → Vault → Change location. The per-Mac config that remembers the path lives at ~/Library/Application Support/MarkView/config.json and is left untouched by reinstalls.

Multiple workspaces

A vault no longer has to be the only one. You can register several and switch between them, so work notes, personal notes, and a side project each get their own tree without mixing together.

Switching

The sidebar header is a workspace switcher. Click it to see every vault you have registered, then click a name to switch. Switching flushes the current auto-save, clears the editor, and loads the new vault's tree.

Adding a workspace

Pick Add vault from the switcher. You give it a name (for example Work or Personal) and point it at a folder, the same picker you saw on first launch. To add a GitHub repository instead of a local folder, see the next section.

Renaming and removing

• Rename changes only the label in the switcher. Your files are not renamed.
• Remove from list takes a workspace out of the switcher. Your files stay on disk, untouched. Re-add the same folder later and your notes are right where you left them.
• MarkView will not let you remove the last remaining workspace, so you always have somewhere to write.

GitHub workspaces

A workspace can be backed by a GitHub repository instead of a local folder. You edit the repo's markdown exactly like a local note. Edits save to disk instantly so the app always feels fast, and they push up to GitHub in the background and whenever you press ⌘ S.

Signing in

Use the Account button in the top-right of the app, then Sign in to GitHub. MarkView shows a short device code. Open github.com/login/device, paste the code (it is click-to-copy), and approve. That is the whole sign-in.

Nothing secret ships inside the app, and your access token is stored in the macOS Keychain, never in a config file or inside the repo's .git folder. The token is handed to git one command at a time and never written to disk in plain text.

Opening a repository

From the workspace switcher or the Account menu choose Add GitHub repo. Search your repositories, pick one, and MarkView clones it into a workspace. Brand-new empty repositories work too, the first note you save creates and pushes the branch.

Saving and syncing

• Typing saves to the local clone immediately, so editing is never blocked on the network.
• Pushes to GitHub are debounced while you work and flushed on ⌘ S. A small toast confirms Pushed to GitHub.
• If the repository has newer commits than your clone, the push is blocked with a clear message so you can pull or resolve on GitHub first. MarkView never force-pushes over someone else's work.

Sharing from a GitHub workspace

In a GitHub workspace, Save and share gives you a choice: copy a GitHub permalink to the exact file, or create the usual markdown.kuberscan.com 48-hour link. The right-click menu on any note adds Reveal in GitHub and Copy GitHub link for the same thing in one click.

Signing out

Open the Account button and choose Sign out. That removes the token from the Keychain. Your cloned files stay on disk, and you can sign back in anytime.

Private repositories need you to be signed in. The anonymous Import from a URL path can only read public files, so use a GitHub workspace for anything private.

Import from a URL

Click Import from URL. Paste a link and click View. The remote markdown becomes a new note in your workspace.

MarkView accepts every form of these:

• markdown.kuberscan.com/<id> or the bare ID (your own 48-hour share links)
• github.com/<owner>/<repo>/blob/<ref>/<path>
• github.com/<owner>/<repo>/edit/<ref>/<path>
• github.com/<owner>/<repo>/raw/<ref>/<path>
• raw.githubusercontent.com/<owner>/<repo>/<ref>/<path>

GitHub imports keep the source file's basename, so importing a repo's README.md creates a note called README. kuberscan imports default to new_note. Name collisions auto-suffix _2, _3, and so on.

Save and share

The Save and share button on the toolbar posts the current note to markdown.kuberscan.com and returns a shareable URL that lives for 48 hours. The recipient does not need an account or MarkView.

From the right-click menu in the sidebar, Copy and share URL does the same thing but drops the link straight on your clipboard with one click.

Settings

Open the gear icon in the toolbar. Everything in one dialog.

• Language: English or Vietnamese. Every button, prompt, modal, and toast is translated.
• Theme: Light or Dark. Mermaid diagrams re-render to match.
• Vault: current location and a Change location button.
• About: current version, a Check for updates button, author and source-code links.

Keyboard shortcuts

The editor itself auto-saves every 500 milliseconds while you type, so you should rarely need ⌘ S.

Troubleshooting

The app says it cannot be opened

You probably installed by double-clicking the DMG directly. Use the curl or Homebrew install paths instead, both strip the macOS quarantine attribute for you and skip the warning. If you have already installed the DMG by hand, run this in Terminal:

xattr -dr com.apple.quarantine /Applications/MarkView.app

Auto-update did not pick up the latest version

Open Settings and click Check for updates. If the toast says you are on the latest, you really are. If it shows a different version available, click Update Now.

My vault folder has a strange path

The iCloud Drive folder lives at ~/Library/Mobile Documents/com~apple~CloudDocs/ on disk. In Finder it shows as iCloud Drive in the sidebar, but the underlying path is the cryptic one above. Both refer to the same location.

I want to see the developer console

Launch with the debug flag set:

MARKVIEW_DEBUG=1 open /Applications/MarkView.app

Uninstall

If you installed via Homebrew:

brew uninstall --cask markview

Otherwise drag MarkView from /Applications to the Trash, then optionally remove the per-Mac config:

rm -rf ~/Library/Application\ Support/MarkView

Either path leaves your vault folder alone. Your notes are your notes. Delete them by hand if you want them gone.