Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
20 commits
Select commit Hold shift + click to select a range
ae75895
Merge pull request #105 from Deityhub/main
Deityhub Nov 13, 2026
f0ad6eb
fix(library): remove a folder when its last draft is deleted
Deityhub Nov 14, 2026
a73adee
Merge pull request #106 from Deityhub/fix/library-empty-folder
Deityhub Nov 14, 2026
3df8162
feat(settings): add a settings page for the editor, AI and connections
Deityhub Nov 14, 2026
43909a7
Merge pull request #107 from Deityhub/feat/settings-page
Deityhub Nov 14, 2026
60f8e0a
feat(account): change the display name and the password from settings
Deityhub Nov 14, 2026
cbc51fd
feat(settings): edit the name and password in dialogs and centre the …
Deityhub Nov 14, 2026
f6ea231
test(settings): use const for the password dialog
Deityhub Nov 14, 2026
21ef292
Merge pull request #108 from Deityhub/feat/account-name-password
Deityhub Nov 14, 2026
ae2c8e5
feat(account): change the email address with a link to the new one
Deityhub Nov 14, 2026
7ea6661
Merge pull request #109 from Deityhub/feat/account-email-change
Deityhub Nov 14, 2026
0156af7
feat(account): link and unlink GitHub and Google sign-ins
Deityhub Nov 14, 2026
6076f88
Merge pull request #110 from Deityhub/feat/account-linked-sign-ins
Deityhub Nov 14, 2026
e6fc13c
feat(search): add a search palette for drafts, commands, settings and…
Deityhub Nov 14, 2026
63968ea
feat(ui): polish the app frames, left panel strip and loading states
Deityhub Nov 15, 2026
12c827a
Merge pull request #112 from Deityhub/feat/ui-polish
Deityhub Nov 15, 2026
d6fadeb
feat(ui): list AI integrations in settings, add a page loader, keep t…
Deityhub Nov 15, 2026
ec91e89
Merge pull request #113 from Deityhub/feat/ui-follow-ups
Deityhub Nov 15, 2026
bada968
docs: rewrite the home page and guides, consolidate the docs (#114)
Deityhub Nov 16, 2026
9943027
chore(release): v0.7.0
github-actions[bot] Nov 16, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 5 additions & 3 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,10 +14,9 @@ mdstudio is built for writers, developers, technical bloggers, and documentation

Before proposing or making changes, read:

1. `docs/SYSTEM_SPEC.md`: the master source of truth (product, architecture, schema, decisions). The end-to-end use cases are in `docs/PRODUCT_SPEC.md`.
1. `docs/SYSTEM_SPEC.md`: the master source of truth (product, architecture, schema, decisions). The end-to-end use cases are in its section 1, and what is planned or not built yet is in its section 12.
2. This file: the non-negotiable invariants.
3. `roadmap.md`: milestones and pending work.
4. As needed: `docs/UI_SPEC.md` and `docs/DESIGN_SYSTEM.md` (screens and tokens), `infra/README.md` (backend blueprints), `docs/RELEASING.md` (releases and secrets).
3. As needed: `docs/UI_SPEC.md` and `docs/DESIGN_SYSTEM.md` (screens and tokens), `infra/README.md` (backend blueprints), `docs/RELEASING.md` (releases and secrets).

---

Expand Down Expand Up @@ -77,6 +76,9 @@ All backend code lives in or is scaffolded via `infra/` (see `infra/README.md`):
- **Compatibility:** Do not use Node.js standard library modules (`fs`, `path`, `crypto`, ...) in client-side code; client code must run in all browsers and on Cloudflare Workers. Node APIs are fine in `scripts/` and the Node-only `infra/` drivers.
- **Types:** Prefer clean types and deterministic state machines. The TypeScript config is strict (`exactOptionalPropertyTypes`, `noUncheckedIndexedAccess`).
- **Tailwind classes:** write them in the form Tailwind recommends (`size-4` not `h-4 w-4`, `shrink-0` not `flex-shrink-0`, `data-disabled:` not `data-[disabled]:`, `wrap-break-word` not `break-words`). `bun run tailwind:check` lists anything that is not, CI runs it, and `bun run tailwind:fix` rewrites it using Tailwind's own rules.
- **UI conventions:** every button that starts an action shows `loading` (the one pressed) or `pending` (its siblings), never a bare `disabled`; every dropdown uses the shared `Select`; action labels never end in an ellipsis. The rules and the reasons are in `docs/DESIGN_SYSTEM.md`, and a test (`loading-rules.test.ts`) enforces the first.
- **Public pages:** a guide (`content/guides/<slug>.md`) and a legal page (`content/legal/<slug>.md`) say what they are in their own front matter (slug, title, description, and `published` and `updated` as UTC moments); adding one needs no code change. Set `updated` when you change one.
- **Docs:** a change that alters what the app does, how it looks or how it is built updates `docs/SYSTEM_SPEC.md` and `docs/UI_SPEC.md` in the same change; the home copy and the FAQ live in `src/lib/site/seo-content.ts`, and `public/llms.txt` is generated from it (`bun run llms`).
- **Accessibility:** Build accessible UX by default (Radix primitives, roving focus on toolbars, labelled controls).

---
Expand Down
17 changes: 17 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,22 @@
# Changelog

## 0.7.0 (2026-11-16)

### Features

- **ui:** list AI integrations in settings, add a page loader, keep the side strip on tablets
- **ui:** polish the app frames, left panel strip and loading states
- **search:** add a search palette for drafts, commands, settings and pages (#111)
- **account:** link and unlink GitHub and Google sign-ins
- **account:** change the email address with a link to the new one
- **settings:** edit the name and password in dialogs and centre the page
- **account:** change the display name and the password from settings
- **settings:** add a settings page for the editor, AI and connections

### Fixes

- **library:** remove a folder when its last draft is deleted

## 0.6.0 (2026-11-13)

### Features
Expand Down
41 changes: 24 additions & 17 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@

<p align="center">
<strong>Write Markdown once. See exactly how it renders everywhere.</strong><br>
An open-source, local-first Markdown editor with a faithful live preview and a portability checker for GitHub, dev.to and Obsidian.
An open-source, local-first Markdown editor with a faithful live preview and a portability checker for GitHub, blogging platforms and Obsidian.
</p>

<p align="center">
Expand All @@ -30,17 +30,20 @@ mdstudio keeps your **raw Markdown as the single source of truth**. The preview
- **Faithful live preview.** Strict CommonMark and GitHub Flavored Markdown, sanitized, with syntax-highlighted code. Scrolling stays aligned line by line, and clicking a block in the preview puts the editor cursor on its source line.
- **Portability checker.** Raw HTML, local images and links, base64 images, wiki-links, `==highlights==`, math, Mermaid, trailing-space line breaks, missing alt text, unclosed tags and more. Every issue is clickable. Turn rules on or off, add publication standards (title and description length, required front matter, heading structure) and your own text or regex rules, and share them as a JSON file.
- **Target profiles.** Strict CommonMark, GFM extended, GFM without HTML, and Wiki notes. The preview, the checks and the toolbar warnings follow your choice.
- **Edit together.** Invite people by email and edit one draft at the same time, online or offline: live cursors, per-person undo, and offline edits merge when the network returns (Yjs). Up to 3 people per draft by default.
- **Review links.** Share an expiring read-only copy (1 to 7 days), public or for named people only. Signed-in readers comment on the words they select, and you resolve the comments from the editor.
- **Publish to GitHub.** Commit or open a pull request to a repository, or post a gist, with the images committed beside the file.
- **Complete formatting toolbar.** Marks, headings, lists, task lists, links, images, footnotes, rules, code blocks, tables with cell navigation, GitHub alerts, math, diagrams and HTML helpers. Fully keyboard accessible.
- **Math and diagrams.** KaTeX and Mermaid, rendered on demand, themed for light and dark.
- **Local-first and private.** Drafts autosave to your browser's IndexedDB. No account, no uploads.
- **A library that scales.** Search every draft, filter by tag, organise drafts in folders (drag and drop), and rename them without touching the text.
- **Local-first.** Drafts autosave to your browser's IndexedDB and everything works offline with no account. Anything that leaves your device (cloud drafts, share links, publishing) is a choice you make per draft.
- **A library that scales.** Search every draft and the words inside them, filter by tag, organise drafts in folders (drag and drop), and rename them without touching the text. One search (Ctrl/⌘ K) also finds commands, settings and pages.
- **Version history.** Versions are kept automatically as you write; compare any of them side by side with the current draft and restore it.
- **Works offline.** The studio keeps working with no connection and can be installed as an app.
- **Import and export.** Open `.md` files, a ZIP or a whole folder, or paste from Google Docs, Notion and the web. Export clean UTF-8 Markdown (LF endings), self-contained Markdown with embedded images, standalone HTML, or every draft at once as a ZIP.
- **Optional AI writer and inline AI actions, bring your own key.** OpenAI, Anthropic, Gemini or any OpenAI-compatible endpoint (Ollama, OpenRouter, Groq). Keys stay in session memory and requests go straight from your browser to the provider.
- **AI on your own key.** A writer for titles, descriptions and drafts, inline actions on the selection (rewrite, shorten, translate, proofread), and Fix with AI on a flagged check, always shown as a diff you accept or reject. OpenAI, Anthropic, Gemini, Ollama or any OpenAI-compatible endpoint. Keys stay in session memory and requests go straight from your browser to the provider.
- **Responsive and themed.** Split view on desktop, single pane with drawers on phones, light and dark mode.
- **Self-hostable.** One Docker container with SQLite, or Cloudflare Workers.
- **Guides.** Seven practical [guides to portable Markdown](https://mdstudio.deityhub.com/guides), written in Markdown and rendered by mdstudio itself.
- **Self-hostable.** One Docker container with SQLite, or Cloudflare Workers (D1, R2 and Durable Objects). The hosted site is the same code. An admin dashboard manages accounts, plans, limits and server settings.
- **Guides.** Practical [guides](https://mdstudio.deityhub.com/guides) on portable Markdown, reviewing, writing together and publishing, written in Markdown and rendered by mdstudio itself.

<p align="center">
<img src="docs/ui-screenshots/13_library.png" alt="The drafts library with search, tags and folders" width="440">
Expand All @@ -52,6 +55,11 @@ mdstudio keeps your **raw Markdown as the single source of truth**. The preview
<img src="docs/ui-screenshots/20_publish_github.png" alt="Publishing a draft to a GitHub repository" width="440">
</p>

<p align="center">
<img src="docs/ui-screenshots/21_settings_ai.png" alt="Settings: the AI tab listing its integrations" width="440">
<img src="docs/ui-screenshots/22_search_palette.png" alt="The search palette finding a command and a guide" width="440">
</p>

<p align="center">
<img src="docs/ui-screenshots/09_editor_dark.png" alt="mdstudio in dark mode" width="440">
<img src="docs/ui-screenshots/07_mobile_preview_view.png" alt="mdstudio on a phone" width="170">
Expand Down Expand Up @@ -96,9 +104,9 @@ The app is served on <http://localhost:3000> with data in the `mdstudio-data` vo
- **Engine.** [unified](https://unifiedjs.com): remark-parse, GFM, front matter, math, remark-rehype, rehype-sanitize, then highlighting. The output is always sanitized. All Markdown logic lives in [`src/lib/markdown/markdown.ts`](src/lib/markdown/markdown.ts).
- **Editor.** CodeMirror 6, loaded only in the browser. Editing commands are pure functions with their own tests.
- **Storage.** Raw IndexedDB behind a small `documentStore` interface.
- **Security.** Nonce-based Content-Security-Policy in production, sanitized preview, no server in the writing path.
- **Security.** Nonce-based Content-Security-Policy in production, a sanitized preview, and no server in the writing path unless you choose a cloud feature.
- **Stack.** TanStack Start, React 19, Vite, Tailwind CSS v4, Radix UI.
- **Backend blueprints.** One Drizzle SQLite schema shared by Cloudflare D1 and `better-sqlite3`, with R2 or disk storage. See [`infra/`](infra/README.md); it is activated in milestone 3.
- **Backend.** One Drizzle SQLite schema shared by Cloudflare D1 and `better-sqlite3`, with R2 or disk storage, cookie sessions, a WebSocket channel on Durable Objects (in process when self-hosted) and a Yjs room per live draft. See [`infra/`](infra/README.md).

## Development

Expand All @@ -112,23 +120,22 @@ The app is served on <http://localhost:3000> with data in the `mdstudio-data` vo
| `bun run licenses` | Audits dependency licenses against the policy |
| `bun run screenshots` | Regenerates the UI screenshots in `docs/ui-screenshots` |
| `bun run brand` | Regenerates the icons and social card |
| `bun run llms` | Regenerates `public/llms.txt` from the site copy |

Read [CONTRIBUTING.md](CONTRIBUTING.md) before opening a pull request: branch from `dev`, write the test first, and use Conventional Commits.

## Documentation

| Document | Contents |
| ------------------------------------------------------------------------------------- | --------------------------------------------------------- |
| [docs/SYSTEM_SPEC.md](docs/SYSTEM_SPEC.md) | Source of truth: product, architecture, schema, decisions |
| [docs/PRODUCT_SPEC.md](docs/PRODUCT_SPEC.md) | The end-to-end use cases |
| [docs/UI_SPEC.md](docs/UI_SPEC.md) and [docs/DESIGN_SYSTEM.md](docs/DESIGN_SYSTEM.md) | Screens and design tokens |
| [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | Modules and routes |
| [docs/RELEASING.md](docs/RELEASING.md) | Cutting a release and the required secrets |
| [roadmap.md](roadmap.md) | What is done and what is next |
| Document | Contents |
| ------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| [docs/SYSTEM_SPEC.md](docs/SYSTEM_SPEC.md) | Source of truth: product and use cases, architecture, schema, API, decisions |
| [docs/UI_SPEC.md](docs/UI_SPEC.md) and [docs/DESIGN_SYSTEM.md](docs/DESIGN_SYSTEM.md) | Every screen, and the design tokens and conventions |
| [docs/RELEASING.md](docs/RELEASING.md) | Cutting a release and the required secrets |
| [infra/README.md](infra/README.md) | The backend blueprints and how to run them |

## Roadmap

Next up: v0.1.0, then accounts with sync, hosted images and share links. Details in [roadmap.md](roadmap.md).
What is planned and what is not built yet is in the [system spec](docs/SYSTEM_SPEC.md), and what is released is in the [changelog](CHANGELOG.md).

## Contributing, security and license

Expand Down
13 changes: 11 additions & 2 deletions content/guides/commonmark-vs-github-flavored-markdown.md
Original file line number Diff line number Diff line change
@@ -1,3 +1,12 @@
---
slug: commonmark-vs-github-flavored-markdown
title: "CommonMark vs GitHub Flavored Markdown: What Differs"
description: "A clear comparison of CommonMark and GitHub Flavored Markdown: tables, task lists, strikethrough, footnotes, autolinks and alerts, and when each one matters."
order: 2
published: 2026-11-02T09:57:00Z
updated: 2026-11-16T09:41:00Z
---

CommonMark and GitHub Flavored Markdown (GFM) are the two Markdown standards you will meet most often. GFM is a strict superset of CommonMark, which means every valid CommonMark document is also valid GFM, but not the other way round. Knowing exactly what GFM adds tells you when your text stops being universally portable.

## What CommonMark is
Expand Down Expand Up @@ -53,6 +62,6 @@ Other platforms may support some of these, all of them or none. That is why a do
- Footnotes and alerts are not CommonMark and not part of the GFM specification, so check each target.
- Raw HTML is allowed by CommonMark, but GFM filters a small set of dangerous tags and most platforms sanitize far more.

## Check which flavor you are using
## See which flavor your text uses

It is easy to use a GFM feature without noticing. [mdstudio](https://mdstudio.deityhub.com/editor) lets you switch the target profile between Strict CommonMark, GitHub (GFM extended), GFM without HTML or Wiki notes. On Strict CommonMark, the checker flags every table, task list, strikethrough and footnote as a GFM extension, so you can see exactly where your text depends on one. The editor is open source and keeps your drafts in your browser. Read more in the [portable Markdown guide](https://mdstudio.deityhub.com/guides/markdown-portability).
It is easy to use a GFM feature without noticing. Open the text in [mdstudio](/editor) and switch the target to Strict CommonMark: the checker flags every table, task list, strikethrough and footnote as a GFM extension, so you can see exactly where your text depends on one. The [portable Markdown guide](/guides/markdown-portability) has the wider checklist.
68 changes: 68 additions & 0 deletions content/guides/markdown-for-blogging-platforms.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,68 @@
---
slug: markdown-for-blogging-platforms
title: Writing Markdown for Blogging Platforms
description: "Write Markdown that publishes cleanly to blogging platforms and site tools: front matter, images, raw HTML and a test post before you rely on an extra feature."
order: 4
published: 2026-11-02T13:08:00Z
updated: 2026-11-16T10:52:00Z
---

Most blogging platforms, publishing tools and static site generators let you write in Markdown, which makes it tempting to draft in your own editor and paste the result. That works well, as long as you know where each tool differs from the Markdown you write locally. This guide covers the habits that make a post publish cleanly the first time, without claiming to know the rules of any one platform: those change, and the platform's own documentation is the authority.

## They all read Markdown, and then add their own rules

Headings, lists, links, images, block quotes, tables and fenced code blocks are common ground. Beyond that, each tool adds its own features, such as embed tags for videos and social posts, shortcodes, or a plugin system, and each processes your text before showing it to readers. Some sanitize HTML, some rewrite links, some turn single newlines into line breaks. The same file can come out differently in each.

## Start with front matter

Many tools read a YAML block at the top of the file for the title, a description, tags, a date and a draft flag. The field names differ from tool to tool, so check the ones your target reads, and keep the block valid YAML:

```md
---
title: Writing portable Markdown
description: A short summary for previews and search.
tags: markdown, writing
draft: true
---
```

Keep the number of tags within what the platform allows, and keep the post marked as a draft until you have previewed it there. A tool that does not understand a field usually ignores it, but one that is strict about unknown fields may refuse the post.

## Do not rely on raw HTML

Platforms sanitize HTML, and what survives can change. Alignment wrappers, custom styles, iframes and scripts are the usual casualties. If you can express something in Markdown, do. Use a Markdown table instead of an HTML one, bold instead of a styled span, and the platform's own embed syntax for videos and social posts.

## Images need public URLs

A relative path such as an `images` folder only exists on your computer, unless the tool publishes from a repository that contains it. Upload each image through the platform's editor and use the URL it returns, or host the images somewhere stable. Add alt text to every image: it helps screen readers, and it is what readers see if the image fails to load. Avoid embedding large base64 images in the text, since they bloat the post and are often rejected.

```md
![A flow chart of the publishing process](https://example.com/images/publish-flow.png)
```

## Code blocks and highlighting

Always put a language after the opening fence. It enables syntax highlighting, and it keeps your code readable if the post is copied to another site.

````md
```ts
export const greet = (name: string) => `Hello, ${name}`;
```
````

## Test post: what to try before you rely on it

The features most likely to behave differently are the ones outside CommonMark. Before you build a post around one, publish a private or draft test post that uses each of these once, and look at the result:

- Math written with dollar signs.
- A Mermaid diagram in a fenced block.
- A footnote, a task list and a table.
- A GitHub-style alert (a block quote starting with a marker such as NOTE).
- An Obsidian wiki-link, which prints as literal brackets almost everywhere.
- Raw HTML with an alignment attribute.

Write down what works for that platform. It takes ten minutes once and saves you from finding out in front of readers. For a diagram you cannot afford to lose, use an image. See the guide to [math and Mermaid in Markdown](/guides/markdown-math-and-diagrams).

## Preview before you publish

[mdstudio](/editor) can hold the text to the stricter rules while you write. Choose the GFM without HTML target: raw HTML is reported as an error there, and the checker also catches local images, wiki-links, math, Mermaid and trailing-space line breaks, each with a click to jump to the line. If your tool builds pages from a Git repository, you can also publish the draft straight to it as a commit or a pull request. For a wider checklist, read the [portable Markdown guide](/guides/markdown-portability).
Loading
Loading