• Markdown Cell Table
• Markdown Cell Databricks
• What Is A Markdown Cell

Created: 2015-07-03. GUI Documentation contains an in-depth description of all the features in the RCloud Graphic User Interface (GUI). RCloud documentation is currently maintained by Spencer Seidel on a voluntary basis.

Easily create tables in extended Markdown format supported by Markdown Here and GFM.

Table of Contents

1. Graphic User Interface (GUI) Overview
   • GUI Navigation
2. Cells
   • Markdown Cells
3. Notebooks
   • Saving Your Work
     • Versioning
   • Hidden Notebooks
   • Sharing Your Notebooks
     • view.html
4. Data Access
5. Notebook Assets
6. Search
7. Settings
8. Comments

1. Getting Started

RCloud supports Chrome, Chromium (the open-source version of Chrome), and Firefox web browsers, so you'll need to download the latest version of any of these to get started.

Next, RCloud uses GitHub technology to store information about users and their RCloud notebooks. Therefore, a new user must register with their installation's instance of GitHub. Please refer to your installation's local documentation about creating new users.

Markdown is a way of formatting text and inserting images. It can be used with the following features of Habitica: Titles, notes, and checklists for tasks and Rewards (including tasks and Rewards. I love the 'attach image' functionality from PR #621. However, currently I need to manually adjust the size of the image before I attach it to get a proper rendering (appropriate width). TableConvert.com is not only a markdown table generator but also a markdown table editor. It’s an easy thing to convert json, csv, excel, latex table and html table into markdown tables.

Finally, every installation's networking architecture will be different. Please refer to your installation's local documentation for any relevant information.

2. Graphic User Interface (GUI) Overview

Parts of the GUI

The RCloud GUI consists of: * Header Bar located in the banner or navigation section of the browser * Left and right Windowshade Panels * Prompt and Markdown Cells located in the center of the screen

GUI Navigation

Opening and Closing Panels

Clicking on the title of a panel opens and closes (and resizes in some cases) RCloud panels, such as Notebooks and Search.

Opening and Closing All Panels

When all RCloud panels are minimized in a column, a '+' sign will appear, as shown here.

Clicking the '+' sign will restore all panels in the column to their previous sizes. Now, a '-' sign will appear, shown below, which will minimize all open panels in a column.

Right Windowshade Panel

Changing Panel Width

To change the width of a panel, hover your mouse over the the edge that touches the cells in the middle. When it changes into a double arrow, click and drag left and right to resize.

3. The Header Bar

Here is the RCloud header bar:

: Please see the Sharing Your Notebooks section for more information.

: Click the star icon to toggle the appearance of the current notebook in the My Interests area on the left sidebar. The icon displays the number of RCloud users who have added the notebook to their interests. In the case shown above, five users have done so.

: Click the fork icon to make a new copy of a notebook for editing.

: Whenever you run a notebook, RCloud automatically saves a revision in GitHub. If you need to close your RCloud session immediately without waiting for a lengthy run time, click the save icon to save a revision immediately.

: Click the play icon to run all markdown and prompt cells in the current notebook. Cells are executed asynchronously. RCloud displays the output as it becomes available.

: This is the title of the current notebook. In this case, 'Markdown Basics.' Click the title to change it.

Note that you can create sub-directories simply by adding any number of forward slashes '/', like on a Unix command line. E.g. Cookbook for R/1 - Basics/1.1 - Indexing into a Data Structure. If the sub-directories don't already exist, RCloud will create them on the fly, so there is no need to create individual sub-directories before changing the name of your notebook. Sub-directories allow you to group your notebooks and will be displayed in a tree-like hierarchy in the Notebooks section of the left sidebar.

Also, if the notebook was created as a result of forking another notebook, the forked notebook name is displayed in a smaller font beneath the current notebook's title.

Click the Advanced tab to access more features:

• Open in GitHub: Notebooks are stored as GitHub 'gists,' although you'll rarely need to interface directly with GitHub. This means you get all the power of a source-control versioning system for free. Behind the scenes, GitHub stores every revision of your notebooks, so you can retrieve them later, if necessary. In the GitHub web interface, you can delete your notebooks, edit the text, or change the privacy settings, among other things. For more about using the GitHub interface see the GitHub help pages.
• Load Notebook by ID: Replace the current notebook with another via URL or GitHub Gist ID.
• Import External Notebooks: Using this dialog, you can import multiple notebooks stored in another GitHub repository. You'll need the source GitHub repository API URL and a list of notebook IDs, newline separated. In addition, you can supply a prefix that will cause all the imported notebooks to go into a folder. E.g. 'myfolder/'. Note the trailing '/' character.
• Export Notebook to File: Your browser will automatically save a copy of the current notebook in JSON format in whatever directory you've designated for downloads. The file name will be the same as your notebook with a .gist extension.
• Import Notebook from File: In order to import a notebook, it must be in the same format as an exported notebook. Once you specify the notebook's location, you can validate the notebook by clicking the word 'Validate.' To import, click the Import button.
• Export Notebook as R Source File: When selected, your browser will download an R source text file named after your notebook with .R appended.
• Publish Notebook: By default, users who wish to view your notebooks must be logged into RCloud. If the Publish Notebook box is checked, any user who has network access to the notebook's URL will be able to view the notebook. Obviously, editing features will be turned off for these users.

: Click Logout to end your RCloud session.

4. Cells

There are two types of cells in RCloud, both used for inserting code. The first is the prompt cell, which allows you to interact with RCloud in more-or-less command-line fashion. Prompt cells are useful for quick, interactive sessions.

Prompt cells support either R or Python, which you can specify in the pull-down menu to the right of each cell:

Prompt / Markdown Cell Selection

Note that 'data marshalling,' or using objects between cells of different languages, is not supported at this time.

The second type is the markdown cell. Markdown cells are better suited for cutting and pasting chunks of R code and adding simple formatted documentation. Note that markdown cells do not currently support Python.

We'll get to the difference between Markdown and RMarkdown cells in a moment.

Prompt Cells

Prompt cells mostly act like an interactive R or Python shell. Type a line of code, press Enter/Return, and the command is immediately executed. When RCloud is finished, you're presented with the result and a new prompt cell.

For example, here's the result of pressing Enter/Return after typing a command:

Note that after executing a command, RCloud presents several icons that allow you to interact with the cell: , , , and . Here's a brief description of each:

• Run the code in the cell.
• Edit the code in the cell (clicking on your code also enables editing).
• Split the cell into two parts at the cursor.
• Delete the cell.

Another way to interact in multi-line mode with prompt cells is to cut and paste multiple lines of code into the cell. When you do, you'll see something like this:

To execute the code, simply put your cursor at the end of the last line and press Enter/Return.

Note that it is currently not possible to insert a prompt cell above an existing prompt cell. The only way to add new prompt cells is by executing the current prompt cell. When you do, a new cell is created under the existing one.

Markdown Cells

Adding R Code

Markdown cells are where you enter and edit blocks of multi-line R markdown. Markdown is a plain-text formatting syntax used to create simple formatted documents. In order to differentiate your R code from text, surround your code with the following (back ticks, brackets and 'r'):

Markdown

Here's some sample markdown, suitable for cutting and pasting into a markdown cell:

Running your code

When you're done editing in a markdown cell, click the icon to the right of the cell. Here is the result:

Full documentation of markdown syntax is available here.

Editing and Viewing Results

If you find a typo or would like to otherwise edit your R code, click the icon. You can also click on any code portions of the output to enter edit mode.

Adding and Deleting Markdown Cells

To insert a markdown cell above, click the icon. To insert a markdown cell below, click the icon. To delete a markdown cell altogether, click the icon.

Cell Run-State Indicator

The run-state of each cell is displayed via an icon in between the gutter and cell name:

: The cell has not been run. This could also mean that the cell ran successfully, but the output may not be consistent with the code in the cell because the code was modified after RCloud initiated a run of your notebook.

: The cell is queued to be run.

: RCloud initiated a run of your notebook, but a cell's code was modified after execution was initiated.

: The cell is running.

: The cell is running, but because the code was modified after notebook execution was initiated, the output may not be consistent with the code.

: The cell ran successfully.

: The cell ran but had errors.

: The cell's run was cancelled.

Stopping Cell Execution

When you run a notebook, you can stop running cells and prevent queued cells from running by pressing the stop button, located in the header at the top of the screen:

Nonpreemptive Stop

This ends an interrupt to the R process and terminates execution if possible.

Rearranging Cells

To rearrange your cells, click and drag the blank status area above the cell or the icon to the left of the cell.

Joining Cells

To join cells of the same flavor, click the join icon at the right of the cell. This will combine the contents of the cell with the cell immediately above it.

Markdown versus RMarkdown Cells

Behind the scenes, RCloud uses several different R packages to render output. Markdown cells use the markdown and knitr packages directly for output. RMarkdown cells, on the other hand, use rmarkdown (a.k.a. R Markdown v2).

Currently RMarkdown support should be considered experimental.

5. Notebooks

RCloud notebooks are simply collections of prompt and markdown cells, comments, and assets, which we'll get to later. Everything in your public notebooks is searchable by every other user of the system. This encourages reuse and makes learning how to use the hundreds of available R packages easier.

You can also browse everyone else's notebooks by opening the Notebooks section on the left sidebar. To do this, simply click on Notebooks at the top of the panel. This toggles the panel, opening or closing it:

RCloud User / Notebook Directory

To load a notebook into the current session, click on the name. After it loads, you can examine the source code or click 'Run' in the header bar to execute all the cells on the page.

Creating a Notebook

To create a new, blank notebook, click the + sign at the right of the Notebooks panel header area:

RCloud will automatically choose a title for your new notebook, Notebook N, where N is the next available number among your notebooks. To give your notebook a more meaningful title, click on the title in the header bar.

To change the default name of new notebooks, see the New Notebook Prefixes sub-section of the Settings section.

Running a Notebook

To run all the cells in your notebook, click the icon in the header bar.

RCloud notebooks are executed asynchronously. RCloud will show individual cell results as the results are ready to display.

Long-Running Notebooks

Notebooks that run longer than a few seconds will cause the browser screen to dim and a please-wait message to be displayed.

Currently, RCloud has no explicit mechanism to stop a long-running notebook. If you mistakenly launch a long-running notebook, you can simply reload the notebook in another browser tab or reload the page. This doesn't stop the execution behind the scenes, but the output of the previous run will not interrupt your current session. Be careful of side-effects, like changing the contents of a file in your local directory in such a way that it affects the output of the notebook.

Forking (Copying) a Notebook

To copy another user's notebook, first navigate to it in the left sidebar and then click to load it into your current session. Now, you're running another user's public notebook in your own session. This is sufficient for running reports or performing other read-only activities. If you want to edit the notebook, you'll need to make your own copy, or, 'fork' it.

After you've loaded the notebook you want to fork, click the Fork icon in the header bar at the top of the screen:

Header Bar: Fork Icon

After forking a notebook, you'll own your own copy and therefore be able to edit it.

The fork icon is always available, which means you can fork your own notebooks. If you are viewing a previous version of a notebook, you can fork a copy of that version. Caution: currently when you fork your own notebook, the history is lost; we hope to fix this soon.

Saving Your Work

There are two mechanisms by which your work is saved in RCloud.

Manual Saving

You can save your notebook at any time by clicking the icon in the header bar.

Versioning

RCloud keeps track of your notebook versions automatically and frequently. Every time you save, create, or run a markdown or prompt cell, the newest version of your notebook is saved. To browse the versions of your notebook, which are stored chronologically with the latest version on top, hover over the name of your notebook in the left sidebar and click the clock icon:

To change they way dates and times are displayed next to your notebook versions, see the show terse version dates setting.

Version Tagging

Reverting to a Previous Version

Should you decide that a previous version of your notebook is the 'best' version, you can make that version the current version by loading the desired previous version of the notebook and clicking the revert icon.

REVERT

Hidden Notebooks

By default, all RCloud notebooks are visible to all RCloud users. If you'd like to toggle the Show/Hide flag on a notebook, hover over the name of your notebook on the left sidebar and click the eye icon. Note that hidden notebook titles are grayed out for owners and invisible to other users.

Hidden notebooks are only invisible within the RCloud interface. Hidden notebooks are still visible within the gists stored in your GitHub instance.

Toggle Hidden

Clicking the icon will hide your notebook from other RCloud users.

Toggle Show

Clicking the icon will make your notebook readable by other RCloud users.

Protecting Your Notebooks

Protected notebooks are readable only by the owner and (optionally) a select group of users and will not show up in search results (although previously unprotected versions might).

View or modify notebook protection by clicking the notebook 'info' button next to the notebook name in the notebooks tree:

If you own the notebook, click the 'no group' link (or a group name if one exists):

Notebook Protection Dialog: Group Information

This opens the notebook protection dialog:

Here, you can assign the notebook to any group you are a member of or make it entirely private (readable only by you).

Use the second tab of the protection dialog to create/rename groups and/or assign other users as administrators/members of groups you administrate.

Notebook Protection Dialog: Group Creation / Renaming / Membership

Note that, unlike a hidden notebook, protected notebooks are not readable by anyone without permission, even within your GitHub instance.

Deleting Notebooks

To delete a notebook, hover over the name of your notebook in the left sidebar and click the icon.

RCloud will ask for a confirmation:

Click OK and the notebook will disappear from the left sidebar and the last-viewed available notebook will automatically load into the current session.

Sharing Your Notebooks

There are several ways you can share your notebooks with colleagues. When you click on the downward arrow next to the share icon in the header bar , a popup menu will appear:

Header Bar: Share / View Dropdown Menu Selection

This allows you to select the kind of URL you'd like to share. Make your selection using the popup menu and then right click on the icon to copy the hyperlink.

Note that if you have a tagged version of your notebook currently loaded, where appropriate, RCloud will populate the shared URL with the tag instead of the version. This is beneficial because then you can tag future versions with the same tag and not break existing URLs.

view.html

This is the simplest method. This will create a link that will allow someone to see the notebook code and execute the notebook within the RCloud IDE. Users who do not own the notebook will see the play and share icons in the header. Clicking the play icon will execute all cells in the notebook. Clicking the edit icon will return to the normal header, allowing a user to fork the notebook, etc.

Hiding UI Elements

To hide all UI elements, add &quiet=1 to the URL. Note that this works only with view.html.

notebook.R

This option is intended for FastRweb notebooks. Loading the URL (from anywhere, including other notebooks, a perl script, etc.) executes a notebook 'behind the scenes' by opening a one-time R session, running the defined 'function' within, shutting down the R session, and finally, returning the result. FastRweb notebooks MUST have a function named function() defined, as this what notebook.R tries to execute upon instantiation. Output from notebook.R can be anything. Text, binary data, whatever, as this information will ultimately be processed by whatever mechanism that called notebook.R.

notebook.R allows trailing paths to be processed by the notebook code if they start with /.self/. The subsequent path portion is passed to the run function as the .path.info argument. This allows notebooks to handle a 'full tree' argument to the notebook on top of a single notebook URL.

E.g.: https://rcloud.mydomain.com/notebook.R/user/notebook/.self/foo/bar will call the notebook with .path.info set to /foo/bar. Note that the .self part distinguishes asset look up from a path info call.

See the notebook.R URLs section of the documentation for more detailed information about notebook.R URLs.

mini.html

Unlike notebook.R, mini.html URLs open an R session via a Websocket and keep it open. Mini.html notebooks MUST have a function named rcw.result() defined, as that is what mini.html tries to execute upon instantiation. Because the R session is kept open, users or processes can interact with the R session while the websocket is kept open.

shiny.html

RCloud supports the RStudio Shiny web application framework. To share Shiny-enabled notebooks, select this option.

Who Starred my Notebook?

To find out which users starred your notebook, click the notebook information icon:

Saving Plots

Hover the mouse over a plot created in an R cell to make the disk icon appear in the upper right corner (see 1), which contains a list of available image formats. A widget at the lower-right corner can be used to resize the image (see 2).

Note that you can only save plots created in R cells.

Find and Find Replace

To find text within your notebook, type Ctrl-F (Win/Linux) or Cmd-F (Mac) to open a find dialog at the top of your notebook:

find

To find and replace text within your notebook, type Ctrl-H (Win/Linux) or Cmd-Option-F (Mac) to open a find and replace dialog at the top of your notebook:

6. Data Access

File Upload

There many ways to use your own data in RCloud. Please see the example notebooks under RCloud Sample Notebooks for some examples. Here, we'll take a closer look at the simplest method: uploading a flat file. Open the File Upload panel on the right sidebar by clicking on the heading. Then, select 'Choose File' and browse to a local file, in this case 'distrib.csv.'

File Upload: Example 1

Next, click the 'Upload' button. If the file exists (just where, we'll get to in a moment), RCloud prompts with a notice that it will be overwritten. If all goes well, RCloud confirms the upload.

The file now exists in your installation server's home directory and is accessible from within RCloud. For example:

The first line of R code loads the contents of the CSV file into an object called 'mydata.' The next line tells R to output a string version of the object.

Upload to Notebook

The Upload to Notebook checkbox changes the way File Upload works. Rather than uploading your file to your home directory, RCloud will store the file inside your notebook as an 'asset.' To view notebook assets, click on the assets bar on the right sidebar. Please see the Notebook Assets section for more information.

7. Notebook Assets

Notebooks can contain 'assets,' which are files that can be used within your notebooks or simply for keeping track of unused code (as in the the case of scratch.R, which is a text file where you can keep bits of code while working on your notebook).

ASSETAREA

Data as an Asset

For example, from the previous example, lets create an asset called distrib.csv that contains the following data:

We can store this data in a new asset called 'distrib.csv,' simply by clicking New Asset and typing distrib.csv as a name.

Now, this data is accessible in your R code:

Uploading Assets

In addition to manually entering asset text, you can also drag and drop files into the Assets panel to upload them:

Drag and Drop File Upload

Assets Links

RCloud automatically generates asset links and displays them in the lower left-hand corner of the Assets panel. To copy the URL, right-click on it.

Cascading Style Sheets (CSS)

Assets can contain Cascading Style Sheet (CSS) formatting information. This changes the way information is presented when your notebook is executed. For example, here is a bit of CSS that defines a paragraph style:

To use this CSS as an asset, it needs to have a special name that begins with 'rcloud-' and ends with '.css'. In the example below, the name is 'rcloud-mystyle.css'.

RCloud automatically uses CSS asset files with this file pattern and ignores others, so you can save bits of CSS in other files without worrying about overlap.

To use the p.mystyle paragraph style, simply reference it in markdown using HTML:

Using / Adding CSS

Note that you must reload your notebook to apply the CSS.

JavaScript

Assets can also contain JavaScript. When editing JavaScript (files must have the .js extension), RCloud automatically uses a JavaScript editing mode, which has built-in syntax checking.

HTML Mode

When editing HTML (files must have the .html or .htm extension), RCloud automatically uses an HTML editing mode, which has built-in syntax checking and tag completion.

HTML File and Syntax Checking

Renaming Assets

To rename an asset, simply click on the file name on the asset's tab.

Binary Assets

Assets can be binary (e.g. an image). RCloud auto-detects the content format and transparently encodes and decodes using base-64 encoding. When possible, the content is displayed in its native format in the asset panel.

Asset Size

Assets are limited to 750KB each.

8. notebook.R URLs

It's possible to construct a URL for a notebook asset by selecting Open in GitHub in the Advanced menu, locating your asset and right-clicking the 'View Raw' icon, which looks like <> next to your asset. The URLs look like this:

https://github.mydomain.com/gist/rclouddocs/d2b9231aca224bbbb888/raw/efb98239f9acc030f98b2cd1957ce7c9b4b9f2c3/DummyData.csv

This is unwieldy. A better and more powerful way to access assets is via the HTTP entry point, notebook.R.

Notebook.R allows you to access your notebook in the following ways:

URLs ending in '<filename>' will return the given asset (file). To illustrate how it works using the previous example, any of these give HTTP access to the latest version of DummyData.csv:

Access to assets isn't the only thing you can do with notebook.R. Notice that in the list of ways to access your notebook above, not all methods reference a filename. If you reference a notebook or revision of a notebook, the URL will return the result of the evaluated notebook.

notebook.R is intended to be a general-purpose Remote Procedure Call (RPC) in R. RPCs in RCloud should always contain some markdown to document what the RPC does, what the arguments are, etc. This way other users can simply view your notebook in RCloud to understand how to use it. This isn't enforced in any way but is encouraged to promote reuse. The markdown is only visible when users visit your notebook in RCloud. The markdown is not output when called remotely.

Please see the following for more notebook.R features and information.

9. Search

To conduct a global text search in all public RCloud notebooks, simply open up the search panel by clicking on Search on the left sidebar. Here are the results for a search on 'markdown.' RCloud searches code, comments, notebook names, assets, everything.

Search Results

1

Results can be sorted by the number of stars a notebook has, the author of the notebook (User), the notebook's name, or by the date a notebook was created.

2

Sorts the results in descending (Desc) or ascending (Asc) order.

3

When too many results are returned for any one notebook, RCloud will display a Show me more link that, when clicked, will toggle the rest of the results.

4

Search results are paginated. Click on any page number below the results or use the back or next page to page through the results.

Complex Searches

RCloud supports Lucene's feature-rich query parser syntax for more complex searches. Features include wildcard, fuzzy, and proximity searches, boolean operators, grouping, and much more.

Please see the official query parser syntax documentation for more information.

10. Settings

Various aspects of your RCloud session can be changed here.

Show Command Prompt

This setting toggles the appearance of the default prompt cell that appears at the bottom of the currently loaded notebook.

Show Terse Version Dates

This controls how RCloud displays dates when viewing notebook versions. When selected, RCloud will display dates and times only when they're different from the version before it.

Show Cell Numbers

Toggles 'Cell 1,' 'Cell 2,' etc. in the cells panel.

Extensions

Power users can extend RCloud's user interface with global and per-user extensions. Although this functionality is outside the scope of this document, more information is available here.

You can enable and disable extensions using the 'Enable Extensions' and 'Disable Extensions' text boxes. These set the user options addons and skip-addons, respectively. On starting the session, any extensions listed in skip-addons are not loaded.

Enter a list of extensions, comma delimited, and press enter. You will then have to reload the page.

New Notebook Prefixes

Use the New Notebook Prefix setting to change how RCloud names new notebooks.

Suppose you were working on a project, Foo. You might choose 'Foo ' for your new notebook prefix. New notebooks would be named 'Foo 1,' 'Foo 2,' and so on.

You could also include a folder. RCloud would then place new notebooks within that folder in the notebook tree. For example, you may choose to make 'Foo/Notebook ' your new notebook prefix name. RCloud would create new notebooks 'Foo/Notebook 1,' 'Foo/Notebook 2,' and so on.

Anyone can leave comments about anyone's notebooks in the Comments panel in the right sidebar, as demonstrated below:

Notebook Comment Icon

Comments are included in search results.

To submit a comment, simply input your text in the text area and click the comment icon . You can also submit your comment by pressing Ctrl-Enter (Win/Linux) or Cmd-Enter (Mac).

Editing Comments

To edit a comment, click on the comment text to make changes. Then click Ctrl- or Cmd-Enter to update the comment.

Deleting Comments

To delete a comment, hover your mouse over the comment. Click the X next to the comment to delete it.

Delete Notebook Comment

12. Help

It's often difficult to remember arguments to functions and what they mean, so RCloud has an inline help feature. In a new prompt cell, type a question mark immediately followed by an R function name and then press Enter/Return to execute the cell:

If help is available, RCloud will open the Help panel:

Alternatively, you can enter a function name in the text box at the top of the panel and click the help icon .

13. Workspace

In the course of working with your notebook, variables are defined and assigned. Often, it is convenient to know the value of a variable without issuing a command to display it. The Workspace panel displays every variable you've defined along with its value.

In the case of dataframe variables, a link is displayed, which, when clicked, will open up the Dataframe panel.

14. Dataframe

Dataframe Section

Dataframe objects are displayed here after you click a dataframe link in the Workspace panel or use the View(object) command in a cell:

15. Session

The session panel displays critical system information when available, such as session timeouts. The panel will automatically open when messages are available.

Click the icon to dismiss a session notification.

16. RStudio Shiny Support

RCloud contains preliminary support for the RStudio Shiny web application framework via the rcloud.shiny package. rcloud.shiny emulates a network connection to run Shiny on an RCloud server and client instead of a Shiny server. Basic functionality is supported. Shiny extensions are not yet supported.

Although comprehensive documentation of rcloud.shiny is beyond the scope of this document, the implementation is simple enough to get many users already familiar with Shiny started.

To learn more about how to use Shiny in RCloud, please see the rcloud.shiny example notebooks under RCloud Sample Notebooks in the Notebooks panel and the official Shiny documentation.

Overview

Markdown is created by Daring Fireball; the original guideline is here. Its syntax, however, varies between different parsers or editors. Typora try to follow GitHub Flavored Markdown, but may still have small incompatibilities.

• Block Elements
• Span Elements
  • Links
• HTML

Block Elements

Paragraph and line breaks

A paragraph is simply one or more consecutive lines of text. In markdown source code, paragraphs are separated by two or more blank lines. In Typora, you only need one blank line (press Return once) to create a new paragraph.

Press Shift + Return to create a single line break. Most other markdown parsers will ignore single line breaks, so in order to make other markdown parsers recognize your line break, you can leave two spaces at the end of the line, or insert <br/>.

Headers

Headers use 1-6 hash (#) characters at the start of the line, corresponding to header levels 1-6. For example:

In Typora, input ‘#’s followed by title content, and press Return key will create a header. Or type ⌘1 to ⌘6 as a shortcut.

Blockquotes

Markdown uses email-style > characters for block quoting. They are presented as:

In Typora, typing ‘>’ followed by your quote contents will generate a quote block. Typora will insert a proper ‘>’ or line break for you. Nested block quotes (a block quote inside another block quote) by adding additional levels of ‘>’.

Lists

Typing * list item 1 will create an unordered list. (The * symbol can be replace with + or -.)

Typing 1. list item 1 will create an ordered list.

For example:

Task List

Task lists are lists with items marked as either [ ] or [x] (incomplete or complete). For example:

You can change the complete/incomplete state by clicking on the checkbox before the item.

(Fenced) Code Blocks

Typora only supports fences in GitHub Flavored Markdown, not the original code block style.

Using fences is easy: type ``` and press return. Add an optional language identifier after ``` and Typora runs it through syntax highlighting:

Math Blocks

You can render LaTeX mathematical expressions using MathJax.

To add a mathematical expression, enter $$ and press the ‘Return’ key. This will trigger an input field which accepts Tex/LaTex source. For example:

[mathbf{V}_1 times mathbf{V}_2 = begin{vmatrix}mathbf{i} & mathbf{j} & mathbf{k} frac{partial X}{partial u} & frac{partial Y}{partial u} & 0 frac{partial X}{partial v} & frac{partial Y}{partial v} & 0 end{vmatrix}]

In the markdown source file, the math block is a LaTeX expression wrapped by a pair of ‘$$’ marks:

You can find more details here.

Tables

Standard Markdown has been extended in several ways to add table support., including by GFM. Typora supports this with a graphical interface, or writing the source code directly.

Enter | First Header | Second Header | and press the return key. This will create a table with two columns.

After a table is created, placing the focus on that table will open up a toolbar for the table where you can resize, align, or delete the table. You can also use the context menu to copy and add/delete individual columns/rows.

The full syntax for tables is described below, but it is not necessary to know the full syntax in detail as the markdown source code for tables is generated automatically by Typora.

In markdown source code, they look like:

You can also include inline Markdown such as links, bold, italics, or strikethrough in the table.

By including colons (:) within the header row, you can set text in that column to be left-aligned, right-aligned, or center-aligned:

A colon on the left-most side indicates a left-aligned column; a colon on the right-most side indicates a right-aligned column; a colon on both sides indicates a center-aligned column.

Footnotes

MultiMarkdown extends standard Markdown to provide two ways to add footnotes.

You can create reference footnotes like this¹ and this².

will produce:

Hover over the ‘fn1’ or ‘fn2’ superscript to see content of the footnote. You can use whatever unique identified you like as the footnote marker (e.g. “fn1”).

Hover over the footnote superscripts to see content of the footnote.

Horizontal Rules

Markdown Cell Table

Entering *** or --- on a blank line and pressing return will draw a horizontal line.

YAML Front Matter

Typora now supports YAML Front Matter. Enter --- at the top of the article and then press Return to introduce a metadata block. Alternatively, you can insert a metadata block from the top menu of Typora.

Table of Contents (TOC)

Enter [toc] and press the Return key to create a “Table of Contents” section. The TOC extracts all headers from the document, and its contents are updated automatically as you add to the document.

Span Elements

Span elements will be parsed and rendered right after typing. Moving the cursor in middle of those span elements will expand those elements into markdown source. Below is an explanation of the syntax for each span element.

Links

Markdown supports two styles of links: inline and reference.

In both styles, the link text is delimited by [square brackets].

Inline Links

To create an inline link, use a set of regular parentheses immediately after the link text’s closing square bracket. Inside the parentheses, put the URL where you want the link to point, along with an optional title for the link, surrounded in quotes. For example:

will produce:

This is an example inline link. (<p>This is <a href='http://example.com/'>)

This link has no title attribute. (<p><a href='http://example.net/'>This link</a> has no)

Internal Links

To create an internal link that creates a ‘bookmark’ that allow you to jump to that section after clicking on it, use the name of the header element as the href. For example:

Hold down Cmd (on Windows: Ctrl) and click on this link to jump to header Block Elements.

Reference Links

Reference-style links use a second set of square brackets, inside which you place a label of your choosing to identify the link:

In Typora, they will be rendered like so:

This is an example reference-style link.

The implicit link name shortcut allows you to omit the name of the link, in which case the link text itself is used as the name. Just use an empty set of square brackets — for example, to link the word “Google” to the google.com web site, you could simply write:

In Typora, clicking the link will expand it for editing, and command+click will open the hyperlink in your web browser.

URLs

Typora allows you to insert URLs as links, wrapped by <brackets>. For example <[email protected]> becomes [email protected].

Typora will also automatically link standard URLs (for example: www.google.com) without these brackets.

Images

Images have similar syntax as links, but they require an additional ! char before the start of the link. The syntax for inserting an image looks like this:

You are able to use drag and drop to insert an image from an image file or your web browser. You can modify the markdown source code by clicking on the image. A relative path will be used if the image that is added using drag and drop is in same directory or sub-directory as the document you’re currently editing.

If you’re using markdown for building websites, you may specify a URL prefix for the image preview on your local computer with property typora-root-url in YAML Front Matter. For example, Enter typora-root-url:/User/Abner/Website/typora.io/ in YAML Front Matter, and then ![alt](/blog/img/test.png) will be treated as ![alt](file:///User/Abner/Website/typora.io/blog/img/test.png) in Typora.

Emphasis

Markdown treats asterisks (*) and underscores (_) as indicators of emphasis. Text wrapped with one * or _ will be wrapped with an HTML <em> tag. For example:

produces:

single asterisks

single underscores

GFM will ignore underscores in words, which is commonly used in code and names, like this:

wow_great_stuff

do_this_and_do_that_and_another_thing.

Markdown Cell Databricks

To produce a literal asterisk or underscore at a position where it would otherwise be used as an emphasis delimiter, you can backslash escape it with a backslash character:

Typora recommends using the * symbol.

Strong

A double * or _ will cause its enclosed contents to be wrapped with an HTML <strong> tag, e.g:

produces:

double asterisks

double underscores

Typora recommends using the ** symbol.

Code

To indicate an inline span of code, wrap it with backtick quotes (`). Unlike a pre-formatted code block, a code span indicates code within a normal paragraph. For example:

will produce:

Use the printf() function.

Strikethrough

GFM adds syntax to create strikethrough text, which is missing from standard Markdown.

~~Mistaken text.~~ becomes Mistaken text.

Emoji :happy:

Enter emoji with syntax :smile:. To make it easier, an auto-complete helper will pop up after typing : and the start of an emoji name.

Entering UTF-8 emoji characters directly is also supported by going to Edit -> Emoji & Symbols in the menu bar.

Inline Math

To use this feature, please enable it first in the Markdown tab of the preference panel. Then, use $ to wrap a LaTeX command. For example: $lim_{x to infty} exp(-x) = 0$.

To trigger inline preview for inline math: input “$”, then press the ESC key, then input a TeX command.

You can find more details here.

Subscript

To use this feature, please enable it first in the Markdown tab of the preference panel. Then, use ~ to wrap subscript content. For example: H~2~O, X~long text~/

Superscript

To use this feature, please enable it first in the Markdown tab of the preference panel. Then, use ^ to wrap superscript content. For example: X^2^.

Highlight

To use this feature, please enable it first in the Markdown tab of the preference panel. Then, use to wrap highlight content. For example: highlight.

What Is A Markdown Cell

HTML

You can use HTML to style content what pure Markdown does not support. For example, use <span>this text is red</span> to add text with red color.

Underlines

Underline isn’t specified in Markdown of GFM, but can be produced by using underline HTML tags:

<u>Underline</u> becomes Underline.

Embed Contents

Some websites provide iframe-based embed code which you can also paste into Typora. For example:

Video

You can use the <video> HTML tag to embed videos. For example:

Other HTML Support

You can find more details here.

1. Here is the text of the first footnote. ↩

2. Here is the text of the second footnote. ↩