Starburst Internal Reference

  • Overview
  • Markdown
  • Images
  • Personas
  • Tag list
  • 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 uses simple backticks to surround the variable or simple command:

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

    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:

      repository: ""
      tag: "338.2.2-rc.1-SNAPSHOT"
      pullPolicy: "IfNotPresent"
      type: "clusterIp"
        name: "hive"
            port: 9083
        name: "hive"
            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:

    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:

    Term 1
    the description for term 1
    Term 2
    the description for term 2
    • 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:

    Tables Are Cool
    col 3 is right-aligned $1600
    col 2 is centered $12
    zebra stripes are neat $1

    Semantic markup:

    Markdown Less Pretty
    Still renders nicely
    1 2 3

    Raw HTML:

    First name Last name
    Alison Loney
    Manfred Moser

    Videos #

    Embedding YouTube videos is supported courtesy 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 admonitions.

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

    Note that multi-line, paragraph-shaped passages work in the styling:

    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:

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