aryansin1234/inkdown

•Updated 5 months ago

Image

595

aryansin1234/inkdown repository overview

⁠InkDown

Markdown in. Beautiful documents out.

Convert Markdown to pixel-perfect PDF and native Word DOCX documents — with a web UI, REST API, and CLI. Everything is bundled in this image: Node 20, Chromium (for PDF), and Pandoc (for DOCX). No installs required on the host.

⁠Quick Start

docker run -p 3000:3000 aryansin1234/inkdown:latest

Then open http://localhost:3000⁠ — that's it.

🍎 Apple Silicon / ARM64 Mac? The image is built for linux/amd64. Use the platform flag:
docker run --platform linux/amd64 -p 3000:3000 aryansin1234/inkdown:latest
Or build a native ARM image locally:
git clone https://github.com/Aryansin1234/InkDown.git && cd InkDown
docker build -t inkdown:local .
docker run -p 3000:3000 inkdown:local

⁠What is InkDown?

InkDown turns raw Markdown into documents you can actually share:

  ┌─────────────┐      ┌──────────────┐      ┌──────────────────┐
  │  Markdown   │ ───▶ │   InkDown    │ ───▶ │  PDF  or  DOCX   │
  │  Web · CLI  │      │  REST API    │      │  pixel-perfect   │
  │  REST API   │      │  ⚡ Engine    │      │  ready to share  │
  └─────────────┘      └──────────────┘      └──────────────────┘

Three ways to use it:

🌐 Web UI — drag & drop or paste Markdown, live preview, download the document
🔌 REST API — call from any language, any platform
⌨️ CLI — node src/cli.js input.md output.pdf

⁠Features

Feature	Details
🎨 Syntax Highlighting	190+ languages, GitHub-light theme
📊 Smart Tables	Pipe, grid, multiline tables — borders & alignment
📈 Mermaid Diagrams	Flowcharts, sequence, Gantt, pie, ER, state, class, git graph, mindmap — rendered as high-DPI PNG
📄 Page Break Control	`<!-- pagebreak -->` comments or auto-break before H1
📑 Table of Contents	Auto-generated, clickable TOC in both PDF and DOCX
🔢 Page Numbers	Footer on every page: Title — Page X / Y
➗ Math (LaTeX)	Inline $E=mc^2$ and block `$$...$$` equations via KaTeX
⚡ PDF Output	Headless Chrome via Puppeteer, A4 format, print-quality
📝 DOCX Output	Native Word documents via Pandoc — real styles, embedded images
👁️ Live Preview	Real-time Markdown preview with Mermaid rendering
🔌 REST API v1	JSON body · file upload · URL fetch
🔒 API Key Auth	Optional `INKDOWN_API_KEYS` env var
🏃 Non-root	Runs as unprivileged `inkdown` user

⁠Available Tags

Tag	Description
`latest`	Most recent stable build

⁠Usage

⁠One-liner

docker run -p 3000:3000 aryansin1234/inkdown:latest

⁠Apple Silicon / ARM64 Mac

docker run --platform linux/amd64 -p 3000:3000 aryansin1234/inkdown:latest

⁠Detached (background)

docker run -d --name inkdown --restart unless-stopped \
  -p 3000:3000 \
  aryansin1234/inkdown:latest

⁠Docker Compose

services:
  inkdown:
    image: aryansin1234/inkdown:latest
    container_name: inkdown
    restart: unless-stopped
    ports:
      - "3000:3000"
    environment:
      - NODE_ENV=production
      - PORT=3000
      # - INKDOWN_API_KEYS=your-secret-key
      # - INKDOWN_CORS_ORIGINS=https://myapp.com
    healthcheck:
      test: ["CMD", "node", "-e", "require('http').get('http://localhost:3000/api/v1/health', r => process.exit(r.statusCode === 200 ? 0 : 1)).on('error', () => process.exit(1))"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 15s

docker compose up -d

⁠With API Key (production)

docker run -d --name inkdown --restart unless-stopped \
  -p 3000:3000 \
  -e INKDOWN_API_KEYS=your-secret-key \
  aryansin1234/inkdown:latest

Pass the key in requests:

X-API-Key: your-secret-key
# or
Authorization: Bearer your-secret-key

⁠Custom Port

docker run -p 8080:8080 -e PORT=8080 aryansin1234/inkdown:latest

⁠Restrict CORS Origins

docker run -p 3000:3000 \
  -e INKDOWN_CORS_ORIGINS=https://myapp.com,https://staging.myapp.com \
  aryansin1234/inkdown:latest

⁠Environment Variables

Variable	Default	Description
`PORT`	`3000`	HTTP port the server listens on
`INKDOWN_API_KEYS`	(unset — open)	Comma-separated API keys. When set, `/api/v1/convert` requires authentication.
`INKDOWN_CORS_ORIGINS`	`*`	Allowed CORS origins. Restrict in production.
`PUPPETEER_EXECUTABLE_PATH`	`/usr/bin/chromium`	Pre-configured — no need to change
`NODE_ENV`	`production`	Node environment

⁠REST API

Base URL: http://localhost:3000/api/v1

⁠Health Check

curl http://localhost:3000/api/v1/health

{
  "status": "ok",
  "version": "1.0.0",
  "timestamp": "2026-05-16T00:00:00.000Z",
  "formats": ["pdf", "docx"]
}

⁠Convert Markdown → PDF

curl -X POST http://localhost:3000/api/v1/convert \
  -H "Content-Type: application/json" \
  -d '{"markdown": "# Hello\n\nWorld!", "format": "pdf"}' \
  --output document.pdf

⁠Convert Markdown → DOCX

curl -X POST http://localhost:3000/api/v1/convert \
  -H "Content-Type: application/json" \
  -d '{"markdown": "# Hello\n\nWorld!", "format": "docx"}' \
  --output document.docx

⁠Convert with Options

curl -X POST http://localhost:3000/api/v1/convert \
  -H "Content-Type: application/json" \
  -d '{
    "markdown": "# Report\n\n## Chapter 1\n\nContent here.",
    "format": "pdf",
    "toc": true,
    "autoBreak": true,
    "title": "My Report"
  }' \
  --output report.pdf

⁠Upload a File

curl -X POST http://localhost:3000/api/v1/convert \
  -F "[email protected]" \
  -F "format=pdf" \
  --output README.pdf

⁠Convert from URL

curl -X POST http://localhost:3000/api/v1/convert \
  -H "Content-Type: application/json" \
  -d '{"url": "https://raw.githubusercontent.com/Aryansin1234/InkDown/main/README.md", "format": "pdf"}' \
  --output README.pdf

⁠With API Key

curl -X POST http://localhost:3000/api/v1/convert \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-secret-key" \
  -d '{"markdown": "# Hello", "format": "pdf"}' \
  --output document.pdf

⁠Request Parameters

Parameter	Type	Default	Description
`markdown`	String	—	Raw Markdown content (use this or `url` or file upload)
`url`	String	—	Public HTTPS URL to a `.md` file
`file`	File	—	Multipart `.md` file upload
`format`	`pdf` \| `docx`	`pdf`	Output format
`title`	String	filename	Document title shown in PDF footer
`toc`	Boolean	`false`	Generate a Table of Contents
`autoBreak`	Boolean	`false`	Auto page-break before every H1

Response: Binary file download with Content-Disposition: attachment. On error: { "error": "...", "code": "..." }

⁠Supported Markdown Features

GFM tables — pipe, grid, multiline, simple
Task lists — - [x] done / - [ ] todo
Strikethrough — ~~text~~
Footnotes — [^1] with references
Definition lists — Term / : Definition
Math — inline $...$ and block $$...$$ via KaTeX
Mermaid diagrams — fenced ```mermaid code blocks
- Flowcharts (TD, LR), Sequence, Class, State, ER
- Gantt charts, Pie charts, Git graphs, Mindmaps
Syntax highlighting — 190+ languages via highlight.js
Page breaks —  or <div style="page-break-after: always;"></div>
Auto page breaks — optional break before every H1
Images — local and remote, auto-inlined as base64
Raw HTML — passed through to PDF, sanitized for DOCX

⁠What's Inside the Image

Component	Version	Purpose
`node:20-slim`	20 LTS	JavaScript runtime
Chromium	system (apt)	Headless PDF rendering
Pandoc	system (apt)	Native DOCX generation
Puppeteer	`^24`	Chrome automation
Mermaid	`^11`	Diagram rendering (bundled, no CDN)
marked	`^13`	Markdown → HTML parser
highlight.js	`^11`	Syntax highlighting
KaTeX	`^0.16`	LaTeX math rendering
Express	`^5`	HTTP server

Base image: node:20-slim (Debian) Exposed port: 3000 Image size: ~400 MB Architecture: linux/amd64 Runs as: non-root inkdown user

⁠Security

Runs as a non-root user (inkdown) inside the container
URL fetching blocks private IPs, loopback, and cloud metadata endpoints (169.254.x.x)
Image inlining restricted to the document's own directory — path traversal blocked
File uploads limited to 50 MB, only .md and .txt accepted
Set INKDOWN_API_KEYS to require authentication on the convert endpoint
Set INKDOWN_CORS_ORIGINS to restrict browser origins

⁠Troubleshooting

Issue	Solution
`no matching manifest for linux/arm64`	Add `--platform linux/amd64` to `docker run`
Conversion timeout	Large documents with many Mermaid diagrams may take longer
DOCX won't open in Word	Ensure you're on the latest image — includes Pandoc 3.9 compatibility patches
Port already in use	Map a different port: `-p 8080:3000`
Container exits immediately	Check logs: `docker logs inkdown`

⁠Source & Links

GitHub: github.com/Aryansin1234/InkDown⁠
Docker Hub: hub.docker.com/r/aryansin1234/inkdown⁠
Issues: github.com/Aryansin1234/InkDown/issues⁠

Made with ☕ — your documents never leave your infrastructure.

Tag summary

Recent tags

Content type

Image

Digest

sha256:05d14c93d…

Size

814.8 MB

Last updated

5 months ago

docker pull aryansin1234/inkdown