Markopolis

Open-source Markdown publishing, honestly reviewed. What you actually get when you run your own Obsidian Publish replacement.

TL;DR

• What it is: Open-source (MIT) web app and API server that turns a folder of Markdown files into a website. The author’s own description: “Self-hosted Obsidian publish with an API to extend functionality” [1].
• Who it’s for: Obsidian users who want to publish notes online without paying for Obsidian Publish or surrendering data to a third-party server. Also developers who want a Markdown backend they can build custom frontends against.
• Cost savings: Obsidian Publish costs $8/month (personal) or $16/month (commercial). Markopolis on a $5 VPS is ~$5/month. The delta is modest ($36–48/year), but you also own your infrastructure and get an API.
• Key strength: Minimal setup and a genuine REST API over your notes — not just a static site generator, but a queryable Markdown backend you can build tooling on top of.
• Key weakness: Early-stage project (181 GitHub stars), no access controls beyond a single API key, and limited community resources when things go wrong.

---

What is Markopolis

Markopolis is a web app and API server that takes a folder of Markdown files and serves them as a website. Point it at your notes directory, run one CLI command to push files, and every note is immediately available as a URL. No build step, no static generation — files render on push.

The project’s GitHub description is terse: “Markdown Programmable Interface.” The developer, Rishikanth, is more direct in the r/selfhosted launch thread: he built it because he wanted to share notes online without being locked into the Obsidian ecosystem [1]. He was using Obsidian for note-taking, found Obsidian Publish’s subscription friction, and more importantly found that once your notes are on Obsidian Publish you can’t programmatically interact with them. Markopolis solves that by exposing a REST API over your notes — every Markdown element (frontmatter, body, backlinks, todos, equations) is accessible via endpoint.

The database layer runs on PocketBase (embedded, no separate database server to manage), and the whole stack ships as a single Docker Compose file. The documentation website at markopolis.app runs on Markopolis itself, which functions as a live demo.

As of this review the repository has 181 GitHub stars. That’s niche-but-real: smaller than tools like Quartz or Obsidian, but larger than the dozens of abandoned Markdown-to-web experiments on GitHub. The author explicitly stated in the launch thread that he relies on Markopolis for his own notes system and will keep maintaining it regardless of external interest [1].

---

Why people choose it

The direct competition for Markopolis is narrow: Obsidian users who want to publish notes online and are choosing between Obsidian Publish and something self-hosted. The r/selfhosted announcement [1] reveals what resonates with that audience.

No vendor lock-in. Obsidian Publish hosts your content on Obsidian’s servers. You can’t query your own content programmatically, customization is limited to CSS snippets, and your publishing workflow depends on Obsidian’s continued operation. Markopolis is plain files on your own server, queryable however you want.

The API is the actual differentiator. Most “share your Obsidian vault” tools are static site generators — you get HTML output and nothing queryable. Markopolis exposes the Markdown structure itself as an API. That means you can build on top of it: a custom search interface, a backlink graph, a mobile reader, scripts that query todos across your entire vault. The FastAPI backend generates its own Swagger documentation, so the API surface is self-documenting.

Transparent about limitations. When Markopolis launched, the author listed explicit caveats: no mobile support yet, no image handling, no file deletion via CLI. He fixed the mobile layout the same day after community feedback [1]. That kind of honest early-stage communication is more useful than polished marketing — you know what you’re signing up for.

What you won’t find is a deep bench of independent reviews, because the tool is genuinely early-stage. The community coverage is a single r/selfhosted thread. The analysis below draws from that thread, the README, and the project’s own documentation.

---

Features

Based on the README and the r/selfhosted discussion [1]:

Publishing:

• Single markopolis push CLI command uploads Markdown files to the server
• Instant rendering — no build step, files are live immediately after push
• Docker image available at ghcr.io/rishikanthc/markopolis:latest

Markdown compatibility:

• Obsidian Markdown flavor: callouts, backlinks, LaTeX equations, code highlighting
• Todo items rendered correctly
• Dark and light mode toggle

Search:

• Full-text search across the entire vault
• Fuzzy search

REST API:

• FastAPI-based with auto-generated API documentation (Swagger UI built in)
• Endpoints for different Markdown elements: frontmatter, body sections, backlinks, todos
• API key authentication (set via environment variable)
• Designed for building custom frontends — the bundled web UI uses the same API

Extensibility:

• “Bring your own frontend” mode — skip the bundled UI entirely and query the API directly [README][1]
• The markopolis.app documentation site demonstrates this in production

Infrastructure:

• PocketBase as embedded database — no external DB container required
• Single Docker Compose deployment
• Persistent storage via a mounted volume
• Python CLI tool installable via pip (Python 3.12+ required)
• Site title and caption text configurable via environment variables

---

Pricing: SaaS vs self-hosted math

Markopolis has no paid tier. MIT license, self-hosted only.

What you’d be replacing — Obsidian Publish:

• Personal: $8/month (~$96/year)
• Commercial: $16/month (~$192/year)
• Data on Obsidian’s servers, no API, limited customization

Self-hosting Markopolis:

• Software: $0
• VPS (Hetzner CX11, 2 GB RAM): ~$4–5/month
• Annual cost: ~$48–60/year

Yearly savings vs. Obsidian Publish personal: $36–48/year. That’s not the dramatic math you see comparing Zapier to self-hosted automation — the dollar difference is modest. The more compelling argument is the API access and data sovereignty, not the savings.

If you’re already running a VPS for other services, Markopolis’s marginal cost is effectively zero. The Docker Compose stack is lightweight enough to run alongside other containers on a shared node without meaningful resource impact.

Time cost: first setup takes 30–60 minutes for someone comfortable with Docker. CLI install and first publish: another 10–15 minutes. Ongoing maintenance: the README describes it as “requires very little to no maintenance,” and given PocketBase + Docker, that claim is plausible — there’s no database to tune and no build pipeline to manage.

---

Deployment reality check

The setup story is genuinely simple. The docker-compose file in the README is 20 lines. You need:

• A Linux server with Docker and docker-compose
• A domain and reverse proxy (Caddy or nginx) for HTTPS
• Python 3.12+ locally for the CLI tool

Environment variables to configure: PocketBase admin credentials, an API key, site title, and three caption strings. Nothing unusual.

What can go wrong:

The original r/selfhosted launch [1] documented real rough edges. No image support on day one. No file deletion via CLI — you could add files but not remove them. Mobile layout was broken at launch (fixed within hours after community feedback). These were acknowledged and addressed quickly, but they signal a project where the changelog matters before you commit to a workflow. Verify the current state of image support and file deletion against the current changelog before deploying.

The version: '3.8' in the sample docker-compose is deprecated in newer Docker Compose — it works but produces warnings. Cosmetic.

The API key is set in plaintext environment variables. There’s no user management, no roles, no per-note access levels — anyone with your API key has full write access. For a personal notes server this is acceptable. For anything shared with a team, you’d need to handle access control at the reverse proxy layer yourself.

PocketBase as the database is unconventional. It removes the need for a separate PostgreSQL container, which simplifies setup. The trade-off is smaller community knowledge when database issues arise, and a different mental model for backups than most self-hosters expect.

The README includes a candid versioning note: “I have still not streamlined the process yet” — v2.0.0 involved fast-forwarding Docker versioning to match the Python package [README]. This matters if you’re running automated upgrades.

Realistic setup time: 30–45 minutes for a developer with Docker experience. For someone new to Docker: budget 2–3 hours including domain and reverse proxy setup.

---

Pros and Cons

Pros

• Actual MIT license. No usage restrictions, no “Fair-code” commercial limitations, no vendor agreements. Fork it, embed it, build a product on top of it [README].
• REST API over your notes. Not a static site generator — a queryable Markdown backend. Every note element accessible via endpoint with auto-generated Swagger docs [README][1].
• Minimal deployment. One Docker Compose file, PocketBase bundled, no external database. Deployed in under an hour [README].
• Obsidian-compatible Markdown rendering. Callouts, backlinks, LaTeX equations, code highlighting work correctly [README][1].
• Custom frontend support. Use Markopolis as a pure backend, build any UI you want [README][1].
• Self-dogfooded. The documentation site runs on Markopolis. The developer uses it for his own notes. That’s the most durable long-term maintenance signal for a solo project [1].
• Honest about limitations. Early-stage issues were listed upfront and addressed quickly after community feedback [1].

Cons

• 181 GitHub stars. Small community, limited Stack Overflow presence, limited third-party integrations, one maintainer.
• No access controls beyond a single API key. No user accounts, no per-note privacy, no roles. Everything visible to anyone who loads the URL, or nothing is [README]. Fine for personal publishing, limiting for anything collaborative.
• No native image hosting. Images required external hosting at launch; verify current status in the changelog before relying on image-heavy notes [1].
• File deletion pain point. CLI didn’t support deleting notes in the initial release [1]. Confirm this is resolved in the current version before building a workflow around content removal.
• Python 3.12+ required locally. Adds a setup prerequisite that may conflict with existing Python environments [README].
• PocketBase is unfamiliar to most self-hosters. Capable but less documented than PostgreSQL. Backups and migrations work differently than most people expect.
• No multi-user publishing. One vault, one admin. No concept of multiple contributors with separate permissions.
• Evolving versioning. The project is transparent about not having stabilized its release process [README]. Factor this in for automated upgrade pipelines.

---

Who should use this / who shouldn’t

Use Markopolis if:

• You use Obsidian and want a self-hosted way to publish notes online without Obsidian Publish’s $8–16/month subscription.
• You want programmatic access to your notes — backlink queries, todo extraction, custom frontends — and need an API to build against.
• You’re comfortable with Docker and can set up a reverse proxy, or you’ll pay someone to do it once.
• Solo personal project from a solo developer is acceptable risk for your use case.

Skip it if:

• You need team collaboration — multiple contributors pushing notes with separate access levels.
• You need per-note privacy controls (some notes public, some private, some invite-only).
• You want a production-grade CMS with commercial support, large community, and enterprise reliability.
• Your notes aren’t in Obsidian Markdown flavor — Markopolis is specifically tuned for Obsidian syntax.
• You want zero server maintenance — a static site generator (Quartz) deployed to GitHub Pages gives you a running site with no infrastructure to manage.

---

Alternatives worth considering

• Quartz — Static site generator built for Obsidian vaults. No server required, deploys to GitHub Pages for free, large community, polished output. No REST API. Choose Quartz if you want publishing without server management; choose Markopolis if you need the API.
• Obsidian Publish — The official option. Easiest setup, clean UI, mobile-optimized. $8–16/month, no API, data on Obsidian’s servers. The direct product Markopolis replaces.
• Perlite — Another Docker-based Obsidian vault publisher. Similar concept, older project, no API.
• BookStack — Mature self-hosted wiki with strong access controls and team support. More opinionated structure (shelves/books/pages), not Obsidian-native. Better for teams than for personal notes.
• Wiki.js — Self-hosted wiki with Markdown support, PostgreSQL-backed, solid RBAC. More complex to deploy. Better for knowledge bases than personal vault publishing.
• Silverbullet — Self-hosted Markdown personal knowledge tool with its own query language. Closer to Obsidian itself than to a publishing platform.

For someone specifically replacing Obsidian Publish, the realistic shortlist is Markopolis vs. Quartz. Quartz wins if you want static output with zero server maintenance. Markopolis wins if you want the API and are willing to run a container.

---

Bottom line

Markopolis does one thing clearly: it turns a folder of Obsidian Markdown files into a website with a queryable API behind it. The MIT license, single-file Docker deployment, and embedded PocketBase database mean there’s nothing to pay and not much to maintain. The REST API is the real reason to choose it over static generators — it’s what makes Markopolis a backend you can build tooling against, not just a way to get notes into a browser.

The honest caveat is maturity. A solo developer, 181 stars, and a candid README about versioning inconsistencies tells you this is a project you adopt because it fits your specific needs, not because it’s the safe institutional choice. The developer uses it himself and has been responsive to community feedback — that’s the most reliable signal for a personal open-source project. If that risk profile works for you and you’re paying for Obsidian Publish, the math and the data ownership argument are both in Markopolis’s favor.

---

Sources

1. MLwhisperer (Rishikanth), r/selfhosted — “Introducing Markopolis: A self-hosted app and API server for serving Markdown files” (Aug 2024). https://www.reddit.com/r/selfhosted/comments/1es1rg3/introducing_markopolis_a_selfhosted_app_and_api/

Primary sources:

• GitHub repository and README: https://github.com/rishikanthc/markopolis (181 stars, MIT license)
• Official documentation / live demo: https://markopolis.app