RefractTrack Markdown Formatting: Difference between revisions

Revision as of 14:02, 28 August 2026

Formatting Text

Anywhere you can type a longer note — task descriptions, comments, bug details — RefractTrack supports a small set of simple formatting shortcuts, so you can add structure without needing a rich-text toolbar. There's also a help button right next to these fields in the app if you ever need a quick reminder.

Structuring a block of text

Type this	To get
A line starting with #	A heading
A line starting with ##	A smaller heading
A line starting with - or *	A bullet point
A line starting with 1.	A numbered list item
Two spaces of indent	Nests a list item under the one above
Triple backticks around a block, with a language name	A code block, with basic color highlighting for C# and JSON

Formatting a word or phrase

Type this	To get
bold	bold
italic	italic
++underline++	underlined text

Live preview

As you type in a description or comment box, a live preview shows exactly how the formatted text will look — no guessing, and no need to save first to check.

Task codes link themselves

You never need to manually link to another task. Just type its code — like FE-12 — anywhere in a description or comment, and RefractTrack automatically turns it into a clickable link, as long as it's a real task you have permission to see.

@@ Line 1: / Line 1: @@
-== Markdown Formatting ==
+== Formatting Text ==
-Free-text fields (task descriptions, comments, bug fields) support a small, purpose-built markdown subset — not a full CommonMark implementation. A help modal in the app documents this for end users; this page is the reference version.
+Anywhere you can type a longer note — task descriptions, comments, bug details — RefractTrack supports a small set of simple formatting shortcuts, so you can add structure without needing a rich-text toolbar. There's also a help button right next to these fields in the app if you ever need a quick reminder.
-=== Block-level syntax ===
+=== Structuring a block of text ===
 {| class="wikitable"
-! Syntax !! Result
+! Type this !! To get
 |-
-| <code><nowiki># Heading</nowiki></code> || Heading (rendered as <code><nowiki><h4></nowiki></code>)
+| A line starting with <nowiki>#</nowiki> || A heading
 |-
-| <code><nowiki>## Heading</nowiki></code> || Smaller heading (rendered as <code><nowiki><h5></nowiki></code>)
+| A line starting with <nowiki>##</nowiki> || A smaller heading
 |-
-| <code><nowiki>- item</nowiki></code> or <code><nowiki>* item</nowiki></code> || Bullet list item
+| A line starting with <nowiki>-</nowiki> or <nowiki>*</nowiki> || A bullet point
 |-
-| <code><nowiki>1. item</nowiki></code> || Numbered list item
+| A line starting with <nowiki>1.</nowiki> || A numbered list item
 |-
-| Two spaces of indent per level || Nests list items
+| Two spaces of indent || Nests a list item under the one above
 |-
-| <code><nowiki>```lang ... ```</nowiki></code> || Fenced code block, with optional single-line syntax highlighting for <code><nowiki>csharp</nowiki></code> and <code><nowiki>json</nowiki></code>
+| Triple backticks around a block, with a language name || A code block, with basic color highlighting for C# and JSON
-|-
-| (blank line not required) || Plain lines are joined with line breaks
 |}
-Mixing list markers at the same nesting depth (e.g. switching from <code><nowiki>-</nowiki></code> to <code><nowiki>1.</nowiki></code> mid-list) closes the old list and opens a new one of the new type at that depth, matching how most lightweight markdown parsers behave.
+=== Formatting a word or phrase ===
-=== Inline syntax ===
 {| class="wikitable"
-! Syntax !! Result
+! Type this !! To get
 |-
-| <code><nowiki>**bold**</nowiki></code> || '''bold'''
+| <nowiki>**bold**</nowiki> || '''bold'''
 |-
-| <code><nowiki>*italic*</nowiki></code> || ''italic''
+| <nowiki>*italic*</nowiki> || ''italic''
 |-
-| <code><nowiki>++underline++</nowiki></code> || underlined text
+| <nowiki>++underline++</nowiki> || underlined text
 |}
-=== Code blocks and syntax highlighting ===
+=== Live preview ===
-Fenced code blocks (<code><nowiki>```</nowiki></code>) support an optional language tag right after the opening fence (e.g. <code><nowiki>```csharp</nowiki></code>). Syntax highlighting is a hand-rolled, best-effort, line-by-line regex highlighter for <code><nowiki>csharp</nowiki></code> and <code><nowiki>json</nowiki></code> — not a real tokenizer, so it can occasionally be fooled by a keyword-looking substring inside an already-highlighted token. This is an accepted trade-off in exchange for no additional dependencies. Comments are only recognized within a single line; there is no multi-line comment tracking.
-=== Task-code auto-linking ===
+As you type in a description or comment box, a live preview shows exactly how the formatted text will look — no guessing, and no need to save first to check.
-Anywhere rendered markdown text contains something matching a task-code pattern (<code><nowiki>PREFIX-123</nowiki></code>, e.g. <code><nowiki>FE-12</nowiki></code>), RefractTrack automatically checks whether it resolves to a real task and, if so, turns it into a link to that task's detail page. If the viewer doesn't have permission to view tasks, or the code doesn't resolve to a real task, it's left as plain text.
+=== Task codes link themselves ===
-=== Live preview ===
-The task form and comment box include a live preview panel (<code><nowiki>js/markdown-preview.js</nowiki></code>) that renders the same markdown subset client-side as you type. This preview logic is kept in byte-for-byte lockstep with the server-side renderer — any change to the server-side markdown rendering rules should be mirrored here to avoid the preview drifting from what actually gets saved and displayed.
+You never need to manually link to another task. Just type its code — like ''FE-12'' — anywhere in a description or comment, and RefractTrack automatically turns it into a clickable link, as long as it's a real task you have permission to see.
 === Related pages ===
 * [[RefractTrack_Tasks|Tasks]]
-* [[RefractTrack_Comments_and_Activity_Log|Comments and Activity Log]]
+* [[RefractTrack_Comments_and_Activity_Log|Comments and Activity]]

Nerdofepic (talk | contribs)