How bloom42/markdown-ninja works
Project type and purpose
• Markdown Ninja is a full-stack, markdown-first CMS/platform to publish websites, blogs, newsletters.
• It comprises:
– A Go-based HTTP API server (cmd/mdninja-server + pkg/server + pkg/services/…)
– A Vue/TypeScript single-page app (“webapp”) served by the Go server
– A CLI tool (cmd/mdninja) for end-users to publish content
– A suite of SDKs (mdninja-go, mdninja-js) for programmatic access
– Auxiliary commands (e.g. ebook generator)
File structure
• Top‐level “cmd” directories are entrypoints: CLI, server, ebook converter.
• “pkg/server” implements REST routes, HTTP context and middlewares.
• “pkg/services” contains domain-by-domain logic (contacts, content, emails, events, organizations, store, websites, kernel, site).
• “migrations” holds SQL migration files for the Postgres database.
• “pkg/storage” wraps S3; “pkg/mailer” wraps SES.
• “pkg/worker” provides background job execution.
• “webapp” is the front-end SPA with Vue components, API client, routing and state.
• “themes” holds prebuilt front-end themes (blog, docs) that plug into the webapp.
• “mdninja-go” and “mdninja-js” are language-specific client libraries.
README for additional insights
• Purpose: publish Markdown content with a single CLI command or via the web UI.
• Key stack: Go, Vue/TS, Docker, Postgres, S3, SES, Stripe for billing, Scaleway KMS.
• Emphasizes minimal CI/CD and turnkey hosting.
Components and their interactions (to represent
a. Clients
– CLI (cmd/mdninja)
– Web SPA (webapp served at /)
– SDKs (mdninja-go, mdninja-js, pingoo-go)
b. API Server
– HTTP router & handlers (pkg/server/apiRoutes)
– Middlewares (authentication, logging, CORS, security headers)
– Handlers delegate to “pkg/services/*”
c. Services Layer
– Domain services (contacts, content, emails, events, organizations, store, websites, site, kernel)
– Each service has Repository (DB), business rules, templates (email, HTML)
d. Persistence & Infrastructure
– PostgreSQL database (migrations)
– S3-compatible object storage (assets, images)
– Email service (SES via pkg/mailer/ses)
– Stripe (billing, webhooks)
– KMS for encryption
– Worker process (pkg/worker) for background jobs (email, scheduled publishing, cleanup, etc.)
e. External integrations
– Stripe API
– SES SMTP/REST
– CDN / custom domains
Architectural patterns & design principles
• Layered (Clean) architecture:
Presentation → API → Services → Repositories → Data stores
• Hexagonal/Ports & Adapters: services under “pkg/services” depend only on repository interfaces; adapters live in “pkg/services/*/repository” and “pkg/storage”, “pkg/mailer”.
• Single responsibility: each service directory handles one domain.
• Background job queue: worker pulls tasks from the DB or queue table.
• Containerization & IaC: Dockerfiles, devcontainer.