Markdown usage #

This page shows the output of all the supported markdown syntax usage. The site uses CommonMark.

Markdown source files #

• Standard extension is .md
• 80 character hard wrap width for markdown code
• Embedded HTML can be wider
• Use 2 space indent for HTML (no tab, not wider)

Section titles #

Titles are marked with one or more #.

Before title..

Level 1 #

after title and before next one, should only be used for page title

Level 2 #

after title and before next one

Level 3 #

after title and before next one

Level 4 #

after title and before next one

Level 5 #

after title and before next one, too deep, probably should never be used

Level 6 #

after title and before next one, too deep, probably should never be used

Text formatting #

Normal text in a paragraph. You can just write along. Spaces between word or line breaks don’t matter. An empty line starts a new paragraph.

Use _ or * to highlight words in italics text. Use __ or ** to highlight words in bolded text. Don’t mix bolding and italics.

• bold with underscore
• bold with double asterisk
• italics with underscore
• italics with asterisk

Standard usage at Starburst is to use asterisk *bold*.

Code blocks and other source code #

Inline usage of source code in markdown uses simple backticks to surround the variable or simple command:

Add ~/bin to the PATH with EXPORT PATH=~/bin:$PATH.

In HTML snippets, like tables and such, use <code>sample.txt</code>.

Separate code block with three backticks:

cd /opt/dev/myproject
mvn clean install

You can declare a language like shell after the initial three backticks to get syntax highlighting.

Here is a shell fenced block:

cd /opt/dev/myproject
mvn clean install

A java fenced block:

String a = String.valueOf(2);   //integer to numeric string
int i = Integer.parseInt(a); //numeric string to an int

A yaml fenced block:

image:
  repository: "harbor.starburstdata.net/starburstdata/hive"
  tag: "338.2.2-rc.1-SNAPSHOT"
  pullPolicy: "IfNotPresent"
expose:
  type: "clusterIp"
  clusterIp:
    name: "hive"
    ports:
      http:
        port: 9083
  nodePort:
    name: "hive"
    ports:
      http:
        port: 9083
        nodePort: 30083

A sql fenced block:

SELECT ARRAY[4, 5, 6] AS integers,
       ARRAY['hello', 'world'] AS varchars;

 integers  |   varchars
-----------+----------------
 [4, 5, 6] | [hello, world]

If for some reason you really must have line numbers, then you must use a liquid highlight block. This java highlight block uses the linenos keyword to display line numbers:

1
2
String a = String.valueOf(2);   //integer to numeric string
int i = Integer.parseInt(a); //numeric string to an int

However, if you find yourself needing to refer to line numbers, your codeblock is likely too long for your purpose. Consider instead a one- to two-line excerpt to illustrate what you are writing about, even if you keep the longer codeblock intact.

Unordered lists #

Use - or * for the items.

• Apple
• Pear
• Banana

You can also indent:

• Pets
  • Dog
  • Cat
• Farm animal
  • Cow
  • Sheep

Ordered lists #

The actual numbers in your document’s source code aren’t used as the line number values in static documents. The line numbers you see in the generated documents are computed. So you can use e.g. 1. all the time. This example uses 1. for all lines in the source document, but the generated document are numbered correctly:

1. Item 1
2. Item 2
   1. Nested 1 (nested items in lists require 4 spaces to indent properly)
   2. Nested 2
3. Item 3

Definition lists #

Use dl/dt/dd HTML:

<dl>
  <dt>Term 1</dt>
  <dd>the description for term 1</dd>
  <dt>Term 2</dt>
  <dd>the description for term 2</dd>
  <dd>another description for term 2</dd>
</dl>

Renders as:

Term 1

the description for term 1

Term 2

the description for term 2

another description for term 2

Simplified definition list syntax #

As an alternative to HTML markup tags for definition lists, you can use an extended simple syntax. It’s actually less typing to create the definition list in this manner. The extended syntax supports markdown markup within the definition list itself.

Enter the term on the first line, and on the next line, enter a colon followed by a space and the term definition:

First Term
: This is the definition of the first term.

Second Term
: This is one definition of the second term.
: This is another definition of the second term. **Boldly** go forth and make
[links to your docs](https://starburstdata.github.io/get-started/index.html)
within your definition list markup.

Renders as:

First Term

This is the definition of the first term.

Second Term

This is one definition of the second term.

This is another definition of the second term. Boldly go forth and make links to your docs within your definition list markup.

Links #

• Markdown syntax with [text](url) is preferred
• Relative links are preferred to avoid issues with the root context
• Ideally use (/file.html for absolute links

Tables #

Direct layout markup:

Semantic markup:

Raw HTML:

Videos #

Embedding YouTube videos is supported courtesy https://github.com/nathancy/jekyll-embed-video. video-embed.css is included to make it responsive, but that is untested. Other sources can be supported, but YouTube is all we need for now.

You must include the video ID you want to use in the front matter.

---
youtubeId1: buqtdpuZxvk
---

You can have multiple videos on a page, you just have to give them different names in the front matter.

If you want to use an entire video, just use youtubePlayer.html in your include, with the :

include youtubePlayer.html

If instead you want to play just a portion, use youtubeSnippet.html in your include, and provide start and end values in seconds after the video id:

id=page.youtubeId1 start=22 end=31

At this point, you might be wondering to yourself, “But what if I want to start at a particular place, then play until the end?” Great question! In that case, just set the value for end to -1:

id=page.youtubeId1 start=22 end=-1

You’ll have to read the .md file for now to see the entire include, as it just renders the included HTML as html in a comment:

If you are looking to include a Wistia video, use the wistiaPlayer.html in your include.

You can customize the start time by using the start property with the following format start='1m30s'.

*You must use either single or double quotes when adding a property. The value of the id parameter is the same as the value of the wvideo= argument in the Wistia URL.

{% include wistiaPlayer.html id='j38ihh83m5' %}

If you just want to add a admonition with a text to a video, use the video.html. Careful about the apostrophes used for the embedded URL.

Admonitions #

The simplest admonition is just using a blockquote.

This is a simple blockquote.

And after this insightful blockquote, you can have a look at a even bigger blockquote.

And here is a longer one.

Its has two sentences. And also

• a list item
• another item

Beyond that you can use specific warning, caution and note and “Before you begin:” admonitions.

As per Google developer documentation (GDD) a warning is: “Stronger than a Caution; it means “Don’t do this.”

Here is an example of using before-you-begin:

Sadly, ul/li does not seem to make liquid happy. Use dashes as bullets; plain asterisks look tacky.

“Ok, that’s great in Jekyll and all, but I need a ‘Before you begin in Sphinx.” Jazzy! You can do that. Here’s how:

.. admonition:: Before you begin

  You should totaly do all the required reading.

A warning example. Note that as in the Before you begin example above, multi-line, paragraph-shaped passages work in the styling and require breaks:

A caution, which, as per GDD “Suggests proceeding with caution”:

A note (GDD: “An ordinary note or tip”):

A note with a long link to see if it breaks/wraps:

You can also use capture to create a large section of content and then pass that to the admonition.

Side navigation #

To include multiple levels of navigation you will need to use the following yml syntax:

nav:
  - title: SEP Overview
    context: /starburst-enterprise/index
  - title: Platform administrators
    id: admins
    collapse: /platform-administrator
    subnavigation:
      - title: Home
        context: /platform-administrator/index
      - title: SEP clusters
        id: test
        collapse: /platform-administrator/cluster
        subfolderitems:
         - title: Test
           context: /platform-administrator/cluster/test