English | 한국어
Looking for an open-source Obsidian alternative built around AsciiDoc?
Metis is a local-first desktop note-taking app and personal knowledge base with an AsciiDoc editor. It keeps standard .adoc files on your device as the source of truth, so your notes and documentation remain plain text, portable, versionable with Git, and usable with other AsciiDoc tools.
Metis is designed for offline-friendly note-taking and structured documentation, with your files remaining under your control.
-
Local-first and file-based: Work directly with AsciiDoc files stored in folders you control.
-
Open source and tool-independent: Your documents remain usable outside Metis with Git, text editors, and existing AsciiDoc tools.
-
Structured knowledge: Use standard AsciiDoc features such as sections, attributes,
xref, andincludeto structure, compose, and reuse documents. -
Built for long-lived documents: Keep notes and documentation readable, reusable, and portable even if your tools change.
Metis is inspired by the local-file workflow that Obsidian users value, while using standard AsciiDoc for richer document structure, composition, and reuse.
Knowledge should remain in the user’s files, and tools should help users work with it. Metis aims to provide an AsciiDoc-based knowledge environment where documents remain readable, editable, and reusable even after users stop using the app.
The following principles guide implementation and feature decisions. Document meaning and portability take priority when adding convenience features.
-
AsciiDoc source first: Respect its syntax and semantics, and avoid custom syntax where the standard can express the content. Derived data, such as search indexes and graphs, must be rebuildable from the source.
-
Files and ownership first: Use local plain text files as the foundation of knowledge. The same documents should work with other editors, Git, and AsciiDoc tools.
-
Meaning and reuse: Prioritize document meaning over presentation. Use
include, attributes, andxrefto compose and reuse documents. -
Extensions that preserve the source: Design plugins and AI to assist document work. Knowledge must remain readable and durable when those features are removed.
The principles above guide development priorities and decisions.
Metis is a desktop app built with Electron, React, and TypeScript. npm workspaces manage the app and shared packages.
| Requirement | Details |
|---|---|
Node.js |
|
npm |
11.19.0 was used for existing local validation; install using the root |
Operating system |
Locally validated on Windows x64. CI is configured for macOS and Linux, but execution has not yet been validated |
Runtime environment |
A desktop environment capable of displaying Electron windows. Network access is required for the initial dependency and Electron installation |
Run all commands from the repository root. Basic usage requires no separate .env file, external server, or database configuration.
npm ci
npm startnpm start builds the app and launches Electron. Select Open folder (폴더 열기) to open a folder containing AsciiDoc documents, or start with New workspace (새 작업 공간). Use New document (새 문서) to create a document in the workspace.
To build without launching the app:
npm run buildBuild output is written to apps/desktop/dist/. There is currently no development server, watch mode, or HMR command. After editing the source, close the running app and run npm start again.
npm run check
npm run test:desktop:corePRs run npm run check on Windows, macOS, and Linux. Core GUI scenarios remain available for local and manual Full validation. PRs do not package the application or run GUI suites.
| Command | Purpose |
|---|---|
|
Type checking, unit tests, tooling tests, and build |
|
Core document flow against the built development app |
|
Full development GUI suite: 31 existing scenarios plus the core flow |
|
The same full suite against the latest packaged app |
GUI tests do not build the app. Run the check or build command first. Evidence is saved under .pre04-runs/core-/ and .pre04-runs/integration-/. Linux uses Xvfb for GUI tests.
npm run package
npm run test:integration:packagedpackage includes a build and creates an application folder for the current host OS and architecture under .pre04-runs/package-*/out/. It does not include an installer, signing, or automatic updates. The latest package staging path is recorded in .pre04-runs/latest-package.txt, which packaged integration tests read automatically.
To launch the packaged app directly from Windows PowerShell:
$metisPackage = Get-Content .pre04-runs/latest-package.txt
& "$metisPackage/out/Metis-win32-x64/Metis.exe"This example targets Windows x64. On Linux, run packaged GUI tests with xvfb-run -a npm run test:integration:packaged.
Development uses main with optional short-lived branches and PRs. Small changes can be pushed directly to main; PRs are useful when a review or automatic Core checks are wanted. Branch protection is not required by this workflow.
| Workflow | Trigger | Checks |
|---|---|---|
Desktop Core |
PR opened, updated, or reopened against |
|
Desktop Full |
Manual only |
Core, development integration, packaging, and packaged integration on all three OSes |
Desktop release |
Manual only, from |
Automatic version increment, Core, packaging, existing security verification, and publication |
Pushing to main or pushing a tag does not trigger validation or a release. Full is optional and is not a prerequisite for merging or releasing.
In GitHub → Actions → Desktop Full → Run workflow, leave pr_number empty to validate main, or enter an open PR number targeting main to validate its merge commit. The workflow resolves one commit SHA for all three OSes. Invalid, closed, or conflicting PRs fail before validation starts. Full results are available in Actions; this workflow is not a required PR check.
To release, select Actions → Desktop release → Run workflow, choose branch main, and choose bump:
| Increment | Example from 0.2.3 |
|---|---|
|
|
|
|
|
|
The workflow updates the root and workspace package versions and root lockfile together. It does not change experiment packages or dependency versions. Every OS packages the same prepared version commit. The existing ZIP assets, checksums, release notes, and VirusTotal policy are retained: initial, minor, and major releases require a scan; patch releases skip it. Scans require the VIRUSTOTAL_API_KEY repository secret.
The version commit and vX.Y.Z tag are pushed atomically only after all packaging and security checks pass. If main changes before that push, the run stops; start a new manual release. Release runs are serialized. Publication needs contents: write and repository rules that allow the workflow to push the version commit and tag.
Publication creates a draft, uploads and verifies its assets, then makes it public. If publishing fails after the push, use Re-run failed jobs on the same run. This reuses the exact candidate and tag without another version increment, resumes an incomplete draft, and verifies any existing public Release instead of creating a duplicate. Candidate and package artifacts are kept for 14 days, so retry within that period. Re-running all jobs starts preparation again and is not the recovery procedure after a successful push.
Metis respects and draws inspiration from Obsidian and AsciiDoc.
Obsidian is an important reference for Metis’s approach to local-first work, user-owned knowledge, connections and exploration between documents, and extensible workflows. We aim to learn from the experience it offers people building and connecting their own knowledge.
AsciiDoc provides the foundation for Metis’s document philosophy and source format. We value meaningful plain text, the separation of content and presentation, and document structure, composition, and reuse. We aim to keep documents usable with existing AsciiDoc tools.
We thank the developers and contributors who have built and sustained both projects and their ecosystems. Inspired by their work, Metis aims to create a knowledge workspace that stays true to AsciiDoc.
See Git strategy for optional PRs, labels, manual validation, and release recovery.