@recaptime-dev's working patches + fork for Phorge, a community fork of Phabricator. (Upstream dev and stable branches are at upstream/main and upstream/stable respectively.)
hq.recaptime.dev/wiki/Phorge
phorge
phabricator
1@title Remarkup Reference
2@group userguide
3
4Explains how to make bold text; this makes your words louder so you can win
5arguments.
6
7= Overview =
8
9Phorge uses a lightweight markup language called "Remarkup", similar to
10other lightweight markup languages like Markdown and Wiki markup.
11
12This document describes how to format text using Remarkup.
13
14= Quick Reference =
15
16All the syntax is explained in more detail below, but this is a quick guide to
17formatting text in Remarkup.
18
19These are inline styles, and can be applied to most text:
20
21 **bold** //italic// `monospaced` ##monospaced## ~~deleted~~ __underlined__
22 !!highlighted!!
23 D123 T123 rX123 # Link to Objects
24 {D123} {T123} # Link to Objects (Full Name)
25 {F123} # Embed Images
26 {M123} # Embed Pholio Mock
27 @username # Mention a User
28 #project # Mention a Project
29 [[wiki page]] # Link to Phriction
30 [[wiki page | name]] # Named link to Phriction
31 https://xyz/ # Link to web
32 [[https://xyz/ | name]] # Named link to web
33 [name](https://xyz/) # Alternate Link
34
35These are block styles, and must be separated from surrounding text by
36empty lines:
37
38 = Large Header =
39
40 == Smaller Header ==
41
42 ## This is a Header As Well
43
44 Also a Large Header
45 ===================
46
47 Also a Smaller Header
48 ---------------------
49
50 > Quoted Text
51
52 Use `- ` or `* ` for bulleted lists, and `# ` for numbered lists.
53 Use ``` or indent two spaces for code.
54 Use %%% for a literal block.
55 Use | ... | ... for tables.
56
57= Basic Styling =
58
59Format **basic text styles** like this:
60
61 **bold text**
62 //italic text//
63 `monospaced text`
64 ##monospaced text##
65 ~~deleted text~~
66 __underlined text__
67 !!highlighted text!!
68
69Those produce **bold text**, //italic text//, `monospaced text`, ##monospaced
70text##, ~~deleted text~~, __underlined text__, and !!highlighted text!!
71respectively.
72
73= Layout =
74
75Make **headers** like this:
76
77 = Large Header =
78
79 == Smaller Header ==
80
81 ===== Very Small Header =====
82
83 Alternate Large Header
84 ======================
85
86 Alternate Smaller Header
87 ------------------------
88
89You can optionally omit the trailing `=` signs -- that is, these are the same:
90
91 == Smaller Header ==
92
93 == Smaller Header
94
95This produces headers like the ones in this document. Make sure you have an
96empty line before and after the header.
97
98Lists
99=====
100
101Make **lists** by beginning each item with a `-` or a `*`:
102
103 lang=text
104 - milk
105 - eggs
106 - bread
107
108 * duck
109 * duck
110 * goose
111
112This produces a list like this:
113
114 - milk
115 - eggs
116 - bread
117
118(Note that you need to put a space after the `-` or `*`.)
119
120You can make numbered lists with a `#` instead of `-` or `*`:
121
122 # Articuno
123 # Zapdos
124 # Moltres
125
126Numbered lists can also be started with `1.` or `1)`. If you use a number other
127than `1`, the list will start at that number instead. For example, this:
128
129```
130 200) OK
131 201) Created
132 202) Accepted
133```
134
135...produces this:
136
137 200) OK
138 201) Created
139 202) Accepted
140
141You can also nest lists:
142
143```- Body
144 - Head
145 - Arm
146 - Elbow
147 - Hand
148 # Thumb
149 # Index
150 # Middle
151 # Ring
152 # Pinkie
153 - Leg
154 - Knee
155 - Foot```
156
157...which produces:
158
159 - Body
160 - Head
161 - Arm
162 - Elbow
163 - Hand
164 # Thumb
165 # Index
166 # Middle
167 # Ring
168 # Pinkie
169 - Leg
170 - Knee
171 - Foot
172
173If you prefer, you can indent lists using multiple characters to show indent
174depth, like this:
175
176```- Tree
177-- Branch
178--- Twig```
179
180As expected, this produces:
181
182- Tree
183-- Branch
184--- Twig
185
186You can add checkboxes to items by prefacing them with `[ ]` or `[X]`, like
187this:
188
189```
190 - [X] Preheat oven to 450 degrees.
191 - [ ] Zest 35 lemons.
192```
193
194When rendered, this produces:
195
196 - [X] Preheat oven to 450 degrees.
197 - [ ] Zest 35 lemons.
198
199Code Blocks
200===========
201
202Make **code blocks** by indenting two spaces:
203
204` f(x, y);`
205
206You can also use three backticks to enclose the code block:
207
208 lang=text
209 ```
210 f(x, y);
211 g(f);
212 ```
213
214You can specify a language for syntax highlighting with `lang=xxx`:
215
216 lang=text
217 lang=html
218 <a href="#">...</a>
219
220When using fenced code blocks (triple backticks) you can append the
221language right after the backticks, like this: ##```html##
222
223This will highlight the block using a highlighter for that language, if one is
224available (in most cases, this means you need to configure Pygments):
225
226 lang=html
227 <a href="#">...</a>
228
229You can also use a `COUNTEREXAMPLE` header to show that a block of code is
230bad and shouldn't be copied:
231
232 lang=text
233 COUNTEREXAMPLE
234 function f() {
235 global $$variable_variable;
236 }
237
238This produces a block like this:
239
240 COUNTEREXAMPLE
241 function f() {
242 global $$variable_variable;
243 }
244
245You can use `lines=N` to limit the vertical size of a chunk of code, and
246`name=some_name.ext` to give it a name. For example, this:
247
248 lang=text
249 lang=html, name=example.html, lines=12, counterexample
250 ...
251
252...produces this:
253
254 lang=html, name=example.html, lines=12, counterexample
255 <p>Apple</p>
256 <p>Apricot</p>
257 <p>Avocado</p>
258 <p>Banana</p>
259 <p>Bilberry</p>
260 <p>Blackberry</p>
261 <p>Blackcurrant</p>
262 <p>Blueberry</p>
263 <p>Currant</p>
264 <p>Cherry</p>
265 <p>Cherimoya</p>
266 <p>Clementine</p>
267 <p>Date</p>
268 <p>Damson</p>
269 <p>Durian</p>
270 <p>Eggplant</p>
271 <p>Elderberry</p>
272 <p>Feijoa</p>
273 <p>Gooseberry</p>
274 <p>Grape</p>
275 <p>Grapefruit</p>
276 <p>Guava</p>
277 <p>Huckleberry</p>
278 <p>Jackfruit</p>
279 <p>Jambul</p>
280 <p>Kiwi fruit</p>
281 <p>Kumquat</p>
282 <p>Legume</p>
283 <p>Lemon</p>
284 <p>Lime</p>
285 <p>Lychee</p>
286 <p>Mandarine</p>
287 <p>Mango</p>
288 <p>Mangostine</p>
289 <p>Melon</p>
290
291
292You can use the `NOTE:`, `WARNING:` or `IMPORTANT:` elements to call attention
293to an important idea.
294
295For example, write this:
296
297```
298NOTE: Best practices in proton pack operation include not crossing the streams.
299```
300
301...to produce this:
302
303NOTE: Best practices in proton pack operation include not crossing the streams.
304
305Using `WARNING:` or `IMPORTANT:` at the beginning of the line changes the
306color of the callout:
307
308WARNING: Crossing the streams can result in total protonic reversal!
309
310IMPORTANT: Don't cross the streams!
311
312In addition, you can use `(NOTE)`, `(WARNING)`, or `(IMPORTANT)` to get the
313same effect but without `(NOTE)`, `(WARNING)`, or `(IMPORTANT)` appearing in
314the rendered result. For example, this callout uses `(NOTE)`:
315
316(NOTE) Dr. Egon Spengler is the best resource for additional proton pack
317 questions.
318
319
320Dividers
321========
322
323You can divide sections by putting three or more dashes on a line by
324themselves. This creates a divider or horizontal rule similar to an `<hr />`
325tag, like this one:
326
327---
328
329The dashes need to appear on their own line and be separated from other
330content. For example, like this:
331
332```
333This section will be visually separated.
334
335---
336
337On an entirely different topic, ...
338```
339
340
341= Linking URIs =
342
343URIs are automatically linked: https://phorge.it/
344
345If you have a URI with problematic characters in it, like
346"`https://example.com/,`", you can surround it with angle brackets:
347
348 <https://example.com/,>
349
350This will force the parser to consume the whole URI: <https://example.com/,>
351
352You can also use create named links, where you choose the displayed text. These
353work within Phorge or on the internet at large:
354
355 [[/herald/transcript/ | Herald Transcripts]]
356 [[https://boring.example.com/ | exciting example]]
357
358Markdown-style links are also supported:
359
360 [Example](https://www.example.com)
361
362= Linking to Objects =
363
364You can link to Phorge objects, such as Differential revisions, Diffusion
365commits and Maniphest tasks, by mentioning the name of an object:
366
367 D123 # Link to Differential revision D123
368 rX123 # Link to SVN commit 123 from the "X" repository
369 rXaf3192cd5 # Link to Git commit "af3192cd5..." from the "X" repository.
370 # You must specify at least 7 characters of the hash.
371 T123 # Link to Maniphest task T123
372
373You can also link directly to a comment in Maniphest and Differential (these
374can be found on the date stamp of any transaction/comment):
375
376 T123#412 # Link to comment id #412 of task T123
377
378See the Phorge configuration setting `remarkup.ignored-object-names` to
379modify this behavior.
380
381= Embedding Objects
382
383You can also generate full-name references to some objects by using braces:
384
385 {D123} # Link to Differential revision D123 with the full name
386 {T123} # Link to Maniphest task T123 with the full name
387
388These references will also show when an object changes state (for instance, a
389task or revision is closed). Some types of objects support rich embedding.
390
391== Linking to Project Tags
392
393Projects can be linked to with the use of a hashtag `#`. This works by default
394using the name of the Project (lowercase, underscored). Additionally you
395can set multiple additional hashtags by editing the Project details.
396
397 #qa, #quality_assurance
398
399== Embedding Mocks (Pholio)
400
401You can embed a Pholio mock by using braces to refer to it:
402
403 {M123}
404
405By default the first four images from the mock set are displayed. This behavior
406can be overridden with the **image** option. With the **image** option you can
407provide one or more image IDs to display.
408
409You can set the image (or images) to display like this:
410
411 {M123, image=12345}
412 {M123, image=12345 & 6789}
413
414== Embedding Pastes
415
416You can embed a Paste using braces:
417
418 {P123}
419
420You can adjust the embed height with the `lines` option:
421
422 {P123, lines=15}
423
424You can highlight specific lines with the `highlight` option:
425
426 {P123, highlight=15}
427 {P123, highlight="23-25, 31"}
428
429== Embedding Images
430
431You can embed an image or other file by using braces to refer to it:
432
433 {F123}
434
435In most interfaces, you can drag-and-drop an image from your computer into the
436text area to upload and reference it.
437
438Some browsers (e.g. Chrome) support uploading an image data just by pasting them
439from clipboard into the text area.
440
441You can set file display options like this:
442
443 {F123, layout=left, float, size=full, alt="a duckling"}
444
445Valid options for all files are:
446
447 - **layout** left (default), center, right, inline, link (render a link
448 instead of a thumbnail for images)
449 - **name** with `layout=link` or for non-images, use this name for the link
450 text
451 - **alt** Provide alternate text for assistive technologies.
452
453Image files support these options:
454
455 - **float** If layout is set to left or right, the image will be floated so
456 text wraps around it.
457 - **size** thumb (default), full
458 - **width** Scale image to a specific width.
459 - **height** Scale image to a specific height.
460
461Audio and video files support these options:
462
463 - **media**: Specify the media type as `audio` or `video`. This allows you
464 to disambiguate how file format which may contain either audio or video
465 should be rendered.
466 - **loop**: Loop this media.
467 - **autoplay**: Automatically begin playing this media.
468
469== Embedding Countdowns
470
471You can embed a countdown by using braces:
472
473 {C123}
474
475= Quoting Text =
476
477To quote text, preface it with an `>`:
478
479 > This is quoted text.
480
481This appears like this:
482
483> This is quoted text.
484
485= Embedding Media =
486
487If you set a configuration flag, you can embed media directly in text:
488
489 - **remarkup.enable-embedded-youtube**: allows you to paste in YouTube videos
490 and have them render inline.
491
492This option is disabled by default because it has security and/or
493silliness implications. Carefully read the description before enabling it.
494
495= Image Macros =
496
497You can upload image macros by navigating to {nav icon=home, name=Home >
498More Applications > Macro }. Macros will replace text
499strings with the image you specify. For instance, you could upload an image of a
500dancing banana to create a macro named "peanutbutterjellytime", and then any
501time you type that string on a separate line it will be replaced with the image
502of a dancing banana.
503
504= Memes =
505
506You can also use image macros in the context of memes. For example, if you
507have an image macro named `grumpy`, you can create a meme by doing the
508following:
509
510 {meme, src = grumpy, above = toptextgoeshere, below = bottomtextgoeshere}
511
512By default, the font used to create the text for the meme is `tuffy.ttf`. For
513the more authentic feel of `impact.ttf`, you simply have to place the Impact
514TrueType font in the Phorge subfolder `/resources/font/`. If Remarkup
515detects the presence of `impact.ttf`, it will automatically use it.
516
517= Mentioning Users =
518
519In Differential and Maniphest, you can mention another user by writing:
520
521 @username
522
523When you submit your comment, this will add them as a CC on the revision or task
524if they aren't already CC'd.
525
526Icons
527=====
528
529You can add icons to comments using the `{icon ...}` syntax. For example:
530
531 {icon camera}
532
533This renders: {icon camera}
534
535You can select a color for icons:
536
537 {icon camera color=blue}
538
539This renders: {icon camera color=blue}
540
541For a list of available icons and colors, check the UIExamples application.
542(The icons are sourced from
543[[ https://fontawesome.com/v4.7.0/icons/ | FontAwesome ]], so you can also
544browse the collection there.)
545
546You can add `spin` to make the icon spin:
547
548 {icon cog spin}
549
550This renders: {icon cog spin}
551
552
553= Phriction Documents =
554
555You can link to Phriction documents with a name or path:
556
557 Make sure you sign and date your [[legal/Letter of Marque and Reprisal]]!
558
559By default, the link will render with the document title as the link name.
560With a pipe (`|`), you can retitle the link. Use this to mislead your
561opponents:
562
563 Check out these [[legal/boring_documents/ | exciting legal documents]]!
564
565Links to pages which do not exist are shown in red. Links to pages which exist
566but which the viewer does not have permission to see are shown with a lock
567icon, and the link will not disclose the page title.
568
569If you begin a link path with `./` or `../`, the remainder of the path will be
570evaluated relative to the current wiki page. For example, if you are writing
571content for the document `fruit/` a link to `[[./guava]]` is the same as a link
572to `[[fruit/guava]]` from elsewhere.
573
574Relative links may use `../` to transverse up the document tree. From the
575`produce/vegetables/` page, you can use `[[../fruit/guava]]` to link to the
576`produce/fruit/guava` page.
577
578Relative links do not work when used outside of wiki pages. For example,
579you can't use a relative link in a comment on a task, because there is no
580reasonable place for the link to start resolving from.
581
582When documents are moved, relative links are not automatically updated: they
583are preserved as currently written. After moving a document, you may need to
584review and adjust any relative links it contains.
585
586
587= Literal Blocks =
588
589To place text in a literal block use `%%%`:
590
591 %%%Text that won't be processed by remarkup
592 [[https://www.example.com | example]]
593 %%%
594
595Remarkup will not process the text inside of literal blocks (other than to
596escape HTML and preserve line breaks).
597
598= Tables =
599
600Remarkup supports simple table syntax. For example, this:
601
602```
603| Fruit | Color | Price | Peel?
604| ----- | ----- | ----- | -----
605| Apple | red | `$0.93` | no
606| Banana | yellow | `$0.19` | **YES**
607```
608
609...produces this:
610
611| Fruit | Color | Price | Peel?
612| ----- | ----- | ----- | -----
613| Apple | red | `$0.93` | no
614| Banana | yellow | `$0.19` | **YES**
615
616Remarkup also supports a simplified HTML table syntax. For example, this:
617
618```
619<table>
620 <tr>
621 <th>Fruit</th>
622 <th>Color</th>
623 <th>Price</th>
624 <th>Peel?</th>
625 </tr>
626 <tr>
627 <td>Apple</td>
628 <td>red</td>
629 <td>`$0.93`</td>
630 <td>no</td>
631 </tr>
632 <tr>
633 <td>Banana</td>
634 <td>yellow</td>
635 <td>`$0.19`</td>
636 <td>**YES**</td>
637 </tr>
638</table>
639```
640
641...produces this:
642
643<table>
644 <tr>
645 <th>Fruit</th>
646 <th>Color</th>
647 <th>Price</th>
648 <th>Peel?</th>
649 </tr>
650 <tr>
651 <td>Apple</td>
652 <td>red</td>
653 <td>`$0.93`</td>
654 <td>no</td>
655 </tr>
656 <tr>
657 <td>Banana</td>
658 <td>yellow</td>
659 <td>`$0.19`</td>
660 <td>**YES**</td>
661 </tr>
662</table>
663
664Some general notes about this syntax:
665
666 - your tags must all be properly balanced;
667 - your tags must NOT include attributes (`<td>` is OK, `<td style="...">` is
668 not);
669 - you can use other Remarkup rules (like **bold**, //italics//, etc.) inside
670 table cells.
671
672Navigation Sequences
673====================
674
675You can use `{nav ...}` to render a stylized navigation sequence when helping
676someone to locate something. This can be useful when writing documentation.
677For example, you could give someone directions to purchase lemons:
678
679{nav icon=home, name=Home >
680Grocery Store >
681Produce Section >
682icon=lemon-o, name=Lemons}
683
684To render this example, use this markup:
685
686```
687{nav icon=home, name=Home >
688Grocery Store >
689Produce Section >
690icon=lemon-o, name=Lemons}
691```
692
693In general:
694
695 - Separate sections with `>`.
696 - Each section can just have a name to add an element to the navigation
697 sequence, or a list of key-value pairs.
698 - Supported keys are `icon`, `name`, `type` and `href`.
699 - The `type` option can be set to `instructions` to indicate that an element
700 is asking the user to make a choice or follow specific instructions.
701
702Keystrokes
703==========
704
705You can use `{key ...}` to render a stylized keystroke. For example, this:
706
707```
708Press {key M} to view the starmap.
709```
710
711...renders this:
712
713> Press {key M} to view the starmap.
714
715You can also render sequences with modifier keys. This:
716
717```
718Use {key command option shift 3} to take a screenshot.
719Press {key down down-right right LP} to activate the hadoken technique.
720```
721
722...renders this:
723
724> Use {key command option shift 3} to take a screenshot.
725> Press {key down down-right right LP} to activate the hadoken technique.
726
727
728Anchors
729========
730
731You can use `{anchor #xyz}` to create a document anchor and later link to
732it directly with `#xyz` in the URI.
733
734Headers also automatically create named anchors.
735
736If you navigate to `#xyz` in your browser location bar, the page will scroll
737to the first anchor with "xyz" as a prefix of the anchor name.
738
739
740= Fullscreen Mode =
741
742Remarkup editors provide a fullscreen composition mode. This can make it easier
743to edit large blocks of text, or improve focus by removing distractions. You can
744exit **Fullscreen** mode by clicking the button again or by pressing escape.
745
746See Also
747========
748* @{article:Remarkup Reference: Cowsay}