Working with Markup Languages in VB Studio

VB Studio's markdown parser/renderer provides an easy-to-use viewing and editing experience with markup, and uses markdown specifications that other sites, such as GitHub, support. The server generates a JSON model from markup and then the client side processes it, rendering the HTML in the VB Studio user interface. This results in markup rendering that's similar to and consistent with what other open-source software companies support. You can use markup in the Wiki, SCM, MR, Announcement, and Environment Detail pages.

You can read more about using these markup languages with VB Studio:

As you work with these markup languages in VB Studio, here are some helpful features to keep in mind:

The Table of Contents is always available on wiki pages (and in the Git page's File view). When the icon is clicked, the contents are displayed. No special coding is needed for this.

Description of the illustration renderer-improvements-toc.png
An Edit button is available on the SCM README.md page to facilitate quick direct edits.

Description of the illustration renderer-improvements-readme-edit-button.png
A markup toolbar provides common formatting actions so that you don't have to remember or search for the markup language syntax you need. The toolbar is available in the Wiki, SCM, and MR pages.
After making an edit, you can go to the Preview tab to look at it. Your edit is displayed immediately. You don't have to scroll down through the page you were editing to find your change. In the Preview tab, it should auto scroll to the line or section being edited.
The header bar is sticky, so when you go from the Edit tab to the Preview tab to look at your changes, the header bar stays at the top of the page as well.

Description of the illustration renderer-improvements-sticky-header.png
Headers have link accessors, which are shown when you hover over the header.

Description of the illustration renderer-improvements-link-accessor-hover.png

When you click the header, the browser page's URL is updated. You can copy the URL and embed it in your pages, to provide a direct link to the header.

Description of the illustration renderer-improvements-link-accessor-click.png

Code in markup is shown with syntax coloring when the code language is specified in code blocks.

Description of renderer-improvements-code-colors.png follows
Description of the illustration renderer-improvements-code-colors.png

For example, for this Java code:

```java
public class Main {
  public static void main(String[] args) {
    if (20 > 18) {
      System.out.println("20 is greater than 18"); // obviously
    }
  }
}
```

The Java syntax highlighting in Confluence markup would be:

{code:language=java}
public class Main {
  public static void main(String[] args) {
    if (20 > 18) {
      System.out.println("20 is greater than 18"); // obviously
    }
  }
}
{code}

In Textile markup it would be:

bc[java].
public class Main {
  public static void main(String[] args) {
    if (20 > 18) {
      System.out.println("20 is greater than 18"); // obviously
    }
  }
}

Empty lists in markdown are shown as empty lists.
Line breaks for Markdown are standardized. The backslash (\) at the end of a line forces a line break. To create a paragraph, you don't have to enter the entire paragraph on one long line. Instead, enter it using many lines and then just toggle line wrap on or off.
Line breaks in existing text blocks may not be displayed properly. This is a known issue.
The use of images in Wiki comments is supported.

Textile Syntax Reference

Textile is a lightweight markup language that uses a text formatting syntax to convert plain text into structured HTML markup. The syntax, a shorthand version of HTML, is designed to be easy to read and write.

Phrase Modifiers

Markup	Output
strong	strong
__italic__	italic
bold	bold
??citation??	citation
-deleted text-
+inserted text+
^superscript^	superscript
~subscript~	subscript
%span%	span
@code@	`code`

Block Modifiers

Markup	Output
hn.	Heading
bq.	Block quote
fnn.	Footnote
p.	Paragraph (optional)
bc.	Block code
pre.	Pre-formatted
#	Numeric list
*	Bulleted list

Links

"title":http://www.example.com

!images/logo.png!:http://www.example.com

Images

!images/logo.png!

Punctuation

Markup	Output
"quotes"	“quotes”
'quotes'	‘quotes’
it's	it’s
em -- dash	— symbol (emdash)
en - dash	– symbol (endash)
2 x 4	2 × 4
foo(tm)	foo™
foo(r)	foo®

Lists

Bulleted Lists
```
* one
** one.one 
** one.two 
* two
```
Numeric Lists
```
# one
## one.one
## one.two
# two
```

Tables

|_. heading 1|_. heading 2|_. heading 3|
|col A1|col A2|col A3|
|col B1|col B2|col B3|

Alignment and Padding

Markup	Output	Example
<	left text alignment	p<.
>	right text alignment	p>.
<>	justify text	p<>.
=	center text	p=.
(	pad left	p(.
)	pad right	p).
()	pad left and right

Attributes

Markup	Example
(class)	h1(foo).
(#id)	h1(foo).
{style}	h1{color:red}.
[language]	h1[en].

For example:

h1(main-heading){color: red}. header text

Footnotes

reference[1]
fn1. footnote text

Extended Blocks

bc..
bq..
pre..

Acronyms

CSS (Cascading Style Sheets) generates CSS.

Generated Content

Markup	Description	Example
{toc}	Generates a table of contents.	{toc} or {toc:style=disc\|maxLevel=3}
{glossary}	Generates a glossary based on acronyms in the document.	{glossary} or {glossary:style=disc}

Confluence Syntax Reference

Confluence pages are where you capture all your important (and unimportant) information, starting with a blank page and adding rich text, tasks, images, links, and more.

Phrase Modifiers

Markup	Output
_emphasis_	emphasis
strong	strong
??citation??	citation
-deleted text-
+inserted text+
^superscript^	superscript
~subscript~	subscript
{{monospace}}	`monospace`

Block Modifiers

Markup	Description
hn.	Heading (where n is some digit, for example h1)
bq.	Block quote (single paragraph)
{quote}	Block quote (multiple paragraphs)
{code}	Block code
{note:title=Note}	A simple note
{warning:title=Caution}	A warning note
{info:title=Useful Information}	Informational note
{tip:title=Tip}	A help tip
{noformat}	Pre-formatted block
#	Numeric list
*	Bulleted list

Links

[Title|http://www.example.com]
[Title|http://www.example.com|tip]

Anchors

Markup	Description
{anchor:anchorname}	Creates anchor 'anchorname'
[Title\|#anchorname]	Links to anchor 'anchorname'

Tables

||heading 1||heading 2||heading 3||
|col A1|col A2|col A3|
|col B1|col B2|col B3|

Text Breaks

Markup	Description
(empty line)	Produces a new paragraph
----	horizontal rule
---	— symbol (emdash)
--	– symbol (endash)

Markdown Syntax Reference

Markdown uses fewer elements than other kinds of wiki markup. For elements not included in the syntax (such as underline, superscript, subscript, tables, notes), you can use actual HTML tags.

If you use special characters, such as & and <, Markdown automatically escapes them and produces the correct HTML code.

Phrase Modifiers

Markup	Output
italic or _italic_	italic (em element)
bold or __bold__	bold (strong element)
~~deleted text~~
`code`	`code`

Tables

| Left alignment | Centre alignment | Right alignment |
| :---- | :----: | ----: |
| col A1 | col A2 | col A3 |
| col B1 | col B2 | col B3 |

The rendered output looks like this: Table rendered from Markdown markup

Block Modifiers

Markup	Output
#, ##, ###, and so on	Heading (levels 1 through 6)
=== (equals signs) under title	Level 1 heading
--- (hyphens) under title	Level 2 heading
>	Block quote (before the quoted line or lines; long lines will wrap)
``` before and after code block, or indented 4 spaces or a tab	Block code

Lists

Markup	Output
1. (any digit)	Numeric list
*, -, +	Bulleted list

Blank lines between list items cause the list item text to be surrounded with paragraph elements.

To nest list items, indent the nested items two spaces.

To place paragraphs within list items, put a blank line above, and indent the text 4 spaces or one tab.

Links

Inline links consist of bracketed link text immediately followed by text in parenthesis. For example:

[Link text](http://www.example.com)
[Link text with title](http://www.example.com "Example.com's home page")

Reference links consist of bracketed link text followed by a reference (a number or other text in brackets). The reference is defined elsewhere in the document. For example:

[Link text][1]
[Link text][any text]
...
[1]: http://www.example.com
[any text]: http://www.example.com "Example.com's home page"

Images

Like links, images can be inline or reference. Inline images look like this (titles are allowed):

![link text](images/logo.png)
![link text](images/logo.png "My logo")

Reference images look like this:

![link text][id]
...
[id]: images/logo.png "My logo"

Use the Markup Toolbar

The markup toolbar provides commonly used formatting actions so that you don't have to remember or search for the right markup language syntax you need (whether Textile, Confluence, or Markdown). The toolbar also provides options to customize the content editor, and is available when editing wiki pages, merge request comments, and the Git repository's readme file.

Use the markup toolbar to:

Format text - add headings, and make text bold or italicized, for example
Add elements like links, images, lists, and tables
Add phrase or block modifiers when quoting text or adding code snippets
Customize the editor to improve efficiency during content creation. You can:
- Toggle line numbers on and off
- Change line wrapping
- Show (or hide) the content editor's minimap

When using the toolbar to add phrase or block modifiers, note that the and actions behave differently depending on what's selected.

For example:

If a single line or text phrase is selected when clicking the action, a phrase modifier is wrapped around the selected text. In Confluence markup, for example, you'd see:
{{something selected}}
If multiple lines are selected, a block modifier is wrapped around the selected text. The Confluence markup would be:
```
{code}
multiline selected
text
{code}
```

If no text is selected, a template is inserted:

{code:language=java}

Code goes here...
more code...

{code}

Here's an example of a template inserted for a table, in Confluence markup:

||heading 1||heading 2||heading 3||
|col A1|col A2|col A3|
|col B1|col B2|col B3|