Back to Documentation

Markdown Editor

Sutram's Markdown Editor lets you create and edit formatted text documents directly in the browser. It is a visual (WYSIWYG) editor where you see the final result as you edit, without needing to know Markdown syntax.

Creating a Markdown File

  1. Navigate to a folder in your project
  2. Click the ⋮ menu (three dots) in the top-right corner
  3. Select Add Markdown File
  4. Enter a name for the file
  5. The editor opens automatically with the title already inserted

Note: This option only appears inside folders (not at the project root) and requires a PRO plan or higher.

Editing an Existing File

  1. Click any .md file in the content list
  2. In the viewer, click the Edit button or the expand icon
  3. The editor opens with the file's current content

Important: To edit, you need to "check out" the file. This reserves the file for you, preventing other people from editing it at the same time.

Toolbar

The toolbar sits at the top of the editor. Each button applies a specific formatting.

Text Formatting

Button Name Behavior
B Bold Toggle - Click once to turn on, click again to turn off. Works with selected text or at the current cursor position. Shortcut: Ctrl+B (Windows) or Cmd+B (Mac)
I Italic Toggle - Works the same as bold. Shortcut: Ctrl+I or Cmd+I
S Strikethrough Toggle - Adds or removes a line through the selected text
<> Inline code Toggle - Formats the text as code (monospace font)

Headings

Button Name Behavior
H1 Heading 1 Toggle - Turns the current line into a large heading. If it is already H1, it reverts to a normal paragraph
H2 Heading 2 Toggle - Medium heading. If it is already H2, it reverts to a paragraph
H3 Heading 3 Toggle - Small heading. If it is already H3, it reverts to a paragraph

Tip: Place the cursor on any line and click H1, H2, or H3 to turn it into a heading.

Lists

Button Name Behavior
• Bulleted list Toggle - Creates a list with bullet points. Click again to revert to a paragraph
1. Numbered list Toggle - Creates an automatically numbered list

Creating sub-items: Inside a list, press Tab to create a sub-item (indent) or Shift+Tab to go back to the previous level.

Special Blocks

Button Name Behavior
" Quote Toggle - Creates a quote block (with a side bar). Useful for highlighting important passages
[ ] Code block Insertion - Creates an area for multi-line code

Tables

The table button (grid icon) opens a dropdown menu with all the options for creating and editing tables.

Option Behavior
Insert table Creates a 3x3 table at the cursor position
Add row above Inserts a new row above the current row
Add row below Inserts a new row below the current row
Add column to the left Inserts a new column to the left of the current column
Add column to the right Inserts a new column to the right of the current column
Delete row Removes the row where the cursor is
Delete column Removes the column where the cursor is
Delete table Removes the entire table

How to use tables:

  1. Create a table: Click the table button and select "Insert table". A 3x3 table will be created.

  2. Edit cells: Click any cell and type the content. Use Tab to move to the next cell or Shift+Tab to go back.

  3. Add rows/columns: Place the cursor in the reference cell, click the table button, and choose where to add (above, below, left, or right).

  4. Delete rows/columns: Place the cursor in the row or column you want to remove, click the table button, and choose "Delete row" or "Delete column".

  5. Delete an entire table: With the cursor in any cell of the table, click the table button and choose "Delete table".

Tip: The first row of the table is automatically formatted as a header (bold text with a highlighted background).

Links and Media

Button Name Behavior
🔗 (globe) External link Insertion - Opens a box to enter a URL. Creates a clickable link in the text
🔗 (chain) Project web link Selection - Shows the web links saved in the current folder for you to choose from
🖼️ (landscape) Image from URL Insertion - Opens a box to paste the address of an image from the internet
🖼️ (folder) Project image Selection - Shows the images in the current folder for you to choose and insert
📹 Project video Selection - Shows the video links in the current folder (YouTube, Vimeo, etc.)
🎵 Project audio Selection - Shows the audio links in the current folder (SoundCloud, Spotify, etc.)

How to Insert Links and Media

External link (any URL):

  1. Select the text that will be the link (optional)
  2. Click the globe button
  3. Type or paste the URL
  4. If you did not select text, type the link text

Project web link:

  1. Click the chain button
  2. A list shows the links saved in the folder
  3. Click the desired link to insert it

Project image:

  1. Click the folder-with-image button
  2. A list shows the images in the folder
  3. Click the desired image to insert it

Video or audio:

  1. Click the video or audio button
  2. Choose from the folder's list of media
  3. The link is inserted into the document

How to Delete Links and Media

To remove an inserted link, image, video, or audio:

  1. Place the cursor at the end of the link/media
  2. Press Backspace (or Delete) to erase character by character
  3. Or select the entire element (click and drag) and press Delete or Backspace

Tip: For text links, you can also select the link text and simply type something new to replace it.

Automatic Saving

The editor saves your work automatically every 60 seconds, as long as there are unsaved changes. You will briefly see a "Saving..." indicator when this happens.

Important: Automatic saving saves a draft. For other people to see your changes, you need to publish the file.

Publishing Changes

When you finish editing:

  1. Click the Finish Editing button (top-right corner)
  2. The file is published and released for other users
  3. Your changes become visible to the whole team

Note: If you leave the editor without finishing, your changes are saved as a draft, but the file remains reserved for you (check-out).

AI Assistant for Sections

The editor includes an artificial intelligence assistant that can help improve, summarize, or expand sections of your document. AI actions are available on any heading (H1, H2, H3, etc.).

How to Access

There are two ways to access the AI actions:

  1. Right-click a heading: A context menu appears with the available options
  2. Button on the heading: When you hover over a heading, a ⋮ button appears to the right. Click it to see the options

Available Actions

Action Description
Summarize Section Condenses the section's content while keeping the main points
Expand Section Adds more detail and depth to the existing content
Improve Section Improves the writing quality (clarity, flow, grammar)
Generate Executive Summary Creates a high-level summary of the document (available only on H1 headings)
Delete Section Removes the section and all its content (does not use AI)

Usage Flow

  1. Choose an action: Right-click the heading or use the ⋮ button and select the desired action
  2. Wait for processing: A loading indicator appears while the AI processes. You can cancel at any time
  3. Review the result: A comparison panel shows the original text (on the left) and the AI's suggestion (on the right), side by side
  4. Decide: Click Apply to accept the suggestion or Cancel to discard it

No changes are made without your approval. You always preview the result before applying.

Executive Summary (TLDR)

The "Generate Executive Summary" action works differently from the others:

  • Available only on H1 headings
  • Instead of replacing the content, it inserts a new section right below the H1
  • The section title is localized in the document's language (e.g., "Executive Summary (TLDR)" in English)

Delete Section

Deleting a section does not use AI and works as follows:

  1. A confirmation window shows the content that will be removed
  2. Click Delete Section to confirm or Cancel to keep it

Warning: Deletion removes the entire section (the heading and all content up to the next heading). This action cannot be undone directly — use the Undo button (previous version) to restore the document.

Undo Button (Previous Version)

The Undo button appears when a previous version of the file exists. Clicking it:

  1. Restores the complete previous version of the file
  2. The current version becomes the new backup

Warning: This undo restores the entire file to the previous version, not just the last typing. To undo recent typing, use Ctrl+Z (Windows) or Cmd+Z (Mac).

Downloading the File

In the content list, click the file's ⋮ menu on the markdown file to see the options:

  • Download: Downloads only the .md file
  • Download with images: Downloads a ZIP file containing the markdown and all the Sutram images in the document. The image links are converted to relative paths, making the package portable.

Note: The "Download with images" option only appears for published files. If there are no Sutram images in the document, a message will inform you that you should use the normal download option.

Keyboard Shortcuts

Shortcut Action
Ctrl/Cmd + Z Undo last typing
Ctrl/Cmd + Shift + Z Redo
Ctrl/Cmd + B Bold
Ctrl/Cmd + I Italic
Enter New paragraph
Shift + Enter Line break (same paragraph)
Tab Indent list item
Shift + Tab Remove list item indent

Comments Mode

The markdown editor includes a built-in comments mode that lets you view, manage, and reposition comment markers while editing the document.

Two Operating Modes

The editor switches between two modes:

Mode Description
Editing (default) Normal Milkdown WYSIWYG editor, with no visible markers
Comments Rendered preview with a comments overlay and side panel

Accessing Comments Mode

  1. In the editor, click the Comments button in the header (next to the "Send" button)
  2. The badge shows the number of existing comments (e.g., "8")
  3. The editor switches to viewing mode with the markers visible
  4. To return to editing mode, click the Comments button again

Restriction: Comments mode is not available on small mobile devices (viewport < 768px). It works on tablets (iPad, Android) and desktops. A tooltip on the disabled button explains: "Use a desktop computer to manage comments".

Comments Mode Layout

┌─────────────────────────────────────────────────────────────────┐
│  ← Back            [💬 Comments 8]      [Send]        │ Header    │
├─────────────────────────────────────┬───────────────────────────┤
│                                     │ 💬 3 comments             │
│   Markdown Preview                  │ ─────────────────────────│
│   (read-only)                       │ ◉ All ○ Open ○ Resolved   │
│                                     │ ─────────────────────────│
│        📍 Marker 1                  │ [1] João · 2h ago         │
│                                     │     Check this section    │
│        📍 Marker 2                  │     "text excerpt..."     │
│                                     │     [Go to]               │
│                                     │ ─────────────────────────│
│                                     │ [2] Maria · 1d ago    ✅  │
│                                     │     Fixed                 │
└─────────────────────────────────────┴───────────────────────────┘

Comments Panel Features

The right-hand side panel offers:

Feature Description
Filters All / Open / Resolved
Comments list All the document's comments with author, date, and a preview of the selected text
Go to Scrolls the view to the corresponding marker
Open thread Click the comment to see replies and interact

Resolving Comments

In comments mode, you can resolve discussions directly:

  1. Click a comment in the panel or the marker in the document
  2. The thread modal opens showing the original comment and replies
  3. Click "Mark as resolved" to indicate that the issue has been addressed
  4. The marker changes from purple (open) to green (resolved)
  5. The comment can be filtered under the "Resolved" tab

To reopen a resolved comment, open the thread and click "Reopen".

Difference Between Viewer and Editor

Aspect Viewer (Preview Modal) Editor (Comments Mode)
Create comments ✅ Select text to comment ❌ Not available
View comments ✅ Markers visible ✅ Markers visible
Resolve/Reply ✅ Via thread modal ✅ Via thread modal
Edit content ❌ Read-only ✅ In Editing mode

Recommended flow:

  1. Viewer: Use it to create new comments (select text)
  2. Editor - Editing Mode: Use it to edit the markdown content
  3. Editor - Comments Mode: Use it to review and resolve existing comments

Useful Tips

  1. Organize with headings: Use H1 for the main title, H2 for sections, and H3 for subsections. This makes reading easier.

  2. Save regularly: Although there is automatic saving, you can click "Finish Editing" at any time to publish.

  3. Exit warning: If you try to leave the page with unsaved changes, the browser will show a warning.

  4. Project images: Prefer using images already uploaded to the project. They are stored securely and can be downloaded together with the document.

  5. Media links: For videos and audio, first add the link to the folder using "Add video link" or "Add audio link", then insert it into the document.

  6. Resolve before publishing: Before finishing your edit, check in Comments mode whether there are open discussions that need to be resolved or answered.

Back to Documentation