Markdown is one of those formats developers end up using almost everywhere.
README files. Documentation. Architecture notes. API docs. Project specifications. AI-generated content. Blog drafts. Changelogs. Notes written during debugging sessions.
The format itself is simple.
The workflow around it isn't always.
Sometimes you just want to open a Markdown editor, write something, see the rendered result, and export it.
Instead, many tools push you toward an account, a cloud workspace, or a larger platform before you can even start writing.
That was the problem I was trying to solve when I built Markups.
Open it. Write Markdown. See the result. Keep control of your document.
Live: markups.dev
Source: github.com/Nir-Bhay/markups
What is Markups?
Markups is an open-source, browser-based Markdown editor designed to make Markdown work feel simple again.
You can open markups.dev and start writing without downloading a desktop application or creating an account. The editor provides a split Markdown and live-preview workflow, along with features that become useful when a document stops being "just text" — diagrams, equations, code blocks, navigation, linting, templates, and export options.
The current project combines a developer-oriented editor experience with a local-first approach to document handling.
┌──────────────────────┐
│ Markdown │
│ file / document │
└──────────┬───────────┘
│
▼
┌──────────────────────┐
│ Markups │
│ Edit + Preview │
└───────┬─────┬────────┘
│ │
┌──────────┘ └──────────┐
▼ ▼
┌─────────────┐ ┌─────────────┐
│ Preview │ │ Tools │
│ Render │ │ Mermaid │
└──────┬──────┘ │ KaTeX │
│ │ Code blocks │
│ └──────┬──────┘
▼ │
┌──────────────────────────────────┘
│
▼
┌────────┬────────┬─────────┐
│ .md │ HTML │ PDF │
└────────┴────────┴─────────┘
The goal isn't to replace every development tool you already use.
It's to make the Markdown layer between those tools easier to work with.
Why I built it
The more Markdown I worked with, the more obvious the friction became.
A .md file is portable by design. You can open it in an editor, commit it to Git, send it to someone, put it in a repository, or publish it somewhere else.
So I kept asking myself:
Why should editing that file require a full cloud workflow?
I wanted a tool where the first step is simply:
Open the editor
↓
Start writing
↓
Preview the document
↓
Export / save
No onboarding flow.
No mandatory workspace setup.
No need to turn a simple Markdown file into a hosted account just to edit it.
That became one of the design principles behind Markups.
The simplest feature: you can just start writing
One of the most important decisions in Markups is also one of the easiest to explain:
You don't need to create an account just to edit Markdown.
Open markups.dev, and the editor is there.
That changes the interaction from:
Open editor
↓
Create account
↓
Verify / sign in
↓
Create workspace
↓
Create document
↓
Start writing
into:
Open markups.dev
↓
Start writing
For a lot of small documentation tasks, that's exactly what I want from a tool.
A developer-oriented editor, not just a textarea
Under the hood, Markups uses Microsoft's Monaco Editor, the same editor technology used by VS Code. That gives the editing surface a much more familiar developer feel than a basic browser text box.
The editor supports things like:
- light and dark themes
- multiple editor themes
- minimap support
- line wrapping controls
- font customization
- bracket matching
- a developer-oriented editing experience
If you already spend your day in an IDE, the editor doesn't feel completely foreign when you move over to Markdown.
Live preview changes the workflow
Writing Markdown and reading rendered Markdown are two different activities.
You need both.
Markups provides a live preview so you can edit the source and immediately see how the document is going to look.
┌─────────────────────────┬─────────────────────────┐
│ Markdown Source │ Rendered Preview │
│ │ │
│ # API Documentation │ API Documentation │
│ │ ================= │
│ ## Authentication │ Authentication │
│ │ │
│ - Bearer token │ • Bearer token │
│ - Expiration │ • Expiration │
│ │ │
└─────────────────────────┴─────────────────────────┘
The current editor supports split view as well as a single-pane workflow, synchronized scrolling, and a document mode for a more rendered-document-oriented editing experience.
Markdown support for real documentation
A Markdown editor becomes much more useful when it can handle the things developers actually put into their documents.
Markups supports common GitHub-flavored Markdown patterns such as:
- headings
- links
- lists
- tables
- task lists
- footnotes
- alert-style blocks
- code blocks
It also extends the document with:
KaTeX for math
$$
E = mc^2
$$
Mermaid for diagrams
flowchart TD
A[Developer] --> B[Markdown]
B --> C[Markups]
C --> D[Live Preview]
C --> E[Export]
D --> F[Review]Syntax-highlighted code blocks
async function getUsers() {
const response = await fetch("/api/users");
return response.json();
}
This matters because modern technical documents are rarely just paragraphs.
They contain code, architecture diagrams, tables, equations, checklists, examples, and structured notes.
Mermaid is especially useful for technical documentation
One thing I like about Markdown-based diagrams is that the diagram can live with the documentation.
For example:
flowchart LR
Client --> API
API --> Auth
Auth --> Service
Service --> DatabaseInstead of maintaining a paragraph explaining the architecture and then keeping a completely separate image somewhere else, the diagram can be part of the document's source.
Change the architecture?
Change the Markdown.
That is a very natural workflow for developers.
Math support when Markdown needs to be more technical
There are documents where plain Markdown isn't enough.
Research notes, educational content, engineering documentation, data explanations, and technical articles can all need equations.
With KaTeX support, you can write mathematical expressions directly in the document:
$$
\frac{d}{dx}x^n = nx^{n-1}
$$
The point isn't to turn Markups into a mathematics product.
It's simply to avoid having technical content break when the document needs one more layer of structure.
Export without rebuilding the document somewhere else
Another practical part of the workflow is export.
From the same document, Markups can produce:
┌─────────────┐
│ Markups │
└──────┬──────┘
│
┌─────────────┼─────────────┐
▼ ▼ ▼
Markdown HTML PDF
│ │ │
▼ ▼ ▼
.md file Web-ready Shareable
document document
The current project supports downloading Markdown, exporting to HTML, and exporting to PDF. Existing Markdown files can also be imported so you can continue working on a document you already have.
That makes the workflow useful when Markdown is the source of truth, but the final output needs to be something else.
Features I find useful once a document gets bigger
Markups isn't limited to editing and previewing.
The current project also includes features aimed at longer or more repetitive documents:
| Feature | Why it is useful |
|---|---|
| Multi-tab documents | Work on more than one document without constantly replacing the current file |
| Templates | Start common document types faster |
| Text snippets | Reuse Markdown boilerplate |
| Focus mode | Remove distractions while writing |
| Typewriter mode | Keep the active writing position visually centered |
| Word / character count | Useful for articles and documentation with size constraints |
| Reading time | Quick estimate for longer documents |
| Table of contents | Navigate large documents quickly |
| Markdown linter | Catch formatting and style issues while writing |
These are small things individually.
Together, they make Markdown feel more like a real writing environment instead of a box where you paste syntax.
Where Markups fits into a developer workflow
This is where I think the project gets more interesting.
You don't have to use Markups for everything.
It works well as a layer around workflows you already have.
1. README files
You can draft or clean up a README in Markups, review the rendered result, then save the Markdown file back into your repository.
Repository
│
└── README.md
│
▼
Markups
│
┌────┴────┐
▼ ▼
Edit Preview
│ │
└────┬────┘
▼
Save .md
│
▼
Git commit
2. Technical documentation
API docs, installation guides, contributor docs, deployment notes, internal specifications, and architecture documents are all natural Markdown use cases.
3. Architecture notes
Mermaid makes it easy to keep architecture diagrams close to the documentation itself.
4. AI-generated Markdown
This is becoming a particularly interesting workflow.
AI coding assistants can generate:
- README drafts
- implementation plans
- technical documentation
- changelogs
- issue descriptions
- architecture notes
- project specifications
But generated Markdown often still needs human review.
Markups can be used as that review layer:
AI assistant
↓
Generated Markdown
↓
Markups
↓
Review + edit + preview
↓
Final Markdown
↓
Git / Docs / Publish
The idea is simple: let AI produce a first draft, then use a human-friendly editor to make it actually yours.
5. Blog and technical article writing
Markdown is also a natural format for writing developer articles.
With live preview, a table of contents, word count, reading-time information, and export options, Markups can work as a focused writing environment before content is published elsewhere.
6. Working with unreliable internet
Because the application is built as a Progressive Web App and uses browser caching, the project is designed to continue working after the initial application load. The repository includes a PWA manifest and service worker for this behavior.
That means a weak connection does not have to be the thing that stops you from writing.
The local-first idea
A big part of Markups is not a flashy feature.
It is the architecture choice behind the workflow.
The project is designed around browser-based, local-first document handling rather than making a hosted account the center of the product.
A simplified view looks like this:
flowchart TD
U[Developer] --> B[Browser]
B --> E[Markups Editor]
E --> R[Markdown Renderer]
E --> S[(Browser Storage)]
E --> P[Live Preview]
R --> P
E --> M[Mermaid]
E --> K[KaTeX]
E --> H[Syntax Highlighting]
E --> X[Export]
X --> MD[.md]
X --> HTML[HTML]
X --> PDF[PDF]The important part is the direction of the workflow:
you start with the document, not with an account.
Privacy and document control
I wanted Markups to be useful for documents that people may not want to put into a hosted workspace simply to edit them.
The current project is built around client-side document handling and does not require an account for the core editing workflow. The project also uses browser storage for local persistence and export/save operations happen from the browser.
That gives the workflow a different feel from cloud-first editors:
Your document
│
▼
Browser
│
▼
Markups
│
├── Edit
├── Preview
├── Persist locally
└── Export
There is no mandatory hosted workspace sitting between you and the first edit.
For developers, that can be useful when working on unfinished ideas, private documentation, internal notes, or project material that simply doesn't need to live in another service.
The goal is not "your files are magically private because the app says so." The goal is to keep the architecture simple enough that the user remains close to the document.
Offline-first: what that actually means here
Markups is implemented as a Progressive Web App.
The project includes a web app manifest and service worker so the application can cache the resources required to run after the initial load.
In practical terms, the intended workflow is:
First visit
↓
Application loads
↓
Browser caches app resources
↓
You can install/bookmark it
↓
Connection disappears
↓
The app can continue working from its cached resources
This is particularly useful for the kind of editor that does not need a server round-trip just to render Markdown.
One important distinction: offline application availability is not the same thing as cloud synchronization.
Markups is not trying to become a cloud document collaboration platform. The project is deliberately much more focused than that.
Markups compared to a cloud-first workflow
There are plenty of excellent Markdown editors already.
Tools such as StackEdit and HackMD are useful for different workflows, especially when cloud synchronization and collaboration are part of the requirement.
Markups takes a different position.
| Workflow need | Markups approach |
|---|---|
| Start editing immediately | No mandatory account for the core editor workflow |
| Markdown source | First-class editing surface |
| Live rendered output | Yes |
| Mermaid diagrams | Built in |
| Math | KaTeX support |
| Code blocks | Syntax highlighting |
| Local/browser workflow | Core design direction |
| Offline-oriented use | PWA + browser caching |
| Export | Markdown, HTML, PDF |
| Open source | Yes |
| Cloud collaboration | Not the primary goal |
The comparison isn't about declaring one product universally better than another.
It is about choosing the right workflow.
If you need a collaborative cloud workspace, use a tool designed for that.
If you want a focused Markdown editor that you can open and start using, Markups is built around that experience.
A small example: from idea to technical document
Imagine you're building an API and want to document it.
You might start with:
# User API
## GET /users
Returns a list of users.
## Authentication
Use a bearer token.
http
Authorization: Bearer
## Architecture
mermaid
flowchart LR
Client --> API
API --> Auth
Auth --> UsersService
UsersService --> Database
plaintext
Then you can immediately see:
- whether your headings make sense
- whether code blocks render correctly
- whether your diagram communicates the architecture
- whether the document is readable as a finished page
And when you're done, you can keep the .md source or export the document to HTML/PDF.
That's the workflow I care about most.
Not "write Markdown because Markdown is cool."
Write Markdown because it is useful — and make the editor around it useful too.
How to get started
You don't need a complicated setup.
1. Open Markups
Go to:
2. Start writing
Open the editor and begin with Markdown on the source side.
3. Preview as you go
Use the live preview to check the rendered document while you write.
4. Import an existing file
Already have a .md file? Import it and continue from there.
5. Add richer content
Try:
- Mermaid
- KaTeX
- code blocks
- tables
- task lists
- footnotes
6. Export when you're finished
Save the Markdown source or export the document as HTML/PDF.
Useful shortcuts
| Shortcut | Action |
|---|---|
Ctrl + S |
Save Markdown |
Ctrl + P |
Export / print to PDF |
Ctrl + O |
Import Markdown |
Why open source?
Another important part of Markups is that it is open source and released under the MIT license.
That matters to me because a developer tool should be inspectable.
You can read the code.
You can understand how the application works.
You can contribute.
You can fork it.
You can adapt it for your own workflow.
Repository:
👉 https://github.com/Nir-Bhay/markups
What Markups is — and what it isn't
Markups is a focused Markdown workspace.
It is not trying to replace:
- VS Code
- GitHub
- a full documentation platform
- a real-time collaborative workspace
- your Git workflow
Instead, it sits in a much smaller space:
Write
↓
Preview
↓
Improve
↓
Export / Save
That simplicity is intentional.
What I'm exploring next
There are still plenty of areas where a Markdown editor can get better.
Some ideas I'm exploring include:
- stronger offline workflows
- better document organization
- more developer-oriented templates
- richer Markdown diagnostics
- improved import/export workflows
- better project/document management
- additional publishing workflows
These are ideas, not promises about the current release.
One of the nice things about keeping the project open source is that the roadmap doesn't have to come entirely from one person.
Final thoughts
The interesting part of Markups isn't really Markdown syntax.
Markdown already works.
The interesting part is the workflow around it.
Does writing a README need an account?
Does editing a .md file need a cloud workspace?
Does documentation always need to live inside another platform?
I don't think it has to.
Sometimes a tool should simply:
Open
↓
Write
↓
Preview
↓
Export
↓
Done.
That's the idea behind Markups.
A free, open-source Markdown editor that you can open in your browser and start using without a mandatory account.
If that matches the way you work, give it a try.
🔗 Links
Live App: https://markups.dev/
GitHub: https://github.com/Nir-Bhay/markups
And because the project is open source, feedback, issues, and contributions are always welcome.
Built for people who just want to work with Markdown.
Top comments (0)