diff --git a/AGENTS.md b/AGENTS.md index a5c465b..c5e7aec 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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). --- @@ -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/.md`) and a legal page (`content/legal/.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). --- diff --git a/README.md b/README.md index 2ea2752..a9b7e20 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@

Write Markdown once. See exactly how it renders everywhere.
- 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.

@@ -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.

The drafts library with search, tags and folders @@ -52,6 +55,11 @@ mdstudio keeps your **raw Markdown as the single source of truth**. The preview Publishing a draft to a GitHub repository

+

+ Settings: the AI tab listing its integrations + The search palette finding a command and a guide +

+

mdstudio in dark mode mdstudio on a phone @@ -96,9 +104,9 @@ The app is served on 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 @@ -112,23 +120,22 @@ The app is served on 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 diff --git a/content/guides/commonmark-vs-github-flavored-markdown.md b/content/guides/commonmark-vs-github-flavored-markdown.md index 3007927..cb656d4 100644 --- a/content/guides/commonmark-vs-github-flavored-markdown.md +++ b/content/guides/commonmark-vs-github-flavored-markdown.md @@ -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 @@ -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. diff --git a/content/guides/markdown-for-blogging-platforms.md b/content/guides/markdown-for-blogging-platforms.md new file mode 100644 index 0000000..0c306d2 --- /dev/null +++ b/content/guides/markdown-for-blogging-platforms.md @@ -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). diff --git a/content/guides/markdown-for-devto-and-hashnode.md b/content/guides/markdown-for-devto-and-hashnode.md deleted file mode 100644 index 12a2fb9..0000000 --- a/content/guides/markdown-for-devto-and-hashnode.md +++ /dev/null @@ -1,55 +0,0 @@ -dev.to and Hashnode both let you write posts 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 platform differs from the Markdown you write locally. This guide covers the habits that make a post publish cleanly the first time. - -## Both are Markdown, with their own rules - -dev.to and Hashnode follow common Markdown conventions: headings, lists, links, images, block quotes, tables and fenced code blocks. Each adds its own features on top, such as embed tags for videos and social posts, and each processes your text before showing it to readers. The details change over time, so treat the points below as habits rather than guarantees, and check the platform's current editor guide for anything unusual. - -## Start with front matter - -dev.to reads a YAML block at the top of the post, which sets the title, tags and publishing state: - -```md ---- -title: Writing portable Markdown -published: false -description: A short summary for previews and search. -tags: markdown, writing ---- -``` - -Keep the block valid YAML, keep tags to the number the platform allows, and set `published: false` until you have previewed the post. Hashnode takes much of this from its editor settings instead, so check how it handles imported metadata. - -## Do not rely on raw HTML - -Both 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 tweets. - -## Images need public URLs - -A relative path such as an `images` folder only exists on your computer. 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}`; -``` -```` - -## Things that often do not render - -- Math written with dollar signs may show as plain text. -- Mermaid diagrams written in a fenced block may show as code rather than a diagram. -- Obsidian wiki-links print as literal brackets. -- Footnotes and GitHub-style alerts may not be supported. - -Check each against the platform before you rely on it, and prefer an image for diagrams you cannot afford to lose. See the guide to [math and Mermaid in Markdown](https://mdstudio.deityhub.com/guides/markdown-math-and-diagrams). - -## Preview before you publish - -The fastest safeguard is to check the post against the rules of your target before you paste it. In [mdstudio](https://mdstudio.deityhub.com/editor), choose the GFM without HTML profile. 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. The editor is open source and keeps drafts in your browser. For a wider checklist, read the [portable Markdown guide](https://mdstudio.deityhub.com/guides/markdown-portability). diff --git a/content/guides/markdown-images.md b/content/guides/markdown-images.md index d695d0f..4404621 100644 --- a/content/guides/markdown-images.md +++ b/content/guides/markdown-images.md @@ -1,3 +1,12 @@ +--- +slug: markdown-images +title: "Markdown Images: Paths, Alt Text and Portability" +description: "How to add images in Markdown so they show up everywhere: relative paths, hosted URLs, base64 data URIs, alt text and the mistakes that break previews." +order: 6 +published: 2026-11-02T15:49:00Z +updated: 2026-11-16T11:46:00Z +--- + Images are the most common reason a Markdown post looks broken after publishing. The text copies perfectly, and then every picture shows as a missing icon. The cause is almost always the path, and the fix is to understand where each kind of image link actually works. ## The basic syntax @@ -14,7 +23,7 @@ You can add an optional title in quotes after the address. It usually shows as a 1. **A hosted URL.** An absolute web address works anywhere the image is reachable. This is the most portable choice. 2. **A relative path.** A path such as `images/chart.png` only works when the Markdown file and the image sit in the same place the renderer expects. It works in a repository README and in many static site generators. It fails when you paste the text into another site. -3. **A platform upload.** On sites like dev.to, you upload through the editor and it gives you a hosted URL. Use that URL in the text. +3. **A platform upload.** Many publishing tools let you upload through their own editor and give you a hosted URL. Use that URL in the text. 4. **A base64 data URI.** The image data is embedded in the text itself. It is self-contained, but it makes the file huge and many platforms reject or strip it. ## Why local paths fail @@ -40,4 +49,4 @@ Alt text is the description shown when an image fails to load, and what screen r ## Find broken image links before you publish -[mdstudio](https://mdstudio.deityhub.com/editor) flags local image paths, embedded base64 images and images with missing alt text, with a click to jump to each one. When you insert an image, the dialog requires alt text. You can also export a self-contained Markdown or HTML file that embeds your local images, so the document works on its own. The editor is open source and keeps your drafts in your browser. For the wider picture, read the [portable Markdown guide](https://mdstudio.deityhub.com/guides/markdown-portability). +[mdstudio](/editor) flags local image paths, embedded base64 images and images with missing alt text, with a click to jump to each one, and its insert-image dialog will not accept an empty alt text. When a draft has to travel as one file, export a self-contained Markdown or HTML file that embeds the local images. When you publish to GitHub, the images are committed beside the file. On a self-hosted install it can also host the images for you and rewrite the paths. For the wider picture, read the [portable Markdown guide](/guides/markdown-portability). diff --git a/content/guides/markdown-line-breaks.md b/content/guides/markdown-line-breaks.md index 9164483..24d5cc0 100644 --- a/content/guides/markdown-line-breaks.md +++ b/content/guides/markdown-line-breaks.md @@ -1,3 +1,12 @@ +--- +slug: markdown-line-breaks +title: Markdown Line Breaks and Paragraphs Explained +description: "How line breaks work in Markdown: paragraphs, soft breaks and hard breaks, why trailing spaces are fragile, and which method renders the same everywhere." +order: 5 +published: 2026-11-02T14:31:00Z +updated: 2026-11-16T11:17:00Z +--- + Line breaks are one of the most confusing parts of Markdown. You press Enter, and nothing happens in the preview, or everything runs together, or it works on one site and not another. The behavior is actually well defined, and once you know the rules you can pick the method that survives every platform. ## Paragraphs, soft breaks and hard breaks @@ -49,4 +58,4 @@ Some editors turn every newline into a break to feel friendlier. That makes the ## Catch fragile breaks automatically -[mdstudio](https://mdstudio.deityhub.com/editor) renders soft breaks the way CommonMark defines them, so single newlines do not turn into breaks in the preview. Its portability checker also flags trailing-space line breaks, so you can replace them before an editor strips them. The editor is open source and keeps your drafts in your browser, unless you want to sync it to the cloud. For related pitfalls, read the [portable Markdown guide](https://mdstudio.deityhub.com/guides/markdown-portability). +[mdstudio](/editor) renders soft breaks the way CommonMark defines them, so a single newline does not turn into a break in the preview. Its checker also flags trailing-space line breaks, so you can replace them with a backslash before an editor strips them. For related pitfalls, read the [portable Markdown guide](/guides/markdown-portability). diff --git a/content/guides/markdown-math-and-diagrams.md b/content/guides/markdown-math-and-diagrams.md index 66fa199..ad62588 100644 --- a/content/guides/markdown-math-and-diagrams.md +++ b/content/guides/markdown-math-and-diagrams.md @@ -1,3 +1,12 @@ +--- +slug: markdown-math-and-diagrams +title: "Math and Mermaid Diagrams in Markdown: Where They Work" +description: "Where LaTeX math and Mermaid diagrams render in Markdown: GitHub and Obsidian support them, other platforms do not. How to write them and what to do instead." +order: 7 +published: 2026-11-02T16:36:00Z +updated: 2026-11-16T12:09:00Z +--- + LaTeX math and Mermaid diagrams are two of the most useful extensions to Markdown, and two of the least portable. They render beautifully on some platforms and show up as raw source on others. This guide shows how to write them and where they work, so you can decide when to use them. ## Math in Markdown @@ -40,9 +49,9 @@ Mermaid supports flowcharts, sequence diagrams, class diagrams, state diagrams, | GitHub | Yes | Yes | | Obsidian | Yes | Yes | | Strict CommonMark | No | No | -| dev.to and Hashnode | Not from plain syntax | Not from plain syntax | +| Blogging platforms and site generators | Depends on the platform | Depends on the platform | -Some platforms offer their own non-standard embed tags for math or diagrams. Those do not work anywhere else, which is the trade-off to weigh. +Some platforms offer their own non-standard embed tags for math or diagrams, and others need a plugin or a setting. Check the one you publish to with a test post before you rely on it. Embed tags do not work anywhere else, which is the trade-off to weigh. ## What to do when the target does not support them @@ -59,4 +68,4 @@ Rendering user-provided math and diagrams carries some risk, since both are pars ## Preview them against your target -[mdstudio](https://mdstudio.deityhub.com/editor) renders math with KaTeX and diagrams with Mermaid in strict mode, in light and dark themes, and shows them only for the profiles whose platforms support them. On the GFM without HTML or Strict CommonMark profile, the checker warns that math and Mermaid are not portable, and the toolbar marks the tools that the target will not render. The editor is open source and keeps your drafts in your browser. For more on compatibility, read the [portable Markdown guide](https://mdstudio.deityhub.com/guides/markdown-portability). +[mdstudio](/editor) renders math with KaTeX and diagrams with Mermaid in strict mode, in light and dark themes, and only for the targets that support them. On GFM without HTML or Strict CommonMark the checker warns that math and Mermaid are not portable, and the toolbar marks the tools that target will not render. For more on compatibility, read the [portable Markdown guide](/guides/markdown-portability). diff --git a/content/guides/markdown-portability.md b/content/guides/markdown-portability.md index f2dc8bf..230e964 100644 --- a/content/guides/markdown-portability.md +++ b/content/guides/markdown-portability.md @@ -1,4 +1,13 @@ -Markdown looks like one language, but it is really a family of dialects. The same file can render perfectly on GitHub, lose a diagram on dev.to and print raw brackets in a static site generator. This guide explains why that happens and gives you a checklist for writing Markdown that renders the same everywhere. +--- +slug: markdown-portability +title: "Portable Markdown: Why It Renders Differently Everywhere" +description: Why the same Markdown looks different on GitHub, blogging platforms and Obsidian, and a checklist for making your writing render the same on every platform. +order: 1 +published: 2026-11-02T08:42:00Z +updated: 2026-11-16T09:14:00Z +--- + +Markdown looks like one language, but it is really a family of dialects. The same file can render perfectly on GitHub, lose a diagram on a blogging platform and print raw brackets in a static site generator. This guide explains why that happens and gives you a checklist for writing Markdown that renders the same everywhere. ## Why the same Markdown renders differently @@ -6,7 +15,7 @@ The original Markdown description left many details open, so every tool made its - GitHub adds alerts, math, Mermaid diagrams and footnotes. - Obsidian adds wiki-links, embeds, highlights and callouts. -- dev.to and Hashnode add their own front matter, embed tags and sanitizing rules. +- Blogging platforms add their own front matter, embed tags and sanitizing rules. - Static site generators each add shortcodes, plugins or MDX. Your text is only portable if every platform you care about understands every construct in it. @@ -14,10 +23,10 @@ Your text is only portable if every platform you care about understands every co ## The six things that break most often 1. **Raw HTML.** Platforms sanitize HTML differently. A `div` with an alignment attribute may survive on GitHub and be stripped elsewhere. Prefer Markdown for everything Markdown can express. -2. **Local images.** An image link like `images/diagram.png` works on your machine and nowhere else. Use a hosted URL or upload the image to the platform. See the [guide to Markdown images](https://mdstudio.deityhub.com/guides/markdown-images). +2. **Local images.** An image link like `images/diagram.png` works on your machine and nowhere else. Use a hosted URL or upload the image to the platform. See the [guide to Markdown images](/guides/markdown-images). 3. **Wiki-links.** Obsidian links such as the double-bracket form below are meaningless outside Obsidian and print as literal text. -4. **Math and diagrams.** LaTeX math and Mermaid diagrams render on GitHub and Obsidian, but many other places show the raw source. See [math and Mermaid in Markdown](https://mdstudio.deityhub.com/guides/markdown-math-and-diagrams). -5. **Line breaks.** Whether a single newline becomes a visible break depends on the platform. See [Markdown line breaks](https://mdstudio.deityhub.com/guides/markdown-line-breaks). +4. **Math and diagrams.** LaTeX math and Mermaid diagrams render on GitHub and Obsidian, but many other places show the raw source. See [math and Mermaid in Markdown](/guides/markdown-math-and-diagrams). +5. **Line breaks.** Whether a single newline becomes a visible break depends on the platform. See [Markdown line breaks](/guides/markdown-line-breaks). 6. **Extensions.** Tables, task lists, footnotes, strikethrough and alerts are not part of strict CommonMark. ```md @@ -37,8 +46,6 @@ Before you publish, run through this list: - Avoid trailing-space line breaks, which editors often strip. A backslash at the end of the line is clearer. - Open the result on the target platform, or in a preview that follows its rules, before you hit publish. -## Check it automatically - -Reading a checklist is slow and easy to forget. [mdstudio](https://mdstudio.deityhub.com/editor) is an open-source Markdown editor built around this problem. Choose a target profile (Strict CommonMark, GitHub (GFM extended), GFM without HTML or Wiki notes), and its portability checker flags raw HTML, local images, wiki-links, math, Mermaid, trailing-space breaks and more, with a click to jump to each one. The preview shows what that platform renders, with no preview-only tricks, so what you see is what ships. +## Let the editor do the checking -Your drafts stay in your browser, there is no account requirement unless you want to use the cloud features, and the project is open source under the MIT license. [Open the editor](https://mdstudio.deityhub.com/editor) and paste in a post to see what it finds. +Run the checklist against your own text in [mdstudio](/editor). Pick a target (Strict CommonMark, GFM extended, GFM without HTML or Wiki notes) and the Checks panel lists each problem with its line number: raw HTML, local images, wiki-links, math, Mermaid and trailing-space breaks. The preview follows the same rules, so you see the result before you publish. Paste a post in to try it. diff --git a/content/guides/obsidian-to-github-markdown.md b/content/guides/obsidian-to-github-markdown.md index cc150a2..9e6bce5 100644 --- a/content/guides/obsidian-to-github-markdown.md +++ b/content/guides/obsidian-to-github-markdown.md @@ -1,4 +1,13 @@ -Obsidian stores notes as plain Markdown files, which makes them easy to share, but Obsidian adds syntax that other tools do not understand. If you copy a note straight into a GitHub README, a dev.to post or a static site, some of it will break. This guide lists what to convert and how. +--- +slug: obsidian-to-github-markdown +title: "Obsidian to GitHub Markdown: Wiki-links, Callouts & More" +description: "How to share Obsidian notes outside Obsidian: convert wiki-links, highlights, callouts and embeds so they render on GitHub, blogging platforms and static sites." +order: 3 +published: 2026-11-02T11:23:00Z +updated: 2026-11-16T10:08:00Z +--- + +Obsidian stores notes as plain Markdown files, which makes them easy to share, but Obsidian adds syntax that other tools do not understand. If you copy a note straight into a GitHub README, a blog post or a static site, some of it will break. This guide lists what to convert and how. ## What Obsidian adds to Markdown @@ -58,8 +67,8 @@ Obsidian callouts look like a block quote that starts with a type in square brac ## What does carry over -Headings, emphasis, lists, task lists, tables, footnotes, code blocks, math and Mermaid diagrams are all standard on GitHub too, so these usually need no changes. Math and Mermaid still fail on platforms that do not render them. See [math and Mermaid in Markdown](https://mdstudio.deityhub.com/guides/markdown-math-and-diagrams). +Headings, emphasis, lists, task lists, tables, footnotes, code blocks, math and Mermaid diagrams are all standard on GitHub too, so these usually need no changes. Math and Mermaid still fail on platforms that do not render them. See [math and Mermaid in Markdown](/guides/markdown-math-and-diagrams). ## Let a checker find them -Doing this by eye across a long note is error prone. Paste the note into [mdstudio](https://mdstudio.deityhub.com/editor) and switch the target profile to Strict CommonMark, GitHub (GFM extended), GFM without HTML or Wiki notes. The portability checker lists every wiki-link, highlight, local image and other non-portable construct with a clickable line number. Switch to the Obsidian profile and the wiki-link and highlight warnings disappear, which shows exactly what is Obsidian-only. The editor is open source and local-first. For the bigger picture, read the [portable Markdown guide](https://mdstudio.deityhub.com/guides/markdown-portability). +Doing this by eye across a long note is error prone. Paste the note into [mdstudio](/editor) and choose GFM extended: the checker lists every wiki-link, highlight and local image with a clickable line number. Then choose Wiki notes and the wiki-link and highlight warnings go away, which shows exactly what is Obsidian-only. For the bigger picture, read the [portable Markdown guide](/guides/markdown-portability). diff --git a/content/guides/publish-markdown-to-github.md b/content/guides/publish-markdown-to-github.md new file mode 100644 index 0000000..fdf56bf --- /dev/null +++ b/content/guides/publish-markdown-to-github.md @@ -0,0 +1,46 @@ +--- +slug: publish-markdown-to-github +title: Publish Markdown to GitHub from an Editor +description: "Send a Markdown draft to a GitHub repository as a commit, a pull request or a gist, with its images, and what to know about connecting and republishing." +order: 9 +published: 2026-11-16T11:03:00Z +updated: 2026-11-16T11:03:00Z +--- + +For a README, a documentation page or a blog kept in a repository, the last step is copying the text into a file, committing it, and fixing the image paths. It is easy to get one of those wrong. Publishing straight from the editor removes the copying, and puts the image files where the text already points. This guide explains what mdstudio does when you publish a draft to GitHub, and what it does not do. + +## Connecting GitHub is a separate step + +Signing in with GitHub only identifies you. It asks for no access to your repositories and keeps no token. To publish, you connect GitHub explicitly, from the Publish dialog or from Settings, and GitHub asks you to approve it. mdstudio asks for access to public repositories and gists, or to private repositories when you choose that option. The token is stored encrypted on the server and never sent to your browser. You can disconnect at any time. + +Publishing is available for a draft kept in your cloud, with a confirmed email address. + +## Commit, pull request or gist + +Pick a repository, a branch and a path, including any folders, such as `posts/my-post.md`. Then choose how it goes in: + +- **Commit** puts the file on the branch you chose. If the branch moved while you were publishing, mdstudio stops and tells you, instead of overwriting anything. +- **Pull request** puts the commit on a new branch named after the draft and the time, and opens a pull request against the branch you chose. Use it when someone has to approve a change. +- **Gist** publishes the text as a secret gist unless you make it public. Publishing again updates the same gist, and it is created again if you deleted it. + +## Images come with the file + +A draft often points at images such as `images/diagram.png`. Publishing commits those files into an `images` folder beside the Markdown file, which is where the text already points, so the links work in the repository without edits. Images pasted into the text as base64 data are taken out and committed as files, so no base64 ends up in the repository. There is a limit of 20 images and about 4.5 MB in one publish. + +## Publishing again, and not overwriting by accident + +Publishing the same draft again updates the same file. If a file already exists at that path and this draft did not put it there, or someone changed it since, mdstudio will not replace it unless you confirm that you want to. This protects work that does not belong to the draft. + +## Write for the repository + +Because the text goes to GitHub, write for GitHub: + +- Use the GFM extended target, so tables, task lists, alerts and footnotes are expected. +- Use relative links between files in the repository, and hosted URLs for everything else. +- Give code fences a language, and keep one blank line between paragraphs. + +The checker warns about links to local files, because they break once the text leaves its folder. Inside a repository a relative link to another file is correct, so read those warnings with the repository's layout in mind. + +## When something else is the destination + +Not everything is published through a repository. If you are sending the text to a platform that takes pasted Markdown, export clean Markdown with the target set to the one that matches, and read [writing Markdown for blogging platforms](/guides/markdown-for-blogging-platforms). To get a second opinion before you commit, see [sharing a draft for review](/guides/share-markdown-for-review). To try publishing, [open the editor](/editor). diff --git a/content/guides/share-markdown-for-review.md b/content/guides/share-markdown-for-review.md new file mode 100644 index 0000000..1310129 --- /dev/null +++ b/content/guides/share-markdown-for-review.md @@ -0,0 +1,45 @@ +--- +slug: share-markdown-for-review +title: Share a Markdown Draft for Review Before You Publish +description: "Get feedback on a Markdown draft before it goes live: an expiring read-only copy, who can open it, comments on selected words, and what happens as you edit." +order: 8 +published: 2026-11-16T10:27:00Z +updated: 2026-11-16T10:27:00Z +--- + +Sending someone a Markdown file for feedback is awkward. They need an editor that renders it, they reply in a chat thread with line numbers you have to hunt for, and by the time you have fixed the first round, the file they hold is out of date. A read-only page with comments on the exact words solves most of that. This guide explains how review links in mdstudio work, and the choices you make when you create one. + +## What a review link is + +A review link is a copy of a draft, published at its own web address. It is not the draft itself. The page shows the text rendered the way the editor's preview shows it, with math and diagrams drawn in the reader's browser, and it has no controls for editing. Readers need no editor and no account to read a public link. + +Only a draft that is kept in your cloud can be shared, and your email address has to be confirmed first. Choose **Share** on the draft, then **Share for review**. + +## It expires, on purpose + +Every link has a lifetime of 1 to 7 days, 4 by default. You can lengthen or shorten it while it is live, and you can stop sharing at any moment, after which the address stops working. A link that has run out can be published again under a new address. The expiry is there so that a draft you meant to show for a week does not sit on the web forever. + +## Public, or only for named people + +A **public** link opens for anyone who has the address, and because it is a public web page, search engines can index it. Treat it like publishing. Do not use it for anything you would not put on a website. + +A link limited to **named people** lists the email addresses you invite. A reader has to sign in with a confirmed account on one of those addresses. Anyone else, including a signed-out visitor who guesses the address, gets a plain "not found", so the page does not reveal that it exists. Private pages are never indexed and are never cached publicly. Each invited address gets one email with who shared it, the title, the expiry date and a button. + +## Comments on the exact words + +When you turn comments on, signed-in readers with a confirmed email can select text on the page and comment on it. A comment is plain text, shown with the reader's display name and never their address, and anyone can reply in the thread. You see the comments in the editor, next to the draft, and you can resolve or delete them. You get at most one email an hour per link saying that something was said, and never what was said. + +## When you keep writing + +The page does not change when you edit the draft. It keeps the text you published until you choose to publish an update. That is deliberate: reviewers always comment on a fixed copy, and you can keep working without readers seeing half-finished sentences. + +When you do publish an update, comments written on the earlier copy are found again by the words they were attached to, and marked as being on an earlier version, so you can tell what still applies. Open pages show that an update has arrived and offer to reload. + +## A short review routine + +1. Finish a draft you would be willing to show, and check it in the editor first. +2. Share it for review, with the people you want to hear from, and a lifetime that fits the deadline. +3. Resolve each comment as you deal with it, and publish an update when you want a second look. +4. When you are done, stop sharing. Your draft is unchanged, and an expired link and its comments stay available to you for 30 days. + +Review is one step in a longer flow. For editing the same draft at the same time as someone else, read [writing a Markdown draft together](/guides/write-markdown-together). To send the finished text on, see [publishing Markdown to GitHub](/guides/publish-markdown-to-github). To try it, [open the editor](/editor). diff --git a/content/guides/write-markdown-together.md b/content/guides/write-markdown-together.md new file mode 100644 index 0000000..9da8c99 --- /dev/null +++ b/content/guides/write-markdown-together.md @@ -0,0 +1,42 @@ +--- +slug: write-markdown-together +title: Write a Markdown Draft Together, Online or Offline +description: "How several people edit one Markdown draft at once: inviting people, cursors and undo, what happens when someone goes offline, and the limits to know first." +order: 10 +published: 2026-11-16T11:36:00Z +updated: 2026-11-16T11:36:00Z +--- + +Two people editing one file usually means taking turns, or merging by hand. For a document you both want to move quickly, such as a README, a proposal or a post with a deadline, that is slow. Editing the same draft at the same time removes the turn-taking. This guide explains how it works in mdstudio, what is merged for you, and where it stops. + +## Starting a shared draft + +Open the draft's menu and choose **Share**, then **Edit together**, and invite people by email address. The draft has to be kept in your cloud, and the people you invite need a confirmed account on that address. Invited people find the draft under "Shared with you" in their library and open it from there. + +By default up to 3 people, including you, can edit one draft, and an account can have 2 of these live at a time. A server's admin can change both limits, and can switch the feature off. You can stop editing together at any time, which returns the draft to normal syncing. + +## What you see while you write + +Everyone's cursor and selection appear in the text with a name and a colour, and an avatar stack in the header shows who is in the draft. Undo is personal: pressing it reverts your own last edit, never someone else's. A small indicator tells you whether you are live, reconnecting or offline. + +## Offline edits merge + +This is the part that is hard with files and easy here. If you lose the connection, you can keep writing. Your edits are kept on your device, and when the network returns they are sent and merged with what everyone else did in the meantime. Nobody has to resolve a conflict by choosing one version. + +If two people change the same spot while apart, both keep their text, and the order of the two pieces is decided consistently for everyone, so the result is the same on every device. It can read oddly, since two people wrote the same sentence differently, but nothing is lost. Reread the passage after a reconnect. + +## What happens to the saved copy + +The text people edit together is the live draft. A copy of it is kept up to date in the owner's cloud draft within a short time after anyone stops typing, so history, sharing and publishing work from current text. If the owner restores an older version, it is applied as an ordinary edit that everyone sees. + +## Limits worth knowing + +- Only the text is shared live. The name and folder of the draft are not synced between people while it is live. +- Images pasted into the text as local data are not shared. Use hosted images, or a link, so everyone sees them. +- People you invite can edit, but cannot reshare the draft, publish it to GitHub or delete it. Those stay with the owner. +- Removing a person, or deleting the draft, ends their access straight away. They keep a plain local copy of what they had, and nothing is destroyed. +- There are no comments or suggestions inside the live editor. For feedback from people who should not edit, use a [review link](/guides/share-markdown-for-review). + +## When to use it + +Edit together when two or three people are producing the same text. Use a review link when you want feedback on a finished copy from many readers. And write the final text for the place it is going: read [portable Markdown](/guides/markdown-portability) before you publish. To try it, [open the editor](/editor). diff --git a/content/legal/privacy.md b/content/legal/privacy.md index 8edaec9..050fdde 100644 --- a/content/legal/privacy.md +++ b/content/legal/privacy.md @@ -1,3 +1,12 @@ +--- +slug: privacy +title: "Privacy Policy" +description: "What mdstudio stores and shares: nothing without an account, and only what each feature needs with one, including editing together. No ads, no analytics." +order: 1 +published: 2026-11-11T16:55:00Z +updated: 2026-11-16T13:28:00Z +--- + This policy covers the hosted mdstudio at {{site}}, run by the mdstudio maintainers ("we", "us"). If you self-host mdstudio, whoever runs your copy is responsible for your data, and this policy does not apply to it. The short version: mdstudio is local-first. You can write, preview, check and export without an account, and then nothing you write leaves your browser. An account is optional and adds features that need a server. There is no advertising, no analytics and no tracking. @@ -8,6 +17,7 @@ Without an account, everything is stored on your device: - Your drafts and their saved versions (IndexedDB). - Your settings: theme, checker rules, library folders and similar (localStorage). +- The search index: searching your drafts, commands and settings (the search dialog) happens on your device, and what you type is never sent anywhere. - A copy of the app's files, so it works offline (the browser cache). We never receive these. Clearing your browser's site data deletes them. @@ -20,12 +30,13 @@ If you are signed in, the name, provider, address and model of your AI setups ar ## What we store when you have an account -- **Account details:** your email address, a hash of your password (never the password itself), your display name, and the time the account was created. +- **Account details:** your email address, a hash of your password (never the password itself), your display name, and the time the account was created. When you change your email address, a link goes to the new address, and the address changes only once that link is opened; we also tell the old address that it changed. - **Sign-in with Google or GitHub:** see the next section. We store the provider's ID for you, your profile picture's address, and your name. - **Sessions:** a hash of your session token and its expiry. No IP address or device details are stored with it. - **Email links:** hashes of the one-time links for confirming your email and resetting your password, until they expire or are used. - **Cloud drafts:** only drafts you choose to put in the cloud. The text, the title and a limited number of earlier versions are stored. Drafts are not end-to-end encrypted: they are stored in a database that we administer, and the admin tools we use show titles and sizes, not text. - **Share links and comments:** see below. +- **Drafts edited together:** see "Editing together" below. - **GitHub publishing:** only if you connect it. See below. - **Account limits and admin records:** your plan and limits, whether the account is suspended, and a log of admin actions (who did what to which account). @@ -54,13 +65,24 @@ A share link publishes a copy of a cloud draft at a public address. Understand w - You can make a link private to invited email addresses. Readers must then sign in with one of those addresses. Invitations are sent by email. - If comments are on, signed-in readers can comment. Comments show the commenter's display name, never their email address. If your display name came from Google or GitHub, that is the name shown. +## Editing together + +You can switch a cloud draft to live editing and invite people by email address, up to 3 people on a draft including you. Understand what that means before you use it: + +- The people you invite can read the whole draft, edit it at the same time as you, and see each other's display name, picture and cursor while they are in it. They need an account with a confirmed email address that matches the invitation. Removing a person, or stopping live editing, ends their access to the live draft. +- While a draft is edited live, its text, and the comments and suggestions made in it, are kept in a live room: on the hosted service, storage belonging to a Cloudflare Durable Object, separate from the main database. A copy of the text is also written to your cloud draft so that versions, share links and publishing keep working. The room is deleted when you stop live editing or delete the draft. +- Each invited person's browser keeps a copy on their device while they work, so it can keep working offline and merge afterwards. Taking access away does not delete a copy that is already on their device, because we cannot reach into someone's browser. Only invite people you would trust with the text. +- Live drafts are not end-to-end encrypted, like other cloud drafts. The admin tools we use show titles and sizes, not text. +- The live connection (a WebSocket to Cloudflare) knows which account is on it, so that only invited people can join. It also carries other live updates, such as your drafts reaching your other devices and new comments on a share link. Nothing about it is stored beyond the connection. +- An invitation is an email to the address you give, with a link to the draft. + ## Email -We send email for confirming your address, password resets, share invitations and notices that someone commented on your shared draft (at most one an hour per link, and never the comment itself). These go through an email provider (currently Resend or Mailtrap), which receives the recipient address and the message. +We send email for confirming your address, changing it, password resets, share invitations, invitations to edit together and notices that someone commented on your shared draft (at most one an hour per link, and never the comment itself). These go through an email provider (currently Resend or Mailtrap), which receives the recipient address and the message. ## Technical data -- **Hosting:** the site runs on Cloudflare (Workers, D1 database, and its network). Cloudflare processes IP addresses and request details to deliver and protect the site, and may keep logs under [its own privacy policy](https://www.cloudflare.com/privacypolicy/). +- **Hosting:** the site runs on Cloudflare (Workers, the D1 database, Durable Objects for live updates and editing, and its network). Cloudflare processes IP addresses and request details to deliver and protect the site, and may keep logs under [its own privacy policy](https://www.cloudflare.com/privacypolicy/). - **Abuse limits:** to limit sign-up and sign-in abuse, we keep short-lived counters tied to your IP address (and to the email address being tried). They exist only for the length of the limit, at most about an hour, and are then deleted. - **Sign-up check:** sign-up may use Cloudflare Turnstile to tell people from bots. Turnstile runs in your browser and sends information about it to Cloudflare. - **Errors:** if a server error occurs, the error and where it happened are logged so we can fix it. Request contents, such as your draft text, are not logged. @@ -82,7 +104,8 @@ We do not sell personal data. Data goes only to the services needed to run mdstu - Account data and cloud drafts: until you delete them or the account is deleted. - Sessions: 24 hours, renewed while you use the site, and never more than 5 days after you signed in. - Email confirmation links: 24 hours. Password reset links: 1 hour. -- When an account is deleted, its drafts, versions, share links, comments, GitHub connection and sessions are deleted with it. Cloudflare keeps short-lived database backups, so deleted data can remain in them for a limited time (up to 30 days). +- Live editing rooms: until you stop live editing or delete the draft. +- When an account is deleted, its drafts, versions, share links, comments, live editing rooms, GitHub connection and sessions are deleted with it. Cloudflare keeps short-lived database backups, so deleted data can remain in them for a limited time (up to 30 days). ## Your choices and rights diff --git a/content/legal/terms.md b/content/legal/terms.md index d8ac04d..8a9cd70 100644 --- a/content/legal/terms.md +++ b/content/legal/terms.md @@ -1,8 +1,17 @@ +--- +slug: terms +title: "Terms of Service" +description: "The rules for using the hosted mdstudio: your content, acceptable use, limits and the service's lack of guarantees." +order: 2 +published: 2026-11-11T16:55:00Z +updated: 2026-11-16T13:28:00Z +--- + These terms cover your use of the hosted mdstudio at {{site}}, run by the mdstudio maintainers ("we", "us"). By using it, you agree to them. If you do not agree, do not use it. How we handle personal data is in the [Privacy Policy](/privacy). ## What mdstudio is -mdstudio is a Markdown editor and portability checker. You can use the editor without an account, and it stores your drafts in your browser. An account is optional and adds cloud drafts, share links with comments, saved AI setups and publishing to GitHub. The service is free. +mdstudio is a Markdown editor and portability checker. You can use the editor without an account, and it stores your drafts in your browser. An account is optional and adds cloud drafts, share links with comments, editing a draft together with people you invite, saved AI setups and publishing to GitHub. The service is free. ## Your account @@ -12,10 +21,16 @@ mdstudio is a Markdown editor and portability checker. You can use the editor wi ## Your content -You own what you write. You give us permission to store, process and show it only as needed to run the features you use: to keep your cloud drafts, sync them between your devices, serve a share link you publish, send your draft to GitHub when you publish, and send your text to an AI provider when you run an AI helper. That permission ends when you delete the content or the account, apart from short-lived backups. +You own what you write. You give us permission to store, process and show it only as needed to run the features you use: to keep your cloud drafts, sync them between your devices, serve a share link you publish, show a draft to the people you invite to edit it, send your draft to GitHub when you publish, and send your text to an AI provider when you run an AI helper. That permission ends when you delete the content or the account, apart from short-lived backups. You are responsible for your content and for having the right to use it. A share link is public unless you make it private. Do not publish anything there that you would not want read by anyone. +## Editing together + +You can invite other people, by email address, to edit a cloud draft with you. Invite only people you want to have the whole text, because they can read it, change it and keep a copy on their device. You are responsible for who you invite and for what they can see. People you invite can edit anything in the draft, including your text. + +Only you can invite and remove people, stop live editing or delete the draft. When you remove someone or stop, their access ends, but a copy already on their device stays there. People you are invited by can use the draft only to work on it with you: they may not share it, publish it or use it for anything else. A draft allows up to 3 people, and an account up to 2 live drafts, for now. + ## What you may not do - Break the law, or post content that is illegal, infringes someone's rights, or is meant to deceive, harass or harm people (including malware and phishing). diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md deleted file mode 100644 index 3f4c807..0000000 --- a/docs/ARCHITECTURE.md +++ /dev/null @@ -1,62 +0,0 @@ -# Architecture - -## Stack -| Layer | Choice | -|---|---| -| Framework | TanStack Start v1, React 19, TypeScript, Vite | -| Routing | TanStack Router file routes (`src/routes`) | -| Styling | Tailwind CSS v4 via `src/styles.css` (`@theme inline`, OKLCH tokens) | -| UI kit | shadcn/ui (Radix) in `src/components/ui`, Vaul drawers, Sonner toasts, lucide-react icons | -| Editor | CodeMirror 6 (`@codemirror/lang-markdown`, language-data, search, history) | -| Markdown | unified: remark-parse, remark-gfm, remark-frontmatter, remark-rehype, rehype-highlight, rehype-sanitize, rehype-stringify; rehype-parse + rehype-remark + remark-stringify for HTML→MD; `yaml` for front matter | -| Storage | IndexedDB (raw, no wrapper library) | -| Tests | Vitest + Testing Library + jsdom | - -## Routes -| Path | File | Purpose | -|---|---|---| -| `/` | `src/routes/index.tsx` | Landing page | -| `/editor` | `src/routes/editor.index.tsx` | Opens most recent draft, or creates one from the sample | -| `/editor/$docId` | `src/routes/editor.$docId.tsx` | Renders `` | -| root | `src/routes/__root.tsx` | Head/meta, fonts (Fraunces, IBM Plex Sans, JetBrains Mono), `` | - -## Modules -### `src/lib/markdown/markdown.ts` (single home of all Markdown logic) -- `PROFILES`: `commonmark | gfm-extended | gfm-no-html | wiki-notes` — controls which features are considered portable. -- `renderMarkdown(text, profile, images)` → sanitized HTML string. Local `images/x.png` refs resolve to stored data URIs for preview only. -- `checkPortability(text, profile)` → `Issue[] {rule, severity, line, message, fix?}`. Rules: raw-html, data-image, local-image, mermaid, highlight (`==x==`), wiki-link (`[[x]]`), math (`$`/`$$`), container (`:::`), trailing-break (two spaces), mixed-bullets, gfm-table/task/strike (on commonmark), fence-lang (missing language). -- `getOutline`, `getStats` (words, chars, reading time), `deriveTitle`, `slugify`. -- `splitFrontMatter` / `joinFrontMatter` (YAML). -- `finalizeText` (LF endings, trailing newline), `normalizeMarkdown` (remark-stringify with consistent bullets/fences/emphasis). -- `embedImages(text, images)` → self-contained export. -- `htmlToMarkdown(html)` — paste conversion. -- `standaloneHtml(title, html)` — full HTML document with inline CSS. - -### `src/lib/storage/documentStore.ts` -```ts -interface MdDocument { id: string; title: string; content: string; images: Record; createdAt: number; updatedAt: number } -``` -`list / get / save / create / remove / duplicate` + `SAMPLE`. Treat as an interface: a future sync backend implements the same API. - -### `src/lib/editor/images.ts` -`compressImage(file)` (canvas, max 1600px, JPEG/WebP), `safeImageName`, `kb`. - -### `src/lib/ai/provider.ts` / `src/lib/ai/writing.ts` -- Providers: `openai` (`/v1/chat/completions`), `anthropic` (`/v1/messages`, header `anthropic-dangerous-direct-browser-access: true`), `gemini` (`:streamGenerateContent?alt=sse`), `custom` (OpenAI-compatible base URL, HTTPS required). -- `buildProviderRequest`, `generateWithProvider` — streaming SSE parse, AbortSignal, refusal/length handling, no retry on 402/403. -- Modes: `metadata` (returns JSON `{title, description, tags[]}`) and `write` (streams Markdown). -- Keys: React state only. Never persisted. - -### Components (`src/components/studio`) -- `Studio.tsx` — page orchestration: top bar, library, toolbar, editor/preview, side panel, status bar, autosave (400 ms debounce), import, paste, export, compact (<1024px) layout with drawers. -- `MarkdownEditor.tsx` — CodeMirror wrapper; `EditorHandle { wrap, linePrefix, insert, goToLine, scrollToRatio, focus }`; paste & drop handlers; Mod-B/I/K. -- `AiWriter.tsx` — provider connection + two tabs (Metadata, Write a topic). - -## Invariants -See `AGENTS.md`. Key: no preview-only transforms; sanitize always; storage via documentStore only; CodeMirror client-only; AI BYOK and review-before-apply; tokens only. - -## Tests (31 passing) -`src/lib/markdown/markdown.test.ts` (render: no `
` on single newline, no smart quotes, GFM, sanitizer strips `