Getting started with the MD Engine

This file is itself served by the engine. Open the engine folder with:

mddash ~/Documents/md-engine

then visit http://localhost:8031/md/Guides/getting-started.md — what you're reading is the live render. The folder map is on the home page.

Local time, from the built-in widget:

1. The mental model

There are two separate things:

The engine renders any content folder. You are never tied to one project.

2. The one command: mddash

No setup step. There is nothing to "render" or prepare first. mddash is the render — cd into any folder and run it, or pass a path. Done.

mddash                       # serve the folder you're standing in
mddash ~/Documents/Physics   # serve a specific folder
mddash -p 8050 ~/Documents/Physics   # use a different port

By default it auto-opens your browser. Pick which one (or turn it off):

mddash -b safari    # open in Safari
mddash -b chrome    # open in Chrome
mddash -b both      # open in BOTH Safari and Chrome
mddash -n           # don't open any browser

You can set a permanent default in ~/.zshrc: export MDDASH_BROWSER=both.

Then the page is at http://localhost:8031/ (or your -p port). Stop with Ctrl+C.

• The home page (/) renders index.md in the served folder. If there's no index.md, the engine creates a starter ai_notes.md.
• Any other file is at /md/<relative-path>.md, e.g. a note at chapters/intro.md is http://localhost:8031/md/chapters/intro.md.
• Hot reload: save a .md, style.css, or a widget — the page refreshes itself (~200 ms poll). No manual reload.

Only one server per port. To view two folders at once, give the second a different port: mddash -p 8032 ~/Documents/Physics.

3. A good folder layout

Nothing is required except your .md files, but this scales well:

~/Documents/Physics/
  index.md          ← the home page (start here)
  mechanics.md
  thermodynamics.md
  images/           ← put pictures here  ->  ![](/images/diagram.png)
  videos/           ← put clips here     ->  served at /videos/clip.mp4
  style.css         ← OPTIONAL: overrides the engine's look for THIS folder
  widgets/          ← OPTIONAL: extra Python widgets for THIS folder

The override rule (important)

For style.css and widgets/, the engine checks the served folder first, and falls back to its own defaults:

• No style.css in the folder → uses the engine's global stylesheet.
• A style.css in the folder → that folder looks however you want, without touching any other folder.
• Same for widgets/: the global default is only clock; drop a widgets/mything.py into a folder to add widgets just for that folder.

4. What you can write in a note

Math (KaTeX)

Inline $E = mc^2$ and display:

$$ \int_{0}^{\infty} e^{-x}\,dx = 1 \qquad \nabla \cdot \mathbf{E} = \frac{\rho}{\varepsilon_0} $$

Tables, code, task lists

def greet(name):
    return f"hello {name}"

• Math renders
• Diagrams render
• Write tomorrow's notes

Diagrams (Mermaid)

Images and videos

Drop files into the folder's images/ and videos/, then reference them:

![A diagram](/images/diagram.png)

The clock widget

Type {​{ clock }} or {​{ clock: My label }} anywhere — it updates every second. This is the only widget shipped globally; add your own per folder (Section 6).

Captions & cross-references

<div id="setup" class="caption-box caption-figure" markdown="1">
<div class="caption-content" markdown="1">
![](/images/setup.png)
</div>
<div class="caption-title"><span class="caption-label">Figure</span>: Lab setup</div>
</div>

5. A typical workflow

1. Make a folder: mkdir ~/Documents/Physics && cd ~/Documents/Physics
2. Create index.md, start writing.
3. Run mddash (from inside the folder) → open the browser.
4. Keep the browser open; every save hot-reloads.
5. Next topic? New folder, repeat. Same engine, zero setup.

Tip: add images/ and videos/ subfolders up front so links just work.

6. Adding your own widget (optional)

A widget is a tiny Python file. Put it in that folder's widgets/ so it stays local (the global engine deliberately ships only clock).

~/Documents/Physics/widgets/today.py:

from datetime import date

def render(context=None, argument=None):
    label = (argument or "Today").strip()
    return f'<div class="py-widget"><b>{label}:</b> {date.today():%A, %d %B %Y}</div>'

Use it in a note with {​{ today }} or {​{ today: Date }}.

• The function signature is render(context=None, argument=None) -> str (HTML).
• argument is whatever follows the colon in {​{ name: argument }}.
• Emit flush-left HTML (no leading indentation) or Markdown will treat it as a code block.

7. Always-on server (disabled on this Mac)

Currently off. The LaunchAgent below is disabled — nothing runs until you open a file, and each server serves one folder. The always-on copy of the engine that is running lives on the Raspberry Pi; see PI-GUIDE.md.

It would run automatically when you log in and serve a folder on http://localhost:8031/ — no browser pop-up, restarting itself if it crashes. It is a macOS LaunchAgent at:

~/Library/LaunchAgents/com.mddash.server.plist

Manage it:

launchctl list | grep mddash      # running?  (PID  exit-code  label)
launchctl unload ~/Library/LaunchAgents/com.mddash.server.plist   # stop
launchctl load   ~/Library/LaunchAgents/com.mddash.server.plist   # start
tail ~/Documents/md-engine/mddash.log   # see its output (only written while it runs)

To change the folder it serves at boot, edit the folder path in the <array> of that plist, then unload + load.

If you re-enable it, the boot server holds port 8031, so run ad-hoc folders on another port: mddash -p 8032 ~/Documents/Physics.

8. Quick reference

Engine home: ~/Documents/md-engine/ · Launcher: ~/.local/bin/mddash · Boot agent: com.mddash.server (disabled — see §7)