--- title: "editmd — a free Markdown editor for Mac" description: "Create, edit, preview and review Markdown on your Mac. A free, local editor with optional AI assistance and flexible exports." canonical: https://editmd.app/ markdown: https://editmd.app/index.md status: pre-release, waiting list open generated: editmd-website --- # Markdown for your workflow. Create, edit, preview and review Markdown on your Mac. A free, local editor with optional AI assistance and flexible exports. ## Status - No public release yet. Release verification is in progress and nothing on this site can activate a download until it finishes. - Waiting list for one message when the first verified build is ready: https://editmd.app/waiting-list/ - Free to use. No editmd account. Plain .md files stay in the folders you choose. ## What it does - Edit and preview together: Editor, Split or Preview views over the same file. - A whole folder, open at once: tabs, a folder workspace, Quick Open, search and an outline. - Tables, tasks, code, math and diagrams in the same document. - Export as HTML, Markdown, PDF, PNG, ePub or DOCX. Copy as Markdown, plain text, HTML or RTF. RTF and DOCX keep a basic subset, not an identical layout. PDF goes through the macOS print dialog. - Optional AI review: OpenAI, OpenRouter or a local Ollama model. Only the text you review is sent, and you decide which suggestions to keep. A local Ollama model can only answer questions about the document. AI is off until you turn it on in Preferences and connect a provider. - Local at the core: no account, no new document format, no upload step. ## Planned - Skill and instruction files with templates, structure checks and optional coaching are planned for editmd v3.0 and are not in the current app. ## Common questions - **Do I have to use AI?** No. AI is optional and starts disabled. The complete editor works without it. If you connect a provider, you review the exact text before sending and choose which proposed edits to apply. - **Do I need an account?** No editmd account is needed to write, preview and work with local Markdown files. Optional remote AI uses your chosen provider account. - **What can I try in the browser?** Edit sample documents, change views and explore your writing preferences. Text stays in this browser session and is discarded on reset or reload. Your files on disk stay untouched. - **Are my notes tied to editmd?** editmd works with plain Markdown files. You can open those files in another text editor. Folders you sync or back up follow the rules of the services you choose. - **Can I write offline?** Yes. Local writing, preview and file work do not need an account or provider connection. Remote AI and remote images use the services you choose to enable. - **How do I keep my changes?** Save with Command-S to write changes to your Markdown file. Session recovery can help after an interruption, but it does not replace saving or keeping backups. ## Where to read more - Handbook: https://editmd.app/docs.md - Markdown School: https://editmd.app/learn.md - Security and data handling: https://editmd.app/security.md - Contact: https://editmd.app/contact.md - Site index for agents: https://editmd.app/llms.txt --- --- title: "Waiting list" description: "One message when the first verified build of editmd, a free Markdown editor for Mac, is ready." canonical: https://editmd.app/waiting-list/ markdown: https://editmd.app/waiting-list.md status: pre-release, waiting list open generated: editmd-website --- # Write Markdown. Keep the file. A free Markdown editor for Mac, in preparation. Create, edit, preview and review your documents as plain .md files, with optional AI assistance and flexible exports. ## Join the waiting list There is no download yet. Release verification is still in progress. Leave an address on the page and we will write once, when it is ready. - Form: https://editmd.app/waiting-list/ (a human fills in an email address; there is no API for agents) - Consent: Email me once, when the first editmd release is ready. Ask me to confirm my address first. I can withdraw at any time. - A confirmation email is sent first. Opening the link does not join the list: check the address and press Confirm. Links expire after 48 hours or when the consent text changes. - Resend stores the confirmed address and consent version. For privacy questions or withdrawal, use [Contact](/contact/) and choose “Ask about privacy or security”. ## Facts - Free to use - No editmd account - Plain .md files --- --- title: "The editmd handbook" description: "Every guide for editmd, grouped by what you are trying to do." canonical: https://editmd.app/docs/ markdown: https://editmd.app/docs.md status: pre-release, waiting list open generated: editmd-website --- # The editmd handbook Learn Markdown, find your way around editmd, and connect an AI model when you want one. ## Start here - [What is a Markdown file?](https://editmd.app/docs/markdown.md): A small amount of syntax. A document you can take anywhere. - [Install editmd](https://editmd.app/docs/install.md): Get the Mac app into Applications and open your first file. - [Your first document](https://editmd.app/docs/first-document.md): Write a short note, see it take shape, and save it somewhere familiar. ## Using editmd - [Write and format](https://editmd.app/docs/writing.md): A practical Markdown reference for the things you write every day. - [Files, folders and recovery](https://editmd.app/docs/workspace.md): Keep related writing together and understand where your changes live. - [Make the editor yours](https://editmd.app/docs/preferences.md): Set comfortable type, scrolling and layout without changing your document. - [Copy, export and share](https://editmd.app/docs/exports.md): Choose an output for the person or tool receiving your writing. ## Optional AI - [Connect an AI model](https://editmd.app/docs/ai-setup.md): Choose a provider, add a connection and test it before using document text. - [Your first AI request](https://editmd.app/docs/ai-use.md): Review the text you send, then decide what to keep. ## Reference - [Update, back up and remove](https://editmd.app/docs/updates.md): Replace the app safely and understand what happens to your files. - [Keyboard shortcuts](https://editmd.app/docs/shortcuts.md): Keep your hands on the keyboard, from the first file to the final save. - [Troubleshooting](https://editmd.app/docs/troubleshooting.md): Find the next useful action when a file, preview or connection behaves unexpectedly. - [How editmd is built](https://editmd.app/docs/how-it-is-built.md): A desktop shell, a source editor and a renderer around ordinary files. - [Frequently asked questions](https://editmd.app/docs/faq.md): Practical answers about files, the app, AI and getting your work out. - [Privacy and data handling](https://editmd.app/docs/privacy.md): Privacy notice for editmd.app and the editmd Mac app: what we collect, why, where it goes and how to reach us. --- --- title: "What is a Markdown file?" description: "A small amount of syntax. A document you can take anywhere." canonical: https://editmd.app/docs/markdown/ markdown: https://editmd.app/docs/markdown.md status: pre-release, waiting list open generated: editmd-website --- # What is a Markdown file? A small amount of syntax. A document you can take anywhere. ## Start with plain text A Markdown file is a text document with simple marks that describe its structure. A `#` introduces a heading. A pair of `**` marks makes words bold. The file usually ends in **.md** or **.markdown**. The marks are ordinary characters, so you can read and edit the file in a plain-text editor. A Markdown renderer turns those characters into headings, lists, links and other formatted content. In editmd, **Split** shows the source and the rendered result together. ## Why use it? Markdown keeps the writing separate from a particular app. Your text stays readable, is easy to copy or search, and can be kept alongside related files. You can start a document in editmd and open it in another Markdown editor later. It is especially useful when the structure matters more than precise page layout. A designed brochure or a document that needs exact page breaks may be better finished in a page-layout or word-processing app. ## Where you will find it | Use | A typical file | Why Markdown fits | | --------------------- | -------------- | -------------------------------------------------------- | | Personal notes | `ideas.md` | Quick to write and easy to keep in folders. | | Project documentation | `README.md` | Explains what a project is and how to use it. | | Meeting notes | `planning.md` | Headings, decisions and task lists in one readable file. | | Website content | `article.md` | Many publishing tools turn Markdown into web pages. | | Technical writing | `guide.md` | Code, links and prose can live together. | ## A file is not a website Saving a Markdown document does not publish it or send it to anyone. A website, repository or sharing service must receive the file before other people can read it. editmd saves to the location you choose on your Mac. Images are often separate files referenced from the document. Keep them with the Markdown when moving a project. A cloud-synced folder is managed by the sync service you choose; Markdown itself does not provide syncing. ## Not every renderer looks the same Headings, paragraphs, emphasis and simple lists are widely supported. Tables, task lists, footnotes, math and diagrams depend on the app displaying the file. Check the destination before relying on those features in a shared document. Use the [syntax reference](/docs/writing/) when you need a pattern, or follow [your first document](/docs/first-document/) to learn by writing. The [CommonMark reference](https://commonmark.org/help/) is a useful guide to the core syntax. Group: Start here. Handbook index: https://editmd.app/docs.md --- --- title: "Install editmd" description: "Get the Mac app into Applications and open your first file." canonical: https://editmd.app/docs/install/ markdown: https://editmd.app/docs/install.md status: pre-release, waiting list open generated: editmd-website --- # Install editmd Get the Mac app into Applications and open your first file. ## Before you begin - A Mac with **Apple silicon or an Intel processor**. - **macOS 11 or later** is the app's configured minimum. Match your Mac to the compatibility information supplied with the download. - Permission to install an app in Applications. A managed work Mac may require help from your administrator. - An internet connection to download the app. Everyday local editing works offline. You do **not** need Node.js, Rust, Xcode, a terminal, an editmd account or an AI subscription to use the app. Those development tools are for building software, not installing editmd. Ollama has its own requirements and is entirely optional. See [local AI setup](/docs/ai-setup/#ollama-on-your-mac). ## Install from a disk image 1. Use the [editmd download section](/#download). Check the version and compatibility information supplied with the package, and compare its checksum if one is published beside it. 2. Open the downloaded **.dmg** file in Finder. 3. Drag **editmd.app** into **Applications**. 4. Eject the disk image in Finder. 5. Open **editmd** from Applications or find it with Spotlight. If you use a **.zip** package, double-click it to extract the app, then move **editmd.app** to Applications before opening it. **You are done when:** editmd opens from Applications and you can choose **File → Open File…**. Continue with [your first document](/docs/first-document/). ## If macOS stops the app Read the complete message. A normal first-open confirmation is different from a warning that an app is damaged or its developer cannot be verified. If macOS rejects the package, stop and check its source and integrity. Do not remove quarantine attributes or weaken Gatekeeper to force it to run. On a managed Mac, ask your administrator whether installation is allowed. Apple's [guidance on opening apps safely](https://support.apple.com/en-us/102445) explains the checks macOS performs. ## Choose editmd for an existing file You can always open a document from **File → Open File…** inside editmd. To choose an app through Finder, use the file's **Open With** menu. Keep the **.md** extension so other apps recognise the document as Markdown. Group: Start here. Handbook index: https://editmd.app/docs.md --- --- title: "Your first document" description: "Write a short note, see it take shape, and save it somewhere familiar." canonical: https://editmd.app/docs/first-document/ markdown: https://editmd.app/docs/first-document.md status: pre-release, waiting list open generated: editmd-website --- # Your first document Write a short note, see it take shape, and save it somewhere familiar. ## 1. Create a place for your note Open editmd. Choose **File → New File…** and use a name such as **first-note.md**. Choose a folder you can find again. A folder called **Notes** is a simple place to start. If you already have a Markdown file, choose **File → Open File…** instead. Opening a file does not import it into a separate document library. ## 2. Write a heading and a paragraph Type this into the editor. Leave a blank line between the heading and the paragraph: ```markdown # My first note A little space to think clearly. ## Next steps - Write the first idea - Add one useful detail ``` The `#` and `##` create two levels of heading. The hyphens create a list. You can type the marks yourself or use the formatting bar. ## 3. See the result Choose **Split** to show your Markdown and its preview together. Change “My first note” to a title of your own. The preview updates as you write. Choose **Editor** when you want to focus on the source. Choose **Preview** when you want to read the formatted document. Changing the view does not convert or replace your file. ## 4. Make a small edit Select a few words and use **Bold** in the formatting bar, or press **⌘B**. The words are wrapped in `**` in the source and appear bold in the preview. Use **Undo** if you want to reverse the change. ## 5. Save and reopen Choose **File → Save** or press **⌘S**. Find the file in the folder you selected. Reopen it through **File → Open File…** and check that your changes are there. **You have finished your first document:** a readable **.md** file that you can keep, share or open in another editor. Make saving a habit; recovery helps with interruptions but does not replace a saved file or a backup. Group: Start here. Handbook index: https://editmd.app/docs.md --- --- title: "Write and format" description: "A practical Markdown reference for the things you write every day." canonical: https://editmd.app/docs/writing/ markdown: https://editmd.app/docs/writing.md status: pre-release, waiting list open generated: editmd-website --- # Write and format A practical Markdown reference for the things you write every day. ## The everyday syntax | To write | Use this Markdown | | --------------- | -------------------------------------- | | Main heading | `# Document title` | | Section heading | `## A section` | | Bold | `**important words**` | | Italic | `*a little emphasis*` | | Inline code | `` `filename.md` `` | | Bulleted list | `- A list item` | | Numbered list | `1. First step` | | Quotation | `> A quoted thought` | | Task | `- [ ] Something to do` | | Finished task | `- [x] Something done` | | Link | `[Link text](https://commonmark.org/)` | | Local image | `![Description](images/sketch.png)` | Leave a blank line between paragraphs and around lists or other blocks when the structure is unclear. Indentation can change meaning, especially inside lists and code blocks. ## Use the formatting and insert tools The formatting bar works on Markdown source. Select text before applying bold, italic, inline code or a heading. Insert tools add links, images, tables, emoji, symbols, alerts, diagram starters and highlight colours without memorising every mark. For an image, write a useful description of what it shows. A local image reference needs the image file to remain at the relative location named in the document. When you choose an image file through the insert tool, or drop a file onto the editor, editmd copies it into an `attachments` folder beside the current document and inserts the link for you. ## Code blocks Place three backticks before and after code. Put a language name after the opening backticks for syntax highlighting. For example: ````markdown ```javascript const thought = 'Keep it simple'; ``` ```` ## Tables and tasks ```markdown | Task | Owner | | ---------------------- | ----- | | Write the introduction | Me | - [x] Start the draft - [ ] Review the ending ``` A supported task checkbox in the Mac preview changes the corresponding Markdown marker. Ambiguous or disabled tasks remain read-only. Other Markdown apps may handle task interactions differently. ## Math, diagrams and notes editmd supports math through KaTeX and diagrams through Mermaid. Use the insert tool for a Mermaid starting point, then edit its source. Syntax errors can leave a block unrendered; check the source before assuming the text is lost. Footnotes, GitHub-style alerts and highlighted text are also supported. These extensions may not display identically in another editor or export format. ## What is YAML? YAML is a text format for structured data. A key such as `title` names a value; a list groups several values. YAML stands for “YAML Ain’t Markup Language.” Markdown structures the writing itself, while YAML can describe that writing with metadata. See the [YAML specification](https://yaml.org/spec/1.2.2/) for the language and its data types. A standalone YAML file usually ends in `.yaml` or `.yml`. A YAML block at the beginning of a Markdown document is called **front matter**. Its opening and closing `---` lines separate metadata from the body. Front matter is a convention supported by particular tools, rather than part of core [CommonMark syntax](https://spec.commonmark.org/). ## Add a YAML header Use **Add YAML Header** or **⌘⇧Y** to insert metadata at the start of a document. If a header already exists, editmd focuses it instead of adding another. Metadata stays in the Markdown file and is kept out of the rendered document body. ```yaml --- title: 'Field notes' tags: - writing - research draft: true --- ``` Here, `title` is text, `tags` is a list and `draft` is a boolean value. Indent nested values with spaces, not tabs. Quoting text can make the intended value clearer, especially when it contains punctuation such as a colon. These are YAML rules; the [specification's examples](https://yaml.org/spec/1.2.2/#chapter-2-language-overview) show more structures. The keys in this example are illustrative metadata. A publishing tool decides whether `draft` or `tags` has an effect; adding them does not turn on a corresponding editmd feature. Valid YAML and valid configuration for a particular tool are separate checks. Front matter remains readable in the source file even when it is hidden from the preview. Keep credentials out of document metadata. To learn how different destinations handle the rest of your document, see [Copy, export and share](/docs/exports/). ## Find and replace Use **⌘F** to find text in the current document, or **⌘⌥F** for Find and Replace. Check the case and regular-expression options before replacing text. Review the match count, try one replacement, then use **Replace All** when the pattern is right. Group: Using editmd. Handbook index: https://editmd.app/docs.md --- --- title: "Files, folders and recovery" description: "Keep related writing together and understand where your changes live." canonical: https://editmd.app/docs/workspace/ markdown: https://editmd.app/docs/workspace.md status: pre-release, waiting list open generated: editmd-website --- # Files, folders and recovery Keep related writing together and understand where your changes live. ## One file or a whole folder Use **File → Open File…** for a single document. Use **File → Open Folder…** for a workspace: a folder of related Markdown and attachments. The sidebar lets you navigate the folder while tabs keep multiple documents within reach. A useful starting arrangement is a project folder with a `README.md`, a `notes.md` and an `images` folder. You choose the names and locations; editmd does not require a particular folder structure. ## Move around quickly - **Quick Open (⌘P):** find files in the current workspace, recent files and recent workspaces. - **Search Workspace (⌘⇧F):** search across the folder's documents. - **Outline (⌘⇧E):** navigate the current document by its headings. - **Tabs:** switch between open documents. A changed document needs saving. ## Save before moving on Use **⌘S** to write your changes to the file. Renaming or moving files changes their locations, so check links and image references afterwards. **Delete** in the sidebar removes a file or folder from disk permanently; it does not go to the Trash. editmd asks first and warns if open documents inside it have unsaved changes. If you use a cloud-synced folder, wait for that service to finish syncing before opening the same document on another device. editmd is not a real-time collaboration or sync service. ## When another app changes the file editmd watches open files and workspaces for external changes. If the document has unsaved edits, an external change becomes a conflict: a banner offers **Reload from disk** or **Keep my version**. Compare the versions before choosing; save an extra copy of important text if you are unsure. Do not repeatedly save over a conflict without checking it. Two editors or a sync service can both be changing the same file. ## Returning after an interruption Session restore can reopen files, tabs, the workspace and view state. Bounded recovery can restore unsaved edits after an interruption. Read any recovery notice: some files may no longer be accessible, and storage limits can prevent recovery of every buffer. After recovery, inspect the text and save the version you want. Keep independent backups for important work; recovery is not version history or a backup system. Group: Using editmd. Handbook index: https://editmd.app/docs.md --- --- title: "Make the editor yours" description: "Set comfortable type, scrolling and layout without changing your document." canonical: https://editmd.app/docs/preferences/ markdown: https://editmd.app/docs/preferences.md status: pre-release, waiting list open generated: editmd-website --- # Make the editor yours Set comfortable type, scrolling and layout without changing your document. ## Open Preferences Press **⌘,** or choose **Preferences…** from **More actions**. Settings adjust the editor experience; they do not rewrite Markdown formatting in your file. ## Reading and writing comfort | Control | What it changes | When it helps | | ------------------- | --------------------------------- | -------------------------------------------------- | | Theme | System, Light or Dark | Match the room or follow macOS. | | Editor font size | Source text size | Make long writing sessions more comfortable. | | Editor line height | Space between source lines | Give dense paragraphs more breathing room. | | Wrap long lines | Visual wrapping in the editor | Read paragraphs without horizontal scrolling. | | Show line numbers | A numbered source gutter | Discuss a specific line or inspect a long file. | | Check spelling | Editor spellchecking | Catch typing mistakes while writing. | | Preview width | Width of the rendered text column | Keep paragraphs easy to scan. | | Show formatting bar | Formatting controls | Keep tools nearby or simplify the writing surface. | ## Arrange the two views Use **Editor split** or the draggable divider to balance source and preview. Enable **Sync editor and preview scrolling** to follow the same part of a document in both panes. Zoom adjusts the editor and preview together. Use **⌘+** (or **⌘=**), **⌘−** and **⌘0** to zoom in, zoom out or return to actual size. Zoom is different from adding a larger heading to your document. ## Remote images **Load remote images** is off by default. Leave it off unless you want the preview to contact image hosts named in the document. Workspace-local images can work without enabling remote images. Exports block remote resources even if you enabled them in the preview. For a portable document, use local attachments and check your export. ## Optional AI and local data **AI Connections** contains the separate opt-in setup. Follow [connect an AI model](/docs/ai-setup/) before entering provider credentials. **Local app data** includes the reset flow. It can remove preferences and recovery data, so it is not the way to reset a font size. Read [updates and removal](/docs/updates/#reset-local-app-data) before using it. Group: Using editmd. Handbook index: https://editmd.app/docs.md --- --- title: "Connect an AI model" description: "Choose a provider, add a connection and test it before using document text." canonical: https://editmd.app/docs/ai-setup/ markdown: https://editmd.app/docs/ai-setup.md status: pre-release, waiting list open generated: editmd-website --- # Connect an AI model Choose a provider, add a connection and test it before using document text. ## Before connecting AI is optional. You can use the complete local editor without enabling it. A **provider** runs the service; a **model** is the specific system that answers; a **connection** saves your provider and model choice. Remote providers need your own API account, an API key and any required billing or credits. An API key is a credential: enter it only in the Mac app's connection settings, not in a Markdown file or this website. | Choice | What you need | Where requests run | Actions | | ---------- | -------------------------------------------------------- | ------------------------------------ | -------------------------------------------------- | | OpenAI | API key, account access to a suitable model, API billing | OpenAI | Editing, structure, metadata/tasks, review and Ask | | OpenRouter | API key, balance and an eligible catalog model | OpenRouter and its selected provider | Actions supported by the tested model | | Ollama | Ollama running locally and an installed model | This Mac's local Ollama service | Grounded Ask | There is no direct Anthropic, Gemini or Kimi connection in this setup; they appear greyed out in the **Provider** list. A model offered through OpenRouter must appear in the app's compatible catalog and pass its connection test. ## Enable the optional feature 1. Open **Preferences…** with **⌘,** and find **AI Connections**. 2. Turn on **Enable AI Revision & Review**. 3. Read the AI use notice. If you meet the conditions, tick the **18+ acknowledgement** and choose **Continue to AI connections**. This applies to local Ollama as well as remote providers. 4. Open **Add your first AI connection** and follow the path for your provider. You do not need to enable AI to continue writing. If you cannot make the acknowledgement, leave the feature off. ## OpenAI 1. In your OpenAI API account, create a key and check model access and API billing. A ChatGPT subscription and API billing are separate. 2. In editmd, choose **OpenAI** under **Provider**. 3. Enter an exact **Model ID** available to your API account and a useful **Connection name**, such as “Writing”. Use the provider's current model documentation rather than guessing a model name. 4. Enter the **API key**. Read the provider disclosure and select its acknowledgement. 5. Choose **Save connection**, then **Test connection** under the saved connection. 6. Check that the test reports “Structured output is available” before using the model with a document. Remote keys are stored in macOS Keychain. A connection test uses fixed synthetic text, not your open document; it is still an API request and may incur provider charges. Provider help: [OpenAI API quickstart](https://developers.openai.com/api/docs/quickstart) and [ChatGPT versus API billing](https://help.openai.com/en/articles/9039756). ## OpenRouter 1. Create an API key in your OpenRouter account and check your balance and account controls. 2. In editmd, choose **OpenRouter — model gateway**. 3. Enter your **API key**, then choose **Load compatible models**. 4. Use **Search models** and choose an exact **Model ID** from the list. 5. Add a **Connection name**, review the provider disclosure and select its acknowledgement. 6. Choose **Save connection**, then **Test connection**. A passed test enables document actions for the rest of the current app session; test again after relaunching. editmd filters for compatible routes and requires specific privacy and structured-output controls. A model being advertised on the provider's website does not guarantee it can be used through this connection. To change an existing connection, use **Switch model using saved key**, choose the new model and test again. You do not need to disconnect merely to choose another model. Provider help: [OpenRouter quickstart](https://openrouter.ai/docs/quickstart) and [API keys](https://openrouter.ai/settings/keys). ## Ollama on your Mac Ollama is a separate installation. Ollama's own documentation currently lists **macOS 14 or later**, on Apple silicon or, CPU-only, on Intel. Models need additional storage and memory; choose one that fits your Mac and check its own requirements. 1. Install and open Ollama using its [official Mac guide](https://docs.ollama.com/macos). 2. Download a local model through Ollama using the steps below. Choose a locally running model, not a cloud-routed model. editmd does not download or manage models for you. 3. In editmd, choose **Ollama — local on this Mac**. 4. Choose **Refresh installed models**, then select the installed **Model ID**. No API key is needed. 5. Read the local-provider disclosure, acknowledge it and choose **Save local connection**. 6. Choose **Test connection** and confirm the result lists **Ask** as supported. The result is kept only for the current app session, so test again after relaunching. A model that loads successfully in Ollama may still fail editmd's grounding checks. The connection uses the fixed local address **127.0.0.1:11434**. editmd checks for a reported remote route before sending document content. Keep Ollama running when using Ask. ### Download a local model 1. In [Ollama’s model library](https://ollama.com/library), choose a local model and size that fit your Mac. Copy its exact name and tag. Model size, memory needs and licensing differ. 2. Open **Terminal** on your Mac. Replace `MODEL_NAME` in the command below with that exact name and tag, then press Return. Wait for the download to finish. ```sh ollama pull MODEL_NAME ``` 3. Check that the model is installed: ```sh ollama ls ``` 4. Return to editmd and choose **Refresh installed models**. Select the matching entry, save the connection and run **Test connection**. `MODEL_NAME` is a placeholder, not a model recommendation. If Terminal cannot find `ollama`, finish Ollama’s Mac installation and reopen Terminal. See the [Ollama command reference](https://docs.ollama.com/cli). Downloading a model does not guarantee it will pass editmd’s grounded-Ask checks. ## If the connection test fails Check the provider, exact model ID, key access, billing or balance, and network connection. For Ollama, confirm the app is running and the model is installed locally. For OpenRouter, refresh the compatible catalog and test the chosen model again. A “structured output unavailable” result means that model cannot provide the response format editmd needs. Choose another compatible model; changing a display name does not change capability. When setup succeeds, continue with [your first AI request](/docs/ai-use/). Group: Optional AI. Handbook index: https://editmd.app/docs.md --- --- title: "Your first AI request" description: "Review the text you send, then decide what to keep." canonical: https://editmd.app/docs/ai-use/ markdown: https://editmd.app/docs/ai-use.md status: pre-release, waiting list open generated: editmd-website --- # Your first AI request Review the text you send, then decide what to keep. ## Start with a short, non-sensitive example Use a small paragraph you wrote for practice. For example: > It can be helpful to take the time to write an idea down in a way that makes sense to you. Set up and test a connection in [AI Connections](/docs/ai-setup/) first. Ask-only local models cannot run the editing exercise; use **Ask this document** instead. ## Improve a selection 1. Select the paragraph in the editor. 2. Choose **AI** in the formatting bar to open **AI document actions**. 3. Choose a ready connection and **Improve clarity**. Other selection actions include Shorten, Expand, Change tone, Translate and Custom instruction. 4. Read the exact scope shown in the dialog, including any surrounding context you choose to include. Check the provider and model. 5. Choose **Send to OpenAI** or **Send to OpenRouter**, as appropriate. macOS then asks once more; the approved text leaves your Mac only after you confirm. 6. Read each proposed edit. Choose **Accept** or **Reject**, then use **Apply accepted edits** for the changes you want. 7. Inspect the document and save with **⌘S**. Accepted edits are undoable and are not saved automatically. The apply button includes the number of accepted edits. If the document changed while a request was running, review the app's stale-result message and start again with the current text rather than forcing an old proposal into place. ## Ask a question Choose **Ask this document**, enter a question that can be answered from the document, and inspect the displayed scope. A useful first question is “What is the main idea?” For local Ollama, choose **Run with Ollama**. For a remote connection, use its **Send** action. Read the answer against your source; an answer is guidance, not a change to the file. ## Know the scope The dialog shows the authorised selection or current-document text. It does not silently add other tabs, the workspace tree, linked resources or prompt history. Sensitive information already written inside the approved text is still part of that text. Review the actual words, not only the displayed byte count. Provider policies and your authority to share the content still matter. Never include API keys in a request. ## Review, structure and metadata Remote connections can also offer document review, structure changes, and metadata/task suggestions. Available actions depend on the provider and tested model. Start with a small scope and review the proposed effect before applying it. The [website walkthrough](/docs/) uses authored sample proposals so you can learn the accept/reject interaction without connecting an account. It does not generate a response to your instruction. ## Turn it off or disconnect Turn off **Enable AI Revision & Review** in Preferences to stop using the feature. To remove a connection, use **Disconnect** (remote providers) or **Remove** (Ollama) in its saved connection controls. Disconnecting a remote connection deletes its local Keychain item; it does not revoke the key at the provider. Revoke a key in the provider account when you no longer want it usable elsewhere. Group: Optional AI. Handbook index: https://editmd.app/docs.md --- --- title: "Copy, export and share" description: "Choose an output for the person or tool receiving your writing." canonical: https://editmd.app/docs/exports/ markdown: https://editmd.app/docs/exports.md status: pre-release, waiting list open generated: editmd-website --- # Copy, export and share Choose an output for the person or tool receiving your writing. ## Keep the Markdown original Your **.md** file is the editable source. Export creates another representation for a particular use. Keep the original and its attachments so you can return to the writing later. ## Choose the right output | Destination | Use | What to check | | --------------------------- | ---------------- | ------------------------------------------------------------- | | Another Markdown editor | Markdown | Include local attachments and preserve relative paths. | | A text field or message | Plain text copy | Formatting becomes ordinary readable text. | | Pasting into a web editor | HTML copy | Structure is preserved; destination styling may change it. | | A styled web document | HTML file export | Includes highlighted code, math and diagrams. | | A rich-text app | RTF copy | A practical subset; not every block is preserved identically. | | A document to read or print | PDF | Check page breaks, wide tables and diagrams. | | An image of the document | PNG | One image of the whole document. Check size and small text. | | An ebook reader | ePub | Check layout in the target reader. | | A word-processing workflow | DOCX | Review conversion of complex formatting. | **Copy** offers Markdown, plain text, HTML and RTF. **Export** offers HTML, Markdown, PDF, PNG, ePub and DOCX. The two menus do not offer the same formats. ## Understand rich output Rich output carries formatting or a rendered appearance along with your words. Choose it when a recipient needs to read, print or reuse the finished document. Keep Markdown when they need to continue working with its source. | Format | What it gives you | Important differences | | --------- | ---------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | HTML copy | Headings, paragraphs, lists and other document structure for pasting | Mermaid stays as source code. Syntax-highlighting styles are not embedded. The receiving app controls how pasted HTML looks. | | HTML file | A styled web document with highlighted code, KaTeX math and Mermaid diagrams | Check it in a browser, including any images. It is a separate exported file. | | PDF | A document for reading and printing, with styled code, math and diagrams | Created through the system print dialog. Page breaks and wide content need a final check. | | PNG | One image of the whole rendered document | There is no per-block or per-diagram image export; crop the image if you need part of it. The recipient cannot edit its words as document text; share a text version when they need one. | | RTF copy | Basic rich text for a compatible destination | Tables, images, math, diagrams, footnotes and alerts may be flattened or omitted. | | DOCX | A document to continue editing in a word processor | A basic conversion: tables, images, math, diagrams, links and alerts may be simplified or omitted. | | ePub | An ebook with styled prose and inline Mermaid SVG diagrams | Math and SVG support depend on the ebook reader. Test in the intended reader. | For example, export a **PDF** for a meeting handout, a **DOCX** for a colleague who will revise the prose, or **HTML** for a styled technical note containing code and diagrams. For a slide, export a **PNG** of the document and crop to the part you need; check that diagram labels stay readable. For reusable source, share **Markdown** with its local attachments. ## Preview features and file formats Tables, task lists, code highlighting, KaTeX math, Mermaid diagrams, footnotes, alerts and highlighted text are features of a document's content. HTML, PDF and DOCX are output formats. A feature that works in editmd's preview does not necessarily have an equivalent in every output format. Use [Write and format](/docs/writing/#math-diagrams-and-notes) to create these blocks, then choose the output above for your recipient. A Mermaid block is diagram source inside a Markdown file; it is not a separate export-menu format. ## Export a document 1. Save the Markdown source. 2. Open the **Share** menu and choose an export format. 3. Read any format-specific guidance shown by the app. 4. Choose a destination and finish saving the output. 5. Open that output in the app your recipient will use and check it before sending. For PDF, use the macOS print dialog and choose its PDF saving option. Inspect the print preview before saving. ## Images and advanced blocks Remote resources are blocked during export, even if remote preview images are enabled. Use local attachments when an image must be included, then verify the resulting file. Math, diagrams, wide tables and custom highlights are worth checking in every target format. DOCX and RTF are practical conversions rather than promises of an identical preview layout. ## Share intentionally Saving or exporting does not send the document to another person. Attach the output to your chosen message or sharing tool. Check that the document contains only the information you intend to share. Group: Using editmd. Handbook index: https://editmd.app/docs.md --- --- title: "Update, back up and remove" description: "Replace the app safely and understand what happens to your files." canonical: https://editmd.app/docs/updates/ markdown: https://editmd.app/docs/updates.md status: pre-release, waiting list open generated: editmd-website --- # Update, back up and remove Replace the app safely and understand what happens to your files. ## Before an update Save open documents and keep a backup of important work. Check the version and compatibility information supplied with the official package. Quit editmd before replacing the app. ## Replace the app manually 1. Obtain the new package from the [official download section](/#download). 2. Open the disk image, or extract the ZIP. 3. Move the new **editmd.app** to **Applications** and confirm replacement of the existing app. 4. Eject the disk image if you used one. 5. Open editmd from Applications and check **About editmd** for the installed version. 6. Reopen a saved document and check your normal writing workflow. Replacing the application bundle is separate from your Markdown files. Keep those files and their backups in the folders you chose. Do not delete your documents as part of an app update. ## Back up the writing Use a backup method you control, such as Time Machine or a separate copy of your document folder. Include attachments. A sync service mirrors changes and may mirror deletions too; understand its version-history and recovery options. App session recovery is bounded and is not a replacement for a backup. Save recovered content after inspecting it. ## Reset local app data Reset is for clearing local application state, not for updating or changing a theme. 1. Save all changes you want to keep and close other editmd instances. 2. Open **More actions → Preferences… → Local app data** and choose **Review local reset…**. 3. Read the unsaved-document summary. Acknowledge any recovery copies that will be discarded. 4. Choose separately whether to remove editmd's stored AI keys. 5. Choose **Erase local data and quit**. In the macOS confirmation that follows, choose **Erase and quit**, or **Cancel** to keep the current state. 6. Reopen editmd if you want to start with a new local session. Saved documents and exports remain on disk. Reset does not remove provider records, backups, clipboard contents or other apps' copies. Deleting a local key does not revoke it at the provider. ## Uninstall If you want to clear local state, perform the reset before removing the app. Then quit editmd and move **editmd.app** from Applications to Trash. Removing the app alone may leave preferences or Keychain items behind. Keep or remove your document folders separately. Avoid deleting broad Library or Keychain folders, which can contain data for other apps. Group: Reference. Handbook index: https://editmd.app/docs.md --- --- title: "Keyboard shortcuts" description: "Keep your hands on the keyboard, from the first file to the final save." canonical: https://editmd.app/docs/shortcuts/ markdown: https://editmd.app/docs/shortcuts.md status: pre-release, waiting list open generated: editmd-website --- # Keyboard shortcuts Keep your hands on the keyboard, from the first file to the final save. ## Read the keys **⌘** means Command, **⇧** means Shift, **⌥** means Option and **⌃** means Control. Hold the modifier keys and press the final key once. ## Files and navigation | Action | Shortcut | | ---------------- | -------- | | New File… | ⌘N | | Open Folder… | ⌘O | | Open File… | ⌘⇧O | | Save | ⌘S | | Quick Open… | ⌘P | | Search Workspace | ⌘⇧F | | Toggle Outline | ⌘⇧E | | Preferences… | ⌘, | | Quit editmd | ⌘Q | Quitting with unsaved changes shows a save prompt first. ## Writing | Action | Shortcut | | ---------------------- | ------------- | | Undo | ⌘Z | | Redo | ⌘⇧Z | | Bold | ⌘B | | Italic | ⌘I | | Strikethrough | ⌘⇧X | | Inline code | ⌘E | | Heading 1, 2 or 3 | ⌘⌥1, ⌘⌥2, ⌘⌥3 | | Add YAML Header | ⌘⇧Y | | Find… | ⌘F | | Find and Replace… | ⌘⌥F | | Select next occurrence | ⌘D | | Go to line | ⌘⌥G | ## View | Action | Shortcut | | ------------------ | -------- | | Zoom In | ⌘= or ⌘+ | | Zoom Out | ⌘− | | Actual Size | ⌘0 | | Toggle Theme | ⌘⇧T | | Toggle Full Screen | ⌃⌘F | Toggle Theme cycles Light, Dark, then System. These are Mac app shortcuts. ## If a shortcut does not work Make sure editmd is the active app and the expected field has focus. Check its native menu for the command. Keyboard layout, macOS settings or another utility may affect a shortcut; the menu remains another way to perform the action. Group: Reference. Handbook index: https://editmd.app/docs.md --- --- title: "Troubleshooting" description: "Find the next useful action when a file, preview or connection behaves unexpectedly." canonical: https://editmd.app/docs/troubleshooting/ markdown: https://editmd.app/docs/troubleshooting.md status: pre-release, waiting list open generated: editmd-website --- # Troubleshooting Find the next useful action when a file, preview or connection behaves unexpectedly. ## The app will not open Check the [installation steps](/docs/install/) and the full macOS message. Confirm you opened the copy in Applications and that the package matches your Mac. Stop if macOS rejects the download's integrity or developer verification; do not bypass the warning. ## My Markdown looks like plain text Choose **Split** or **Preview**. Confirm the syntax has spaces where required: `# Heading`, not `#Heading`. Close any unclosed backtick fence and add blank lines between blocks. The [writing reference](/docs/writing/) includes examples. ## An image is missing Check the image's relative path and whether the attachment moved with the document. Remote preview images are off by default. Exports block remote resources even if the preview can show them, so use a local attachment and check the exported result. ## A file will not open editmd reads UTF-8 text files. A file saved in another encoding is reported as unavailable; open it in another editor and save it as UTF-8. Files reached through a symbolic link are refused; open the real file instead. ## A diagram or formula does not render Check the block language and syntax. Try a smaller example to locate the error. Complex or unsupported content may remain as source rather than a rendered diagram. Different export formats also have different capabilities. ## My changes disappeared or a conflict appeared Check the active tab and file location first. Look for a recovery notice or external-change conflict. Another editor or sync service may have changed the same file. Preserve any useful text before resolving the conflict, and check your backup or sync version history if needed. ## An AI model is missing For OpenRouter, use **Load compatible models**; the app only offers candidates that meet its route requirements. For Ollama, start the local service and use **Refresh installed models**. A model must be installed through Ollama before editmd can select it. ## AI connects, but an action is unavailable Ollama exposes grounded **Ask** only. OpenRouter and local models need the appropriate successful test for the selected model in the current app session. Test again after changing models. If structured output or grounding checks fail, choose another compatible model. ## The AI answer is wrong Compare it with the source. Reject edits that change meaning or add unsupported facts. Try a smaller, clearer scope if you want another attempt. Passing a connection test does not make every answer correct. ## What to include when reporting a problem Record the editmd version, macOS version, Apple silicon or Intel, the exact message, the steps that led to it and what you expected. Try a small synthetic document that reproduces the problem. Include a screenshot only after removing private text, file paths, provider credentials and account details. You do not need to send your full workspace to explain a bug. Group: Reference. Handbook index: https://editmd.app/docs.md --- --- title: "How editmd is built" description: "A desktop shell, a source editor and a renderer around ordinary files." canonical: https://editmd.app/docs/how-it-is-built/ markdown: https://editmd.app/docs/how-it-is-built.md status: pre-release, waiting list open generated: editmd-website --- # How editmd is built A desktop shell, a source editor and a renderer around ordinary files. ## The file comes first editmd treats Markdown source as the document. Editing changes that source; the preview is a rendering of it. Switching views does not create a second proprietary version of your writing. The app separates the writing interface from native file operations. This keeps the familiar editing surface close to the file tools provided by macOS. ## Inside the Mac app | Layer | Built with | What it does | | ------------------- | ------------------------------- | ----------------------------------------------------------------------- | | Desktop application | Tauri 2 and Rust | Connects the interface to native file, dialog and application services. | | User interface | React and TypeScript | Presents documents, preferences and review flows. | | Source editor | CodeMirror 6 | Handles Markdown text editing and editor interactions. | | Application state | Zustand | Coordinates the active workspace and interface state. | | Markdown rendering | markdown-it and DOMPurify | Converts Markdown to filtered rendered content. | | Rich content | KaTeX, Mermaid and highlight.js | Renders math, diagrams and highlighted code. | The frontend build uses Vite. Those tools are part of how the application is made; users do not install them to run the packaged Mac app. ## One source, several outputs The rendered-content pipeline is shared across preview and HTML-based output. Other formats use their own conversions, which is why export guidance distinguishes an exact source file from a practical rich-text conversion. Native file operations live in the Rust layer. AI requests also pass through app controls for provider choice, exact scope and result review. Model responses do not get direct authority to save a document. ## How this website is built The website uses **Astro** to generate static HTML. Its guides and navigation remain readable without JavaScript. Small native scripts add the hero example and motion. The hero example and the AI walkthrough on the homepage keep their text in memory and use authored examples; they are separate from the desktop app's files and provider connections. ## Why these choices matter - **Portability:** the document remains plain Markdown. - **Clarity:** the source and its preview are different views of the same writing. - **Control:** opening, saving and applying a proposed AI edit are explicit actions. - **Progressive delivery:** you can read this website without loading the editor demo. This is an explanation of the product's architecture, not a source-build installation guide. For the user workflow, begin with [install editmd](/docs/install/). Group: Reference. Handbook index: https://editmd.app/docs.md --- --- title: "Frequently asked questions" description: "Practical answers about files, the app, AI and getting your work out." canonical: https://editmd.app/docs/faq/ markdown: https://editmd.app/docs/faq.md status: pre-release, waiting list open generated: editmd-website --- # Frequently asked questions Practical answers about files, the app, AI and getting your work out. ## Getting started ### Is editmd free? Do I need an account? The editor is free and does not require an editmd account. Optional remote AI uses your own provider account and may incur API charges. Installing or using AI is not required for writing. ### Do I need to know Markdown already? No. Start with ordinary paragraphs and add headings or lists as you need them. Split view shows how your source becomes a formatted document. Follow [your first document](/docs/first-document/). ### What is the difference between .md and .txt? Both can contain plain text. The **.md** extension tells tools to interpret Markdown formatting conventions. Renaming a Word or PDF file to **.md** does not convert its contents into Markdown. ### Can I use it on Windows, Linux, iPhone or iPad? The desktop app documented here is for macOS. There is no Windows, Linux, iPhone or iPad version. ### Is the source code open source? Free use of the app and access to its source code are separate questions. This site does not provide a public source repository or a source-build download. Third-party notices describe the components included in the relevant distribution. ## Files and privacy ### Where are my documents stored? In the files and folders you choose on your Mac. editmd does not upload them to an editmd document account. Services you use for sync or backups may separately copy those folders. ### Can I open files from another Markdown editor? Yes, ordinary Markdown files can be opened directly. Check app-specific syntax, metadata and relative attachment paths; not every Markdown extension renders the same way everywhere. ### Does editmd work offline? Local writing, preview and file work do not require a provider connection. Remote AI, external links and remote image loading need their respective services. Local Ollama needs its local service running and a model already installed. ### Does it save automatically? Use **Save (⌘S)** to write edits to disk. Session recovery can preserve bounded unsaved buffers, but it is not a substitute for saving or backups. Accepted AI edits also need saving. ### Can I sync with iCloud Drive or another service? You choose where files live, including folders managed by a sync service. That service owns synchronisation. Avoid editing the same file on two devices at once and review any external-change conflict. ### Are remote images loaded automatically? No. **Load remote images** is off by default. Local workspace images are a separate case. Export blocks remote resources even when you enable them in preview. ## Optional AI ### Is AI always running? No. It starts disabled. You enable it, connect a model, inspect the scope and explicitly send each request. There is no background processing of your workspace. ### Does a ChatGPT subscription cover OpenAI API use? No. ChatGPT and the OpenAI API have separate billing. Set up API access and check its billing before adding an OpenAI connection. See [OpenAI's billing guide](https://help.openai.com/en/articles/9039756). ### Which models can I add? Direct OpenAI uses an exact model ID available to your API account. OpenRouter uses the compatible catalog shown in the app. Ollama uses installed local models that pass editmd's checks. Follow [AI setup](/docs/ai-setup/) rather than assuming every advertised model is compatible. ### Why can Ollama only answer questions? The local integration exposes grounded Ask. It does not offer local editing, structure changes, metadata/tasks or review. Those controls remain unavailable for the local connection. ### What text does AI receive? The exact approved selection or current-document scope displayed before sending, including any surrounding context you choose. editmd does not silently read other files. Sensitive information already inside the selected text is included, so review it carefully. ### Where is my API key kept? Remote-provider keys are stored in macOS Keychain. Do not put keys in documents or send them in a support screenshot. Disconnecting removes the local item; revocation is a separate action in the provider account. ### Why is there an 18+ acknowledgement? The optional AI flow requires it before enabling connections or sending requests, including local Ollama. It covers the AI use conditions and your authority to use the chosen provider. The non-AI editor remains usable without it. ## Output, updates and help ### Will PDF or DOCX look exactly like the preview? Check the exported file in its destination app. Formats preserve different features, and DOCX/RTF are practical subsets. Keep the Markdown source and see [copy, export and share](/docs/exports/). ### Will updating delete my documents? Replacing the app in Applications is separate from files you saved elsewhere. Save and back up before updating, then check your documents afterward. Follow [update and back up](/docs/updates/). ### Does uninstalling remove all local data? Removing the app alone may leave preferences and Keychain items. Use the app's reviewed local reset flow first if you want to clear those, and manage saved documents separately. See [removal](/docs/updates/#uninstall). ### I am stuck. Where should I start? Use [troubleshooting](/docs/troubleshooting/) for installation, preview, images, conflicts and AI connection issues. A small synthetic example and the exact error message make a problem much easier to diagnose. Group: Reference. Handbook index: https://editmd.app/docs.md --- --- title: "Privacy and data handling" description: "Privacy notice for editmd.app and the editmd Mac app: what we collect, why, where it goes and how to reach us." canonical: https://editmd.app/docs/privacy/ markdown: https://editmd.app/docs/privacy.md status: pre-release, waiting list open generated: editmd-website --- # Privacy and data handling Privacy notice for editmd.app and the editmd Mac app: what we collect, why, where it goes and how to reach us. Last updated 17 September 2026. ## Who is responsible Brencel AS, organisation number 829 668 602, Falsens gate 2, 3018 Drammen, Norway, is the data controller for this website. Reach us through the [Contact page](/contact/) and choose “Ask about privacy or security”, or write to the postal address above. ## Your Mac Your Markdown files and editor preferences stay on your machine. The Mac app needs no account and has no Brencel server behind it: no analytics, no advertising, no telemetry and no crash reporting. Local files can also be synced or backed up by services you choose; those services follow their own rules. ## This website This website uses no cookies, no advertising, no analytics scripts, no session replay and no third-party scripts. **Server logs.** Hosting receives ordinary page requests: IP address, browser details, the address requested, the time and the result. We use them to run and secure the site, which is our legitimate interest (GDPR Article 6(1)(f)). They are stored in Finland and deleted after 30 days. We count page views and downloads from these logs as plain totals. To stop abuse of the forms, the server also keeps a scrambled form of your IP address in memory for about one minute; it is never logged or stored. **Where the site is served.** The site is served from Finland; your connection may be handled by Google's network location nearest to you, and hosting logs are stored in Finland. **Stored in your browser.** Two things, both because you asked for them: your appearance choice, and your progress in the Markdown course. They stay in this browser and are never sent to us. No consent banner is needed for settings you chose yourself. ## Contact form When you write to us we receive the topic, your email address, your message and any version details you add. We use them to answer you, which is our legitimate interest in handling enquiries (Article 6(1)(f)). The message is delivered by our mail service to our mailbox at Google Workspace. We delete contact messages 12 months after our last reply. Server logs never contain your message or your address. ## Waiting list Joining the waiting list sends a confirmation email. You are added to the release list only after opening the link and pressing the confirmation button. We record the consent-text version and confirmation time with your address in Resend. The legal basis is your consent (Article 6(1)(a)). We use the address for one message, when the first release is ready, and delete it within 30 days after that message, and in any case 12 months after you confirmed. You can withdraw at any time through the [Contact page](/contact/); choose “Ask about privacy or security”. Withdrawing does not affect what happened before. ## AI providers Optional AI in the Mac app is off until you connect a provider. editmd generates nothing itself; it sends the text you chose to the provider you chose, which can be a local model on your Mac. Your API keys stay in the macOS Keychain. Brencel receives none of this traffic. The provider's account terms, charges and retention apply to that text. ## Who receives your data - **Google Cloud EMEA Limited**, Ireland: hosting, server logs and network delivery for this site, and the Google Workspace mailbox where contact messages arrive. - **Resend (Plus Five Five, Inc.)**, United States: sends our email and holds the waiting list. Resend processes and stores this data in the United States: your email address, your contact message with any version details, waiting-list confirmation emails and consent records. It keeps delivery records for a short period set by its service plan. See [Resend’s data-location explanation](https://resend.com/security/gdpr). Your details are not displayed publicly, sold or used for marketing. Discord and GitHub, which we link to, are separate services with their own privacy rules. ## Transfers outside the EEA Finland hosting and log storage do not mean every processing step stays in the EEA. Google’s global network can handle connections outside the EEA, and Resend processes the mail data described above in the United States. We rely on the EU standard contractual clauses in each provider’s data processing addendum: [Google Cloud Data Processing Addendum](https://cloud.google.com/terms/data-processing-addendum) and [Resend’s Data Processing Addendum](https://resend.com/legal/dpa). Both providers also take part in the EU-US Data Privacy Framework. ## Your rights You can ask us for access to your information, to correct or delete it, to restrict how we use it, or to receive a copy of what you gave us. You can object to processing we base on legitimate interest, and withdraw waiting-list consent at any time. Use the [Contact page](/contact/) and choose “Ask about privacy or security”; we answer within one month. You can also complain to the Norwegian Data Protection Authority, [Datatilsynet](https://www.datatilsynet.no/), or to the authority where you live. Giving us information is voluntary, and we make no automated decisions about you. ## Every destination, in order 1. **Your Mac.** Files, preferences and appearance. Always. 2. **Hosting.** Ordinary page requests when you visit this site. 3. **AI provider.** Only the scope you review, only when you send it. 4. **Mail service.** Only when you write to us or join the waiting list. Group: Reference. Handbook index: https://editmd.app/docs.md --- --- title: "Changelog" description: "Release notes for editmd. No public release has been published yet." canonical: https://editmd.app/docs/changelog/ markdown: https://editmd.app/docs/changelog.md status: pre-release, waiting list open generated: editmd-website --- # Changelog No public release has been published yet. The first release notes will appear here with version, summary, changes and known limitations once the exact build has passed verification. Waiting list: https://editmd.app/waiting-list/ --- --- title: "Markdown School" description: "Twelve practical lessons with narrated videos, editable examples and exercises. Markdown foundations, YAML metadata and AI instruction files." canonical: https://editmd.app/learn/ markdown: https://editmd.app/learn.md status: pre-release, waiting list open generated: editmd-website --- # Markdown School Twelve lessons. Each has a narrated video, an editable example and an exercise. No account; progress stays in the browser. ## Lessons 01. [A small format. A lasting idea.](https://editmd.app/learn/lessons/origins.md): Meet Markdown: readable text that can become a structured document. 02. [Choose the format for the work.](https://editmd.app/learn/lessons/formats.md): Use Markdown where readable, portable writing helps—and recognize when another format fits better. 03. [Make a note easier to scan.](https://editmd.app/learn/lessons/headings.md): Give every idea a place with a title and section headings. 04. [Turn a list into next steps.](https://editmd.app/learn/lessons/tasks.md): Write ordinary lists, ordered steps and checkable tasks. 05. [Make your references useful.](https://editmd.app/learn/lessons/links.md): Connect an idea to its source with a link that tells the reader what to expect. 06. [Ask for a review. Keep your judgment.](https://editmd.app/learn/lessons/review.md): Give AI a bounded task, then verify the suggestions before changing your document. 07. [Read YAML as structured data.](https://editmd.app/learn/lessons/yaml-basics.md): Build named values, lists and nested settings, then separate syntax from meaning. 08. [Give a document useful metadata.](https://editmd.app/learn/lessons/yaml-front-matter.md): Combine YAML and Markdown, compare literal and folded text, and check a small schema. 09. [Write scoped instructions for Codex.](https://editmd.app/learn/lessons/agents-md.md): Create a concise AGENTS.md and reason about directory scope with a fictional project. 10. [Make Claude project guidance checkable.](https://editmd.app/learn/lessons/claude-md.md): Replace vague instructions with concrete project facts and verify what Claude Code loads. 11. [Inspect Gemini CLI context.](https://editmd.app/learn/lessons/gemini-md.md): Write GEMINI.md guidance, inspect loaded context and distinguish editing from reloading. 12. [Build and test a focused skill.](https://editmd.app/learn/lessons/skill-md.md): Combine discovery metadata, a bounded procedure and positive and negative test cases. ## Example projects - Meeting notes that lead somewhere: https://editmd.app/learn/examples/meeting-notes.md - A welcoming project README: https://editmd.app/learn/examples/project-readme.md --- --- title: "A small format. A lasting idea." description: "Meet Markdown: readable text that can become a structured document." canonical: https://editmd.app/learn/lessons/origins/ markdown: https://editmd.app/learn/lessons/origins.md status: pre-release, waiting list open generated: editmd-website --- # A small format. A lasting idea. Lesson 01 of 12 in Markdown School. Meet Markdown: readable text that can become a structured document. ## Before the preview, there was plain text Open a Markdown file in a text editor and you see the words together with a few simple marks. `#` can introduce a heading. Asterisks can mark emphasis. A renderer interprets those marks and displays a structured document. The `.md` extension is a filename convention; you do not need a special app to read the text. John Gruber introduced Markdown on **15 March 2004** to help people write for the web using readable plain text that converts to HTML. His original announcement describes a text-to-HTML tool and publishing integrations. [Read the original announcement](https://daringfireball.net/2004/03/introducing_markdown). Aaron Swartz contributed ideas, design feedback and testing. Gruber also credits plain-text email as a major influence on the syntax. [Project description and acknowledgements](https://daringfireball.net/projects/markdown/). ## One file, two ways to read it ```markdown # Garden notes A little room to **grow**. ``` The source has a heading and a paragraph. The preview displays their meaning through typography. Font choice, colours and page layout belong to the renderer; they are not stored in those Markdown marks. A Markdown file is useful for notes, project documentation and other structured writing. GitHub, for example, displays Markdown READMEs as an introduction to a repository. [GitHub’s README guide](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes). ## Why it appears in AI workflows Modern tools also read Markdown as context and instructions. That is a newer application of readable text, not Markdown’s original purpose. A heading helps organize your request; it does not prove the content is correct. We will practise a bounded review in [the AI lesson](/learn/lessons/review/). ## Try it, then explain it Change the source below. Afterwards, explain which characters belong to the title itself and which characters tell the renderer that it is a heading. You should be able to read your note without relying on the preview. ## Exercise Write a # title for a note, leave a blank line, then add a short paragraph. Try changing the title and watch the result. ## Takeaway The .md file is ordinary text. A renderer gives its marks a visual form. Related guide: https://editmd.app/docs/markdown/. All lessons: https://editmd.app/learn.md --- --- title: "Choose the format for the work." description: "Use Markdown where readable, portable writing helps—and recognize when another format fits better." canonical: https://editmd.app/learn/lessons/formats/ markdown: https://editmd.app/learn/lessons/formats.md status: pre-release, waiting list open generated: editmd-website --- # Choose the format for the work. Lesson 02 of 12 in Markdown School. Use Markdown where readable, portable writing helps—and recognize when another format fits better. ## Begin with what the document must do Imagine three tasks: explain a project, calculate a monthly budget and design a print brochure. Each has a different requirement. For the guide, headings, paragraphs and links are the main work. For the budget, calculations matter. For the brochure, precise placement matters. Our practical recommendation: use Markdown for structured prose; use a spreadsheet when formulas and data operations dominate; use a layout tool when exact page composition is the task. This is a choice about the work, not a ranking of formats. ## A useful project introduction ```markdown # Garden guide A shared reference for our neighbourhood garden. ## Start here Read the planting notes, then choose one task. ## Get involved Bring an idea to the next garden meeting. ``` A README commonly introduces a project, explains its usefulness and helps people get started. The example above is deliberately small. A real project may also need installation requirements, usage examples, contribution guidance and support information. [GitHub’s README guidance](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes). ## Source and delivery can differ You can write in Markdown and deliver another format. Keep the `.md` file as your editable source, then choose the output for the recipient. A PDF is a useful reading copy. A word-processing document may fit a colleague’s editing workflow. The [editmd export guide](/docs/exports/) explains what each conversion preserves. ## Portability has a boundary CommonMark defines a core syntax. GitHub Flavored Markdown adds features such as tables and task lists. Mermaid diagrams and math depend on additional renderer support. Check the destination rather than assuming every preview will look the same. [CommonMark specification](https://spec.commonmark.org/), [GFM specification](https://github.github.com/gfm/). ## Choose your first project Write a purpose statement and explain your format choice in the practice area. Two hashes and a space make a section heading, such as `## Purpose`; [the headings lesson](/learn/lessons/headings/) explains heading levels. For a starter you can keep, the [school home](/learn/#take-a-project-with-you) includes a complete meeting-notes file and README. ## Exercise Write ## Purpose and ## Why Markdown. Under each heading, explain the document you want to create and why Markdown fits. The check confirms headings; you judge the choice. ## Takeaway Choose the format around the next person or tool that will use your work. Related guide: https://editmd.app/docs/exports/. All lessons: https://editmd.app/learn.md --- --- title: "Make a note easier to scan." description: "Give every idea a place with a title and section headings." canonical: https://editmd.app/learn/lessons/headings/ markdown: https://editmd.app/learn/lessons/headings.md status: pre-release, waiting list open generated: editmd-website --- # Make a note easier to scan. Lesson 03 of 12 in Markdown School. Give every idea a place with a title and section headings. ## A title, then useful sections A meeting note can contain the right information and still be hard to use. A title identifies the document. Section headings tell the reader where to find a decision or an action. For this style of heading, place one to six `#` characters at the beginning of a line, followed by a space and the heading text. More marks mean a deeper level. [CommonMark heading syntax](https://spec.commonmark.org/0.31.2/#atx-headings). ```markdown # Garden meeting ## Decisions Keep the reading bench. ## Actions Mira will draw the layout. ``` ## Build a hierarchy the reader can follow Use one main title for this exercise. Under it, use second-level headings for major sections. A third-level heading can divide one of those sections further. Make the heading describe its content: “Decisions” is more useful here than “More information”. ```markdown ## Actions ### Before the next meeting Sketch two possible layouts. ``` Avoid choosing a heading level only because you prefer its font size. The structure should make sense even in a renderer with different styling. ## Separate paragraphs clearly Leave a blank line between paragraphs. A line break in the source alone is not generally a new paragraph. Blank lines around headings also make the source easier to scan. [CommonMark paragraphs](https://spec.commonmark.org/0.31.2/#paragraphs). ## Practise with a rough note Organize the supplied note into a title, decisions and actions. Then change a heading and watch the preview. The check looks for real heading tokens, so writing `#` inside a fenced code example will not pass as a document heading. ## Exercise Create one # title, a ## Decisions section and a ## Actions section. Put the relevant notes beneath each heading. ## Takeaway Use headings for a meaningful hierarchy, not just larger type. Related guide: https://editmd.app/docs/writing/. All lessons: https://editmd.app/learn.md --- --- title: "Turn a list into next steps." description: "Write ordinary lists, ordered steps and checkable tasks." canonical: https://editmd.app/learn/lessons/tasks/ markdown: https://editmd.app/learn/lessons/tasks.md status: pre-release, waiting list open generated: editmd-website --- # Turn a list into next steps. Lesson 04 of 12 in Markdown School. Write ordinary lists, ordered steps and checkable tasks. ## Use a list when items belong together Start each item with a hyphen and a space. An ordinary list can hold supplies, questions or ideas. Use a numbered list when the order is part of the meaning. [CommonMark lists](https://spec.commonmark.org/0.31.2/#lists). ```markdown - A measuring tape - A notebook - Two layout sketches ``` ```markdown 1. Measure the space. 2. Compare the sketches. 3. Choose a layout. ``` ## Add a completion state A task list adds `[ ]` for an open task or `[x]` for a completed task after the list marker. Include a space before the task text. Task lists are a GFM extension, so support depends on the renderer. [GFM task list items](https://github.github.com/gfm/#task-list-items-extension-). ```markdown - [x] Sketch the layout - [ ] Bring a measuring tape ``` The practice preview shows the state as a symbol. Change the source to update it. In editmd’s Mac preview, supported task checkboxes can update the corresponding source marker; the [writing guide](/docs/writing/#tables-and-tasks) explains that behaviour. ## Write tasks someone can act on “Bench” names a subject. “Measure the bench before choosing a layout” describes an action. Add an owner or date when the facts are known. If they are unknown, leave a question rather than inventing an assignment. ## Try an open task and a finished one Mark one supplied task complete and add another action. The check confirms that the source contains both states. It cannot know whether the work actually happened. ## Exercise Keep at least one open task and one completed task. Add a useful action of your own and decide whether it is done. ## Takeaway Lists group information. Tasks also record whether work is complete. Related guide: https://editmd.app/docs/writing/. All lessons: https://editmd.app/learn.md --- --- title: "Make your references useful." description: "Connect an idea to its source with a link that tells the reader what to expect." canonical: https://editmd.app/learn/lessons/links/ markdown: https://editmd.app/learn/lessons/links.md status: pre-release, waiting list open generated: editmd-website --- # Make your references useful. Lesson 05 of 12 in Markdown School. Connect an idea to its source with a link that tells the reader what to expect. ## A label and a destination A Markdown link has two parts: the text the reader sees in square brackets and the destination in parentheses. Keep them together. [CommonMark links](https://spec.commonmark.org/0.31.2/#links). ```markdown [CommonMark syntax reference](https://commonmark.org/help/) ``` “CommonMark syntax reference” tells the reader more than “click here”. Pick a label that makes sense in the surrounding sentence and when scanned on its own. ## Put the reference beside the claim A research note should make it easy to tell which source supports which statement. Place a reference next to the relevant passage. Keep your observations, quotations and interpretation distinguishable. Open the source and check it; plausible link text is not evidence that a source exists or supports the claim. ## Links inside a project A relative link points from the current document to another file. Moving files can break that relationship. Keep your project structure consistent and check links where the document will be used. ```markdown [Planting notes](notes/planting.md) ``` An image uses a related syntax with an exclamation mark. Its text should describe the image meaningfully. Unlike a link, a renderer may load an image automatically, so understand the application’s image settings. [CommonMark images](https://spec.commonmark.org/0.31.2/#images). ```markdown ![Two possible bench layouts](images/bench-layouts.png) ``` ## Practise without leaving your draft The lesson preview displays link labels without making them navigable, and displays image descriptions without fetching images. This keeps experimentation on the page. Copy your source into your document when you want to check the real destination. ## Exercise Add a descriptive Markdown link to an HTTPS page. For this exercise, use https://commonmark.org/help/ and choose a useful label. ## Takeaway A useful label explains the destination; a link alone does not prove a claim. Related guide: https://editmd.app/docs/writing/. All lessons: https://editmd.app/learn.md --- --- title: "Ask for a review. Keep your judgment." description: "Give AI a bounded task, then verify the suggestions before changing your document." canonical: https://editmd.app/learn/lessons/review/ markdown: https://editmd.app/learn/lessons/review.md status: pre-release, waiting list open generated: editmd-website --- # Ask for a review. Keep your judgment. Lesson 06 of 12 in Markdown School. Give AI a bounded task, then verify the suggestions before changing your document. ## Give the request a shape An AI review is easier to assess when you state the task, supply the relevant material and describe the result you need. Markdown headings are one way to separate these parts. Clear instructions, context and examples are common prompting guidance; headings alone do not guarantee a correct answer. [Anthropic’s prompting guidance](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices). ```markdown ## Goal Find unclear actions in these meeting notes. ## Context We agreed to update the guide. ## Constraints Do not invent an owner or date. Review only. ## Output Quote each unclear passage and suggest a question. ``` ## Review a suggestion against the source The note above does not name an owner or deadline. A suggestion such as “Mira will update the guide on Friday” adds facts that are absent. A useful response would ask who owns the action and when it is due. Keep the uncertainty visible until someone can resolve it. This is a teaching example, not a live model response. No text from the practice area is sent to an AI provider. ## Separate three different checks | Check | What it can tell you | What it cannot establish | | ------------ | -------------------------------------------------------- | ----------------------------------------------- | | Structure | The expected headings or markers are present | Whether a statement is true | | AI review | Possible ambiguity, contradictions or improvements | That every finding is correct or complete | | Verification | What the relevant source, calculation or person supports | An automatic guarantee about the whole document | ## Keep scope and control visible Read the material you plan to send. With a hosted provider, understand which text goes to that provider. A local model has different setup requirements. In editmd, [connect your chosen provider](/docs/ai-setup/), then follow [your first AI request](/docs/ai-use/) to inspect scope and review the result. editmd’s own Review action reads the document you have open and shows exactly what will be sent before you confirm; a written request like the one above suits a tool that takes a typed prompt, such as a chat assistant or editmd’s Custom instruction. A revision should preserve your intended meaning. Accept useful changes, reject unsupported ones and save deliberately. The practice task below only checks the structure of your review request; your judgment remains part of the work. ## Exercise Write a review request with ## Goal, ## Context, ## Constraints and ## Output. Include the note, limit the task and say how findings should be returned. This exercise makes no AI request. ## Takeaway AI can suggest a change. You check its evidence, meaning and scope before accepting it. Related guide: https://editmd.app/docs/ai-use/. All lessons: https://editmd.app/learn.md --- --- title: "Read YAML as structured data." description: "Build named values, lists and nested settings, then separate syntax from meaning." canonical: https://editmd.app/learn/lessons/yaml-basics/ markdown: https://editmd.app/learn/lessons/yaml-basics.md status: pre-release, waiting list open generated: editmd-website --- # Read YAML as structured data. Lesson 07 of 12 in Markdown School. Build named values, lists and nested settings, then separate syntax from meaning. ## What is YAML, and when would you use it? YAML is a text format for structured data. Markdown gives prose headings and lists; YAML gives a program named values, ordered collections and nested records. A `.yaml` or `.yml` file commonly holds settings or metadata. It is not a programming language, and a value cannot perform an action by itself. [YAML specification, introduction](https://yaml.org/spec/1.2.2/#chapter-1-introduction-to-yaml). For this original exercise, imagine a tool that reads metadata for a garden guide. These names are our invented contract, not settings in editmd: ```yaml title: Garden guide draft: true code: '007' tags: - planning - writing owner: name: Mira ``` ## Read the shape before editing `title` names a string. `draft` holds a boolean, while the quoted `"007"` stays text. `tags` holds a sequence; `owner` holds a mapping with its own `name`. Colons separate keys from values. Use spaces for indentation, not tabs. The nesting matters more than visual alignment. [YAML collections](https://yaml.org/spec/1.2.2/#21-collections), [indentation](https://yaml.org/spec/1.2.2/#61-indentation-spaces). Try reading the example aloud as a record: “The guide has a title, a draft state, a code, two tags and an owner.” If that sentence does not describe your intended data, a successful parse will not fix it. ## Quote text that could be mistaken for something else ```yaml label: 'Plan: first draft' reference: '#garden' code: '007' draft: false ``` Quoting makes the intended strings explicit. By contrast, `false` here is a boolean. A quoted `"false"` is a string. A receiving tool can reject the wrong type even when the YAML is valid. Comments begin with `#` in the appropriate position; the hash inside the quoted reference belongs to the string. [YAML scalars](https://yaml.org/spec/1.2.2/#23-scalars). ## A small mistake changes the data ```yaml owner: name: Mira ``` This can parse, but `name` is a top-level key and `owner` has no supplied value. Indent `name` beneath `owner` to express the relationship. The exercise separates syntax errors from mismatches with its expected fields. Neither check knows whether Mira is the actual owner. The local practice checker uses YAML 1.2 and deliberately excludes custom tags and aliases. That keeps this beginner exercise bounded; it does not mean those features are forbidden by YAML. ## Practice, then transfer Add the tags and owner to the starter. Compare the parsed result, then deliberately unindent `name` and check again. Finally, change the fictional owner and choose tags for a different document. Keep the structure; make the content your own. Do not put passwords or private account details in configuration examples. Sources checked 17 September 2026. Host behavior can change; verify it against the linked documentation when using these examples. ## Exercise Add two tags and a nested owner mapping. Keep draft a boolean and quote the code so its leading zero stays visible. ## Takeaway YAML represents data; the receiving tool decides what that data means. Related guide: https://editmd.app/docs/writing/. All lessons: https://editmd.app/learn.md --- --- title: "Give a document useful metadata." description: "Combine YAML and Markdown, compare literal and folded text, and check a small schema." canonical: https://editmd.app/learn/lessons/yaml-front-matter/ markdown: https://editmd.app/learn/lessons/yaml-front-matter.md status: pre-release, waiting list open generated: editmd-website --- # Give a document useful metadata. Lesson 08 of 12 in Markdown School. Combine YAML and Markdown, compare literal and folded text, and check a small schema. ## Put metadata before the document Some tools read a YAML block at the beginning of a Markdown file as _front matter_. Astro is one example. Its delimiters and accepted fields are a tool convention, not a universal Markdown feature. Check the target tool before using them. [Astro Markdown front matter](https://docs.astro.build/en/guides/markdown-content/#frontmatter), [CommonMark specification](https://spec.commonmark.org/0.31.2/). ```markdown --- title: Garden guide draft: false --- # Garden guide A plan for a shared space. ``` In our exercise, the first block is metadata and the later heading is prose. A renderer that does not support front matter may show the delimiters or interpret them as Markdown. Metadata remains in the raw file even when a preview hides it. ## Preserve lines or fold them ```yaml summary: | First line. Second line. description: > A short garden guide. ``` The literal form `|` retains the line break between these ordinary lines. The folded form `>` turns that ordinary break into a space. Blank lines and more-indented lines have additional rules. This lesson uses the simple case; inspect the parser output rather than assuming every newline behaves identically. [YAML block scalars](https://yaml.org/spec/1.2.2/#81-block-scalar-styles). For a postal address, preserving lines may be useful. For a description wrapped across source lines, folding may be useful. Neither choice improves factual accuracy. ## Check syntax, then the receiving tool's rules Our fictional document contract requires `title` as text and `draft` as a boolean. The two descriptions are strings. The browser checks that contract and shows the parsed metadata separately from the Markdown body. ```yaml draft: 'false' # Valid YAML; wrong type for this exercise. ``` Remove the quotes to supply a boolean. Notice that the syntax could be valid before and after the change. Similarly, a correct `draft` field does not universally hide a page: only a tool that implements that behavior can do so. ## Practice with a deliberate mistake Repair the starter, add both block-scalar examples and retain a Markdown heading below the closing delimiter. Inspect the escaped `\n` characters in the parsed result. Then change `draft` back to a string and run the check. You should receive a field/type message rather than a syntax error. For a real publishing system, check its schema and preview a disposable document before publishing. The exercise performs no publishing, file access or AI request. Sources checked 17 September 2026. Host behavior can change; verify it against the linked documentation when using these examples. ## Exercise Make title a nonempty string and draft a boolean. Include a literal summary, a folded description and a Markdown title below the closing delimiter. ## Takeaway Valid YAML, valid metadata and accurate writing are three different checks. Related guide: https://editmd.app/docs/writing/. All lessons: https://editmd.app/learn.md --- --- title: "Write scoped instructions for Codex." description: "Create a concise AGENTS.md and reason about directory scope with a fictional project." canonical: https://editmd.app/learn/lessons/agents-md/ markdown: https://editmd.app/learn/lessons/agents-md.md status: pre-release, waiting list open generated: editmd-website --- # Write scoped instructions for Codex. Lesson 09 of 12 in Markdown School. Create a concise AGENTS.md and reason about directory scope with a fictional project. ## Project guidance has a particular filename Codex reads `AGENTS.md` as project instructions. The uppercase plural name matters; an arbitrary `agent.md` is not automatically the same convention. Codex builds a chain of applicable instruction files from broader scope toward the working directory. Within a directory, `AGENTS.override.md` takes precedence over `AGENTS.md`. [OpenAI's AGENTS.md guide](https://developers.openai.com/codex/guides/agents-md/). These files supply context. They do not change model weights, prove facts or replace the host's actual permission controls. ## Start with a small, observable contract This is an original example for a fictional project whose package script really is `npm test`. Replace it with the command your project actually supports: ```markdown # Garden project ## Scope Edit documentation only. ## Checks Run npm test and report failures. ## Boundaries Ask before publishing. Do not invent results. ``` “Use good practices” is difficult to evaluate. “Report the command and its result” gives a reviewer evidence to inspect. Keep project facts separate from a one-off user request, and remove stale commands when the project changes. ## Reason about a directory tree ```text garden-project/ AGENTS.md docs/ AGENTS.md planting.md ``` For work launched in `docs/`, identify both instruction files on the route from the root. A useful `docs/AGENTS.md` could add “Preserve existing source links.” Do not assume the same discovery model applies to Claude Code or Gemini CLI; their lessons document their own mechanisms. [Codex discovery and verification](https://developers.openai.com/codex/guides/agents-md/). ## Test the instruction, not just its headings In a disposable project, ask Codex to identify the instruction sources it loaded and propose a documentation-only change. Inspect whether its proposed scope matches the files you intended. Give it a small change, then compare the reported test command with the actual terminal result. A model saying “all tests passed” is not itself evidence. Try a second request that would require publishing. The example says to ask first. Record what happened; writing the boundary is not proof that it was enforced. Use actual permissions to control tools and external effects. ## Your exercise Write the three sections below using the supplied fictional facts. The browser checks headings, nonempty sections and the named test command. It does not launch Codex or certify that your instructions will be followed. After it passes, explain which rule belongs at the root and which belongs only under `docs/`. Sources checked 17 September 2026. Host behavior can change; verify it against the linked documentation when using these examples. ## Exercise Write a project title and populated Scope, Checks and Boundaries sections. Name the supplied test command and keep publication outside this task. ## Takeaway Use the exact filename, inspect scope and test behavior on a small task. Related guide: https://editmd.app/docs/ai-use/. All lessons: https://editmd.app/learn.md --- --- title: "Make Claude project guidance checkable." description: "Replace vague instructions with concrete project facts and verify what Claude Code loads." canonical: https://editmd.app/learn/lessons/claude-md/ markdown: https://editmd.app/learn/lessons/claude-md.md status: pre-release, waiting list open generated: editmd-website --- # Make Claude project guidance checkable. Lesson 10 of 12 in Markdown School. Replace vague instructions with concrete project facts and verify what Claude Code loads. ## Use CLAUDE.md for maintained project context Claude Code supports project instructions in `CLAUDE.md` or `.claude/CLAUDE.md`. It also has user-level guidance and automatic memory, which serve different scopes. Instruction files are context for the model, not settings that mechanically enforce every sentence. [Anthropic's memory guide](https://code.claude.com/docs/en/memory). A README usually helps people understand a project. A CLAUDE.md can hold working conventions an agent needs repeatedly. Avoid duplicating an entire README when a short reference and a few concrete rules will do. ## Improve a vague rule Before: ```markdown Write good documentation. Be careful. Test everything. ``` After, for our fictional garden project: ```markdown # Garden project ## Project Keep garden notes in docs/. Use short headings. ## Checks Run npm test and report its result. ## Boundaries Ask before publishing or sending messages. ``` The revised version names a location, a writing convention, an actual project command and an external-action boundary. It still needs judgment: a heading can be short and unhelpful. Read the resulting document as well as checking compliance. ## Find the file you are actually using In Claude Code, `/memory` lists memory-file locations for inspection and editing. Use `/context` to inspect which files loaded into the current session. A listed location is not the same thing as a loaded instruction. Imports and nested project guidance have their own documented behavior. [Inspecting Claude Code memory](https://code.claude.com/docs/en/memory#view-and-edit-with-memory). For the exercise, use a disposable folder with one project file first. Ask for a proposed documentation edit and inspect the context before judging the result. Add more scopes only when you can explain why they are needed. ## Separate repeated procedures from project facts “Notes live in docs/” is a project fact. “Review meeting notes and return missing owners” is a reusable task procedure. The latter may belong in a skill loaded when needed. Claude Code supports its own skill discovery and invocation controls; they are not universal YAML fields for every agent host. [Anthropic skills guide](https://code.claude.com/docs/en/skills). ## Practice and inspect Complete the starter with the supplied facts. The browser checks the requested structure and command, not whether Claude will obey. In a real host test, record the host version, loaded file, exact prompt, output and observed result. If the instruction fails, make it more specific or remove conflicting guidance; do not add ten near-duplicate warnings. Sources checked 17 September 2026. Host behavior can change; verify it against the linked documentation when using these examples. ## Exercise Write a project title and populated Project, Checks and Boundaries sections. Use the fictional npm test command, and state that files must not be published without approval. ## Takeaway A concise project file is useful context, not an enforcement system. Related guide: https://editmd.app/docs/ai-use/. All lessons: https://editmd.app/learn.md --- --- title: "Inspect Gemini CLI context." description: "Write GEMINI.md guidance, inspect loaded context and distinguish editing from reloading." canonical: https://editmd.app/learn/lessons/gemini-md/ markdown: https://editmd.app/learn/lessons/gemini-md.md status: pre-release, waiting list open generated: editmd-website --- # Inspect Gemini CLI context. Lesson 11 of 12 in Markdown School. Write GEMINI.md guidance, inspect loaded context and distinguish editing from reloading. ## A Markdown file can supply tool-specific context Gemini CLI uses `GEMINI.md` files for persistent instructions. Its documented hierarchy includes global, workspace and more local context. The resulting instructions depend on the working location and configured discovery behavior. [Google's GEMINI.md guide](https://geminicli.com/docs/cli/gemini-md/). Do not copy a Codex precedence diagram and relabel it Gemini. Similar-looking files are interpreted by different hosts. Start with the smallest project example you can inspect. ## Write an original project contract ```markdown # Garden project ## Context Garden notes live in docs/. ## Checks Run npm test and report failures. ## Boundaries Review only. Ask before changing files. ``` The command is a supplied fact for our fictional project, not a command every Markdown folder supports. For your own project, check its scripts before including it. “Review only” describes the requested task; host permissions remain the mechanism that controls file writes. ## Inspect before and after an edit Inside Gemini CLI, these commands serve different purposes: ```text /memory show /memory reload ``` `show` displays the combined loaded context. `reload` rescans the configured locations. Edit the disposable project's file, reload, then show it again and look for the exact changed sentence. [Google's context commands](https://geminicli.com/docs/cli/gemini-md/#manage-context-with-the-memory-command). The browser exercise below does not run those commands. It helps you write the file before testing it in your own installed host. ## Make a useful observation Try a review request for a short fictional document. Record whether the output reports concerns without editing the file. Compare the file before and after; do not use the agent's own assurance as your only check. Try a folder with additional context only after the single-file test is understandable. If old guidance remains, inspect loaded sources and configuration. If the context is correct but behavior is wrong, improve the instruction and repeat the small test. These are different diagnoses. ## Project facts versus reusable work Keep always-relevant project facts here. Put an on-demand procedure in a skill when it has a clear trigger, input and output. Google recommends focused descriptions and loading detailed references only when needed. [Gemini skill best practices](https://geminicli.com/docs/cli/skills-best-practices/). In the exercise, write the three requested sections. Passing means the browser found that structure and the sample command; it makes no claim about actual Gemini behavior or factual correctness. Sources checked 17 September 2026. Host behavior can change; verify it against the linked documentation when using these examples. ## Exercise Write a title and populated Context, Checks and Boundaries sections. Include npm test and an explicit review-only boundary. ## Takeaway Inspect the context your tool loaded, rather than assuming a filename was enough. Related guide: https://editmd.app/docs/ai-use/. All lessons: https://editmd.app/learn.md --- --- title: "Build and test a focused skill." description: "Combine discovery metadata, a bounded procedure and positive and negative test cases." canonical: https://editmd.app/learn/lessons/skill-md/ markdown: https://editmd.app/learn/lessons/skill-md.md status: pre-release, waiting list open generated: editmd-website --- # Build and test a focused skill. Lesson 12 of 12 in Markdown School. Combine discovery metadata, a bounded procedure and positive and negative test cases. ## A skill is a repeatable procedure Project instructions supply recurring context; a skill describes a task that should load when relevant. The Agent Skills format uses a directory containing `SKILL.md`, beginning with YAML `name` and `description`, followed by Markdown instructions. Supporting files are optional. [Agent Skills specification](https://agentskills.io/specification). Our example reviews fictional meeting notes. It does not need code, credentials or an external service. ```markdown --- name: meeting-notes-review description: Review supplied meeting notes for missing owners and dates. Use when asked to check meeting follow-ups. --- # Review meeting notes ## Input Use supplied notes; ask if absent. ## Procedure Quote each unclear action. Do not invent owners or dates. ## Output Return Passage, Concern and Question. ## Boundaries Review only. Do not edit or send messages. ``` ## Make discovery specific “Help with writing” overlaps many tasks. The description above names the material, the action and the moment to use it. OpenAI recommends focused skills and testing the requests that should activate them. [OpenAI skills](https://developers.openai.com/codex/skills/). The folder name should match the skill name. Start with one file. Add a referenced rubric when detail becomes unwieldy; add a script only when deterministic work justifies it. Google distinguishes discovery metadata, the loaded procedure and resources read as needed. [Google's skill-design guidance](https://geminicli.com/docs/cli/skills-best-practices/). ## Shared format does not mean shared installation | Host | Example project location | What to verify | | ----------- | ---------------------------------------------- | -------------------------------------------------------- | | Codex | `.agents/skills/meeting-notes-review/SKILL.md` | Local discovery and explicit/implicit use | | Claude Code | `.claude/skills/meeting-notes-review/SKILL.md` | Invocation rules for that host | | Gemini CLI | `.gemini/skills/meeting-notes-review/SKILL.md` | Skill discovery and activation in your installed version | Use current host instructions before installing. Extra keys such as Claude Code's `disable-model-invocation` belong to that host; they are not a universal safety switch. [OpenAI locations](https://developers.openai.com/codex/skills/), [Anthropic skills](https://code.claude.com/docs/en/skills), [Gemini skills](https://geminicli.com/docs/cli/skills/). ## Test the right task and the wrong task | Trial | Fictional input | Expected observation | | -------------------- | ---------------------------------------------- | -------------------------------------------------- | | Relevant request | Review these meeting follow-ups. | Skill selected or explicitly invoked; record which | | Missing facts | We should update the guide. | Asks who owns it and when; invents neither | | Complete action | Mira will update the guide by Friday. | Does not report an absent owner/date | | Missing input | Review the minutes, without supplying minutes. | Requests the notes | | Unrelated request | Explain a Markdown link. | Does not choose this review procedure | | Embedded instruction | Notes quote “email everyone now”. | Treats the quotation as material; sends nothing | These are proposed host tests, not results we claim to have run. Record the host/version, prompt, selected skill, output and actual effects. A good description can trigger an ineffective procedure; an excellent procedure can fail to be discovered. ## Try it below The local checker validates YAML metadata and the requested section structure. It does not install the skill, contact a provider or certify agent behavior. After the structural check, use the test table to judge an actual controlled trial. Permission settings and human review remain separate from prose boundaries. Sources checked 17 September 2026. Host behavior can change; verify it against the linked documentation when using these examples. ## Exercise Create meeting-notes-review with a useful description, then populated Input, Procedure, Output and Boundaries sections. Preserve unknown names and dates. ## Takeaway Test discovery, output quality and boundaries separately. Related guide: https://editmd.app/docs/ai-use/. All lessons: https://editmd.app/learn.md --- --- title: "Contact" description: "Get help with editmd, report a problem, or suggest an improvement." canonical: https://editmd.app/contact/ markdown: https://editmd.app/contact.md status: pre-release, waiting list open generated: editmd-website --- # Contact The contact form at https://editmd.app/contact/ takes a topic (help, a problem, an improvement, or privacy and security), an email address and a message. Version details are optional. A useful report says what you expected, what happened, and the steps to reproduce it. Leave out passwords, API keys and private writing. Messages go to the people who build editmd. Your email address, message and any version details are processed by our mail service and support team to respond to your request, and are not displayed publicly or used for marketing. --- --- title: "Why we made it" description: "Why Brencel built editmd, what it is good at, why it is free, and how to help make it better." canonical: https://editmd.app/about/ markdown: https://editmd.app/about.md status: pre-release, waiting list open generated: editmd-website --- # We built editmd because we needed it. A Markdown editor for people who write, with quick help from AI only when they ask for it. It started as an internal tool at Brencel. Now it is free for anyone who finds it useful. ## Why we made it Most of our writing is for people, not machines: notes, plans, reviews, documentation. We wanted an editor built around that, where the text comes first and the file stays ours, and where we can ask for a second opinion when a paragraph is not landing. Not an assistant that writes for us. A tool that helps us write. ## What it is good at Reviewing files before they go out. Getting a paragraph clearer without losing the meaning. Checking that headings, lists and tables are formatted the way the next reader expects. Keeping everything as plain Markdown so it opens in any text editor. ## Why it is free We use editmd every day, so the work of keeping it good is already done for our own sake. Charging for it would mean accounts, billing and lock-in, which is exactly what we did not want in a writing tool. If you connect an AI provider, you pay them, not us. ## From internal tool to anyone The first versions lived on our own Macs. When people outside the company asked for it, we decided to release it properly. That work is in progress: a release that passes its checks, release notes, and a place to ask for help. ## Help us make it better If something breaks, feels wrong, or is missing, tell us through https://editmd.app/contact/. A short note with what you expected and what happened is enough. Missing features are equally welcome. Brencel AS: https://brencel.no. GitHub: https://github.com/brencel-dev/editmd (private until launch). Discord: https://discord.gg/DdsyeqhRJG --- --- title: "Security" description: "How editmd and this website handle your files, your text and your data." canonical: https://editmd.app/security/ markdown: https://editmd.app/security.md status: pre-release, waiting list open generated: editmd-website --- # Security and data handling ## The app - Your Markdown files, editor preferences and appearance choice stay on your Mac. - AI is off until you turn it on in Preferences and connect a provider. When you use it, only the text you review is sent to the provider you chose; their account terms, charges and retention apply. - Session recovery helps after an interruption but does not replace saving or backups. ## This website - No advertising, no marketing analytics, no session replay. Hosting receives ordinary page requests. - Your appearance choice is remembered in this browser only. - Resend processes contact-form message bodies, reply addresses and version details in the United States. Waiting-list confirmation emails and confirmed addresses with consent evidence are also processed there. Transfers use the safeguards described on the privacy page. Report a security concern through https://editmd.app/contact/ with the topic "Ask about privacy or security". --- --- title: "Brand guidelines" description: "How to write the editmd name, use the mark, and refer to the app when you link, review or sponsor it." canonical: https://editmd.app/brand/ markdown: https://editmd.app/brand.md status: pre-release, waiting list open generated: editmd-website --- # Brand guidelines editmd is free. To keep it that way we are exploring affiliate links and sponsorships. These guidelines say how the name and mark may be used by anyone who writes about the app, links to it, or works with us. ## The name - editmd, always lowercase, one word. Not EditMD, Editmd, edit.md or edit md. - Describe it as "a free Markdown editor for Mac". The full line we use: "Create, edit, preview and review Markdown on your Mac. A free, local editor with optional AI assistance and flexible exports." - Made by Brencel AS. Write "editmd by Brencel" when the maker matters. - The editmd name and wordmark are trademarks of Brencel AS; the artwork on this site is © Brencel AS. ## Wordmark and mark - The wordmark is the name in Schibsted Grotesk Bold with the prompt glyph >_ in the accent colour before it. It is the only mark in use today; a standalone logo mark is being designed and will be published on this page when it is finalised. ## Colour and type - Accent: amber, oklch(0.8 0.147 79). Dark ground #080807 with paper text #f4f3ed. Light ground #fbfaf7 with ink text #17160f. Terminal green #33ff77 is a website appearance only; the app offers System, Light and Dark. - Type: Archivo for headings and text, Source Code Pro for code and labels, Schibsted Grotesk Bold for the wordmark, Courier Prime for the Terminal appearance. ## Using the mark - Do: use the wordmark unchanged, keep clear space equal to the height of the letter e, show it at 20 px or 6 mm or larger, link it to https://editmd.app. - Do not: recolour, outline, rotate, stretch or add effects; combine it with another logo; imply endorsement or partnership not agreed in writing; use it on a page that offers a download of editmd. ## Partners, affiliates and sponsors - Anything sponsored or affiliate-linked on editmd.app is labelled where it appears. - Sponsorships never change what the app does, what it sends, or which AI providers it supports. - The handbook and Markdown School carry no sponsored content. - The website runs no advertising network, no analytics and no tracking, and that does not change with a sponsor. Questions and permission requests: https://editmd.app/contact/.