Ledge: Uitvoerbare Markdown-notities

Uitvoerbare Code en Shells

Elke notitie heeft zijn eigen shell. Codeblokken worden uitgevoerd in een persistente shell die bij de specifieke notitie hoort. Hierdoor blijven acties zoals cd, geëxporteerde variabelen of een geactiveerde virtualenv behouden voor de volgende run.

Bediening en interactie

  • ⌘↩: Voert het blok uit waar de cursor zich bevindt. De output wordt eronder gestreamd.
  • ⇧⌘↩: Stuurt het blok naar de 'terminal drawer', een tweede shell waarin je kunt blijven typen.
  • Interactie: Een lopend blok kan input ontvangen. Je kunt bijvoorbeeld een sudo-wachtwoord invoeren of een [y/N] vraag beantwoorden in het outputpaneel.
  • Configuratie: In de frontmatter kunnen cwd: en env: worden gebruikt om in te stellen waar de shells van de notitie starten en welke variabelen ze meenemen.
  • norun: Door norun toe te voegen aan een code-omheining (fence), wordt de Run-knop verwijderd. Dit is handig voor commando's die je wilt citeren, maar niet wilt uitvoeren.

Notities op een Remote Server

Je kunt Ledge koppelen aan een machine via SSH, waardoor de notities daar worden opgeslagen. De server beheert de bestanden en voert de shells uit; de app op je computer fungeert enkel als venster naar die server.

Kenmerken van servergebruik

  • Geen account: Er is geen account, service of open poort nodig. De enige verbinding tussen jou en de server is SSH.
  • Persistentie: Shells en actieve blokken behoren tot de server. Als je je laptop sluit, lopen de processen door. De output staat klaar zodra je de app weer opent.
  • Multi-device: Je computer, telefoon en een tweede venster kunnen tegelijkertijd op één server zijn, elk met eigen tabbladen.
  • Beveiliging: Inloggen gebeurt via een SSH-sleutel of een wachtwoord in de systeem-keychain. Ledge pinnen de host-sleutel van de server en weigert alle andere.
  • Installatie: De Ledge Server kan worden geïnstalleerd met:

curl -fsSL https://ledge.sh/server.sh | sh

  • Back-ups: Met ledge backup kan elk uur een versleutelde kopie van de notities in een S3-compatibele bucket worden geplaatst.

Ledge op Mobiel

Ledge is beschikbaar voor iPhone en iPad als een venster naar dezelfde server. De telefoon slaat zelf geen notities op, maar leest, bewerkt en voert uit wat op de server staat.

  • Functionaliteit: Live preview, zoeken, tags, backlinks, dagelijkse notities en wikilinks werken volledig.
  • Uitvoering: Tik op 'Run' bij een blok om dit op de server uit te voeren. Je kunt de app verlaten terwijl het proces doorloopt.
  • Bediening: Toetsen zoals ^C, ^D, Escape en de pijltjestoetsen bevinden zich boven het toetsenbord om commando's te onderbreken of door tools als htop te navigeren.
  • Koppeling: Koppeling gebeurt via een pairing-code die ledge pair op de server print. De telefoon gebruikt een sleutel in de Secure Enclave die het apparaat nooit verlaat.
  • Versleuteling: Vergrendelde notities worden geopend met een wachtwoord; de telefoon slaat dit niet op.

Uitvoeren op andere machines

Door een host: regel aan de frontmatter toe te voegen, wordt elke run in die notitie via SSH op die specifieke host uitgevoerd, terwijl de notitie zelf op de oorspronkelijke locatie blijft staan.

  • Meerdere hosts: Je kunt meerdere hosts definiëren; Ledge vraagt dan bij elke run welke host gebruikt moet worden.
  • Bevestiging: Markeer een blok als confirm om Ledge de code te laten tonen, de machine te noemen en om bevestiging te vragen voordat het wordt uitgevoerd.
  • Authenticatie: Maakt gebruik van je eigen SSH-configuratie (sleutels, agents, ~/.ssh/config en 2FA).
  • Omgeving: De cwd en env van de notitie reizen mee met de run, maar profielen en secrets doen dat niet.
  • Interpreters: Python, Node en andere geïnterpreteerde blokken draaien ook op de host, met een per-machine interpreter-override in de instellingen.

Interface en Workflow

Panen en Tabbladen

  • Splitsen: ⌘D splitst het scherm links/rechts, ⇧⌘D boven/onder. Elk paneel heeft eigen tabbladen.
  • Onafhankelijkheid: Elke notitie houdt zijn eigen shell vast, waardoor twee panen twee verschillende werkomgevingen zijn.
  • Drag-and-drop: Sleep een tabblad naar een ander paneel; de cursorpositie, scrollpositie, ongedaan-geschiedenis en actieve output blijven behouden.
  • Navigatie: <0xE2><0x8C><0x83>Tab wisselt tussen tabbladen; <0xE2><0x8C><0x83>1 t/m <0xE2><0x8C><0x83>9 springt direct naar een positie.
  • Workspaces: Elke workspace slaat zijn layout op. Schakel tussen workspaces met ⌘1 t/m ⌘9.

Secrets en Profielen

Een profiel is een benoemd bestand met omgevingsvariabelen dat buiten de map met notities wordt bewaard.

  • Gebruik: profile: deploy in de frontmatter leest het bestand ~/.config/ledge/profiles/deploy.env.
  • Veiligheid: Omdat profielen buiten de notities staan, worden ze niet meegesynchroniseerd of geback-upt in de Markdown-bestanden. De waarden blijven op de machine.
  • Overriding: Een env: regel in een notitie kan een waarde uit een profiel overschrijven voor die specifieke notitie.
  • Beheer: Een ingebouwde editor toont waarden gemaskeerd, met een toggle om ze te onthullen.
  • Project-dotenv: envFile: .env laadt de lokale dotenv van een project voor niet-geheime variabelen.

AI Agents en Ledge

Ledge levert een MCP-server (Model Context Protocol). Met claude mcp add ledge -- ledge mcp kunnen Claude Code en andere MCP-agents notities lezen, zoeken, maken en bewerken.

  • Adressering: Notities worden aangesproken op titel, waardoor referenties niet verlopen bij een hernoeming.
  • Context: Een terminal die in een notitie is geopend, weet in welke notitie hij zich bevindt.
  • Prompt-blokken: Een prompt codeblok is uitvoerbaar. ⌘↩ stuurt dit naar de agent en het antwoord wordt direct eronder gestreamd.
  • Beperkingen: Er is geen 'delete' tool voor agents, en vergrendelde notities zijn volledig ontoegankelijk voor AI.

Beveiliging en Privacy

Vergrendelen van notities

Het vergrendelen van een notitie versleutelt de inhoud op de schijf met een wachtwoord.

  • Zichtbaarheid: De titel, frontmatter en tags blijven zichtbaar voor navigatie en links, maar de body is versleuteld.
  • Zoeken: Zoekopdrachten en backlinks slaan vergrendelde bodies over en geven aan hoeveel notities zijn overgeslagen.
  • Automatisch: Eén wachtwoord geldt voor alle vergrendelde notities. ⌘L vergrendelt opnieuw, en de kluis sluit zichzelf na 15 minuten inactiviteit.
  • Bijlagen: Afbeeldingen die in een vergrendelde notitie worden geplakt, worden mee-versleuteld.

Synchronisatie en Git

Notities zijn platte Markdown-bestanden in gewone mappen.

  • Sync-opties: Synchronisatie kan via iCloud Drive, Dropbox, git, Syncthing of andere tools. Er is geen aparte database.
  • Live updates: Ledge volgt wijzigingen van buitenaf live, zelfs in geopende notities.
  • Git-integratie: Je kunt een workspace naar een git-remote pushen. Collega's kunnen deze clonen als een gewone workspace.
  • Conflictbeheer: Git-conflicten worden behandeld als gebruikelijk. Als een pull een open notitie herschrijft, blijft jouw versie behouden en gaat de andere naar de workspace-prullenbak.
  • Sync-notities: Een speciale Sync-notitie kan met ⌘↩ pulllen, committen en pushen.

Toepassingsvoorbeelden

Ledge kan op verschillende manieren worden ingezet:

  • Data-exploratie: Gebruik sql blokken voor database-queries en python (met bijvoorbeeld Pandas) voor data-analyse.
  • Project Runbooks: Stel cwd en envFile in om direct Docker-commando's of migraties uit te voeren vanuit een notitie.
  • Incident Response: Gebruik profielen (bijv. profile: prod-readonly) om veilig tools als redis-cli uit te voeren tijdens incidenten.
  • Leren programmeren: Voer korte code-snippets uit in talen als Ruby om direct het resultaat te zien.
  • Homelab beheer: Gebruik host: homelab om serverstatistieken (zoals zpool list) op te vragen zonder handmatig SSH te openen.
  • Dagelijks journaal: Combineer dagnotities met prompt blokken om AI-agents takenlijsten uit vorige dagen te laten samenvatten.

Overige Functionaliteiten

Ondersteunde Talen

  • Out-of-the-box: Python, Node, Ruby en PHP.
  • Specialisaties: redis blokken koppelen aan redis-cli via de REDIS_URL. TypeScript maakt gebruik van de ingebouwde Bun-runtime.
  • Custom: Nieuwe interpreters kunnen via één regel in de instellingen worden toegevoegd.

Notities App Functies

  • Dagelijkse notities: ⌘J opent de notitie van vandaag via een template met tokens zoals {{date}} en {{yesterday}}.
  • Workspaces: Koppel een projectmap om Markdown-bestanden direct als notities te gebruiken.
  • Live Preview: Syntax (zoals bold of links) wordt verborgen wanneer de cursor er niet in staat. Checkboxen zijn direct klikbaar.
  • Plakken: Inhoud van webpagina's, Slack of Google Docs wordt via ⌘V automatisch omgezet naar Markdown (koppen, lijsten, tabellen).
  • Navigatie: ⌘P opent notities op titel; # start een full-text search. Wikilinks ([[Titel]]) zorgen dat links blijven werken na een hernoeming.
  • Tags en Favorieten: Gebruik #hashtags of tags: in de frontmatter. Favorieten (favorite: true) worden bovenaan de zijbalk geplaatst.
  • Prullenbak: Verwijderde notities gaan naar de workspace-prullenbak en worden na 30 dagen definitief verwijderd.

Ledge CLI

De ledge CLI maakt het mogelijk om notities te beheren vanuit elke terminal.

  • Integratie: Resultaten gaan naar stdout, conversaties naar stderr.
  • Voorbeeld: git log --oneline -5 | ledge append "Release notes" voegt de laatste commits toe aan een notitie.

Licentie en Filosofie

Ledge is gratis en open source onder de Apache-2.0 licentie. Er is geen account vereist en er is geen externe database. Jouw notities zijn Markdown-bestanden op jouw computer of server, en blijven jouw eigendom.