Jupyter Notebook Variable In Markdown

Jupyter (formerly IPython Notebook) is an open-source project that lets you easily combine Markdown text and executable Python source code on one canvas called a notebook. Visual Studio Code supports working with Jupyter Notebooks natively, as well as through Python code files. This topic covers the support offered through Python code files and demonstrates how to:

  1. Jupiter Notebook Variable In Markdown Code
  2. Jupyter Notebook Python Variable In Markdown

Jupyter Notebook - Markdown Cells Markdown cell displays text which can be formatted using markdown language. In order to enter a text which should not be treated as code by Notebook server, it must be first converted as markdown cell either from cell menu or by using keyboard shortcut M while in command mode. Surprisingly, Jupyter Notebooks do not support the inclusion of variables in Markdown Cells out of the box. If you still use Jupyter Notebooks there is a readily solution: the Python Markdown extension. It is part of the nbextensions package which is easy to install and configure. Surprisingly, Jupyter Notebooks do not support the inclusion of variables in Markdown Cells out of the box. If you still use Jupyter Notebooks there is a readily solution: the Python Markdown extension.

  • Work with Jupyter-like code cells
  • Run code in the Python Interactive Window
  • View, inspect, and filter variables using the Variable explorer and data viewer
  • Connect to a remote Jupyter server
  • Debug a Jupyter notebook
  • Export a Jupyter notebook

To work with Jupyter notebooks, you must activate an Anaconda environment in VS Code, or another Python environment in which you've installed the Jupyter package. To select an environment, use the Python: Select Interpreter command from the Command Palette (⇧⌘P (Windows, Linux Ctrl+Shift+P)).

Once the appropriate environment is activated, you can create and run Jupyter-like code cells, connect to a remote Jupyter server for running code cells, and export Python files as Jupyter notebooks.

Jupyter code cells

You define Jupyter-like code cells within Python code using a # %% comment:

Note: Make sure to save the code shown above in a file with a .py extension.

When the Python extension detects a code cell, it adds Run Cell and Debug Cell CodeLens adornments. The first cell also includes Run Below and all subsequent cells include Run Above:

Note: By default, Debug Cell just steps into user code. If you want to step into non-user code, you need to uncheck Data Science: Debug Just My Code in the Python extension settings (⌘, (Windows, Linux Ctrl+,)).

Run Cell applies to only the one code cell. Run Below, which appears on the first cell, runs all the code in the file. Run Above applies to all the code cells up to, but not including, the cell with the adornment. You would use Run Above, for example, to initialize the state of the runtime environment before running that specific cell.

Selecting a command starts Jupyter (if necessary, which might take a minute), then runs the appropriate cell(s) in the Python Interactive window:

You can also run code cells using (Ctrl+Enter) or the Python: Run Selection/Line in Python Terminal command (Shift+Enter). After using this command, the Python extension automatically moves the cursor to the next cell. If you're in the last cell in the file, the extension automatically inserts another # %% delimiter for a new cell, mimicking the behavior of a Jupyter notebook.

You can also click in the margin to the left of line numbers to set breakpoints. Then you can use Debug Cell to start a debugging session for that code cell. The debugger stops execution at breakpoints and allows you to step through code one line at a time and inspect variables (see Debugging for details).

Additional commands and keyboard shortcuts

The following table lists additional commands and keyboard shortcuts supported when working with code cells.

CommandKeyboard shortcut
Python: Go to Next CellCtrl+Alt+]
Python: Go to Previous CellCtrl+Alt+[
Python: Extend Selection by Cell AboveCtrl+Shift+Alt+[
Python: Extend Selection by Cell BelowCtrl+Shift+Alt+]
Python: Move Selected Cells UpCtrl+; U
Python: Move Selected Cells DownCtrl+; D
Python: Insert Cell AboveCtrl+; A
Python: Insert Cell BelowCtrl+; B
Python: Insert Cell Below PositionCtrl+; S
Python: Delete Selected CellsCtrl+; X
Python: Change Cell to CodeCtrl+; C
Python: Change Cell to MarkdownCtrl+; M

Python Interactive window

The Python Interactive window, mentioned in the previous section, can be used as a standalone console with arbitrary code (with or without code cells). To use the window as a console, open it with the Jupyter: Create Interactive Window command from the Command Palette. You can then type in code, using Enter to go to a new line and Shift+Enter to run the code.

To use the window with a file, use the Jupyter: Run Current File in Python Interactive Window command from the Command Palette.

IntelliSense

The Python Interactive window has full IntelliSense – code completions, member lists, quick info for methods, and parameter hints. You can be just as productive typing in the Python Interactive window as you are in the code editor.

Plot Viewer

The Plot Viewer gives you the ability to work more deeply with your plots. In the viewer you can pan, zoom, and navigate plots in the current session. You can also export plots to PDF, SVG, and PNG formats.

Within the Python Interactive window, double-click any plot to open it in the viewer, or select the expand button on the upper left corner of the plot.

Note: The Python Interactive window supports rendering plots created with matplotlib and Altair.

Live Share for Python Interactive

The Python Interactive window also supports Visual Studio Live Share for real-time collaboration. Live Share lets you co-edit and co-debug while sharing audio, servers, terminals, diffs, comments, and more.

This feature requires the Live Share extensions to be installed on both host and guest machines.

Variable explorer and data viewer

Within the Python Interactive window, it's possible to view, inspect, and filter the variables within your current Jupyter session. By expanding the Variables section after running code and cells, you'll see a list of the current variables, which will automatically update as variables are used in code.

For additional information about your variables, you can also double-click on a row or use the Show variable in data viewer button to see a more detailed view of a variable in the Data Viewer. Once open, you can filter the values by searching over the rows.

Note: Variable explorer is enabled by default, but can be turned off in settings (Python > Data Science: Show Jupyter Variable Explorer).

Connect to a remote Jupyter server

You can offload intensive computation in a Jupyter notebook to other computers by connecting to a remote Jupyter server. Once connected, code cells run on the remote server rather than the local computer.

To connect to a remote Jupyter server:

  1. Run the Jupyter: Specify local or remote Jupyter server for connections command from the Command Palette (⇧⌘P (Windows, Linux Ctrl+Shift+P)).

  2. Select how you would like to connect to a Jupyter server.

  3. If working remotely, provide the server's URI (hostname) with the authentication token included with a ?token= URL parameter when prompted. (If you start the server in the VS Code terminal with an authentication token enabled, the URL with the token typically appears in the terminal output from where you can copy it.) Alternatively, you can specify a username and password after providing the URI.

  4. The Python Interactive window indicates where code is run by displaying the URI (which is blurred out in the image below):

Note: For added security, Microsoft recommends configuring your Jupyter server with security precautions such as SSL and token support. This helps ensure that requests sent to the Jupyter server are authenticated and connections to the remoter server are encrypted. For guidance about securing a notebook server, see the Jupyter docs.

Convert Jupyter notebooks to Python code file

When you've activated an environment with Jupyter installed, you can open a Jupyter notebook file (.ipynb) in VS Code and then convert it to Python code. Once you've converted the file, you can run the code as you would with any other Python file and also use the VS Code debugger. Opening and debugging notebooks in VS Code is a convenient way to find and resolve code bugs, which is difficult to do directly in a Jupyter notebook.

When you open a notebook file, Visual Studio Code will open it in the Notebook Editor automatically. Use the convert icon on the toolbar to convert the Notebook (.ipynb) file to a Python file (.py).

Select the convert icon followed by 'Python Script', wait a few seconds, and then VS Code opens the converted notebook in an untitled file. The notebook's cells are delimited in the Python file with # %% comments; Markdown cells are converted wholly to comments preceded with # %% [markdown], and render as HTML in the interactive window alongside code and output such as graphs:

Note: The first time you run code cells in a Python file, the Python extension starts a Jupyter server. It may take some time for the server to start up and for the Python Interactive window to appear with the results of the code.

Debug a Jupyter notebook

The Visual Studio Code debugger lets you step through your code, set breakpoints, examine state, and analyze problems. Using the debugger is a helpful way to find and correct issues in notebook code.

  1. In VS Code, activate a Python environment in which Jupyter is installed, as described at the beginning of this article.

  2. Import the notebook's .ipynb file into VS Code as described in the previous section. (Download the file first if you're using a cloud-based Jupyter environment such as Azure Notebooks.)

  3. To start the debugger, use one of the following options:

    • For the whole notebook, open the Command Palette (⇧⌘P (Windows, Linux Ctrl+Shift+P)) and run the Jupyter: Debug Current File in Python Interactive Window command.
    • For an individual cell, use the Debug Cell adornment that appears above the cell. The debugger specifically starts on the code in that cell. By default, Debug Cell just steps into user code. If you want to step into non-user code, you need to uncheck Data Science: Debug Just My Code in the Python extension settings (⌘, (Windows, Linux Ctrl+,)).
  4. To familiarize yourself with the general debugging features of VS Code, such as inspecting variables, setting breakpoints, and other activities, review VS Code debugging.

  5. As you find issues, stop the debugger, correct your code, save the file, and start the debugger again.

  6. When you're satisfied that all your code is correct. Save the file, then export the notebook as described in the following section. You can then upload the notebook to your normal Jupyter environment.

Export a Jupyter notebook

In addition to opening a Jupyter notebook, you can also use one of the following commands from the Command Palette (⇧⌘P (Windows, Linux Ctrl+Shift+P)) to export content from a Python file in VS Code to a Jupyter notebook (with the .ipynb extension).

  • Jupyter: Export Current Python File as Jupyter Notebook: creates a Jupyter notebook from the contents of the current file, using the # %% and # %% [markdown] delimiters to specify their respective cell types.
  • Jupyter: Export Current Python File and Output as Jupyter Notebook: creates a Jupyter notebook from the contents of the current file and includes output from code cells.
  • Jupyter: Export Interactive Window as Jupyter Notebook: creates a Jupyter notebook from the contents of the Python Interactive window.

After exporting the contents, VS Code displays a prompt through which you can open the notebook in a browser.

A common use of directives and roles is to designate “special blocks” of your content.This allows you to include more complex information such as warnings and notes, citations, and figures.This section covers a few common ones.

MyST syntax extensions¶

MyST Markdown has a base syntax that it supports, and additional syntax can be enabled to add extra functionality.By default, Jupyter Book enables a few extra syntax pieces for MyST in order to more closely resemble the Markdown experience in Jupyter Notebooks and interfaces.These extensions are:

dollarmath

To support $$ and $ syntax for math blocks. See Math and equations.

linkify

To auto-detect HTML-like links in your markdown and convert them to hyperlinks.

substitution

To allow you to define markdown “variables” and substitute text in using them. See Substitutions and variables in markdown.

colon_fence

To allow you to use ::: fences for admonitions, in order to make them easier to render in interfaces that do not support MyST. See Markdown-friendly directives with :::.

To enable your own syntax extensions, use the following configuration pattern:

Note that this will override the default Jupyter Book extension list.You should include all of the extensions that you want to be enabled.

See also

For a list of syntax extensions in MyST, see the MyST documentation.

Notes, warnings, and other admonitions¶

Let’s say you wish to highlight a particular block of text that exists slightly apart from the narrative of your page.You can use the {note} directive for this.

For example, the following text:

Results in the following output:

Note

Here is a note!

There are a number of similarly-styled blocks of text. For example, here is a {warning}block:

Warning

Here’s a warning! It was created with:

For a complete list of options, see the sphinx-book-theme documentation.

Blocks of text with custom titles¶

You can also choose the title of your message box by using the{admonition} directive. For example, the following text:

Results in the following output:

Here’s your admonition

Here’s the admonition content

If you’d like to style these blocks, then use the :class: option. Forexample:

This admonition was styled…

Using the following pattern:

Markdown-friendly directives with :::

The admonition syntax above utilises the general directives syntax.However, if you’re using an interface that does not support MyST Markdown, it will render as a raw literal block.Many directives contain markdown inside, and if you’d like this markdown to render “normally”, you may also use ::: fences rather than ``` fences to define the directive. As a result, the contents of the directive will be rendered as markdown.

For example:

Note

This text is standardMarkdown

Similar to normal directives, these admonitions can also be nested:

Important

Note

You can use this syntax for any kind of directive, though it is generally recommended to use only with directives that contain pure markdown in their content.

Insert code cell outputs into admonitions¶

If you’d like to insert the outputs of running code inside admonitionblocks, we recommend using glue functionality.For example, we’ll insert one of the outputs that was glued into the book from the code outputs page.

The code below:

generates:

Note

Here’s my figure:

See Insert code outputs into page content for more information on how to use glue to insert your outputs directly into your content.

Tip

To hide code input and output that generated the variable you are inserting, use the remove_cell tag.See Hide or remove content for more information and other tag options.

HTML admonitions¶

A drawback of admonition syntax is that it will not render in interfaces that do not support this syntax (e.g., GitHub). If you’d like to use admonitions that are defined purely with HTML, MyST can parse them via the html_admonitions extension. To use it, first enable it with the following configuration:

Then, you may define admonitions in your book like so:

See HTML Admonitions for more information about HTML admonitions.

Panels¶

Panels provide an easy way for you to organize chunks of content into flexible containers on your page.They are useful for creating card-like layouts, flexible columns, and grids.Panels are based off of Bootstrap CSS, and utilize Bootstrap’s classes to control the look and feel of panels.

Here is an example that creates two panels:

  • --- separates each panel

  • ^^^ defines the panel header

  • +++ defines the panel footer

Note

Panel headers and footers are optional.If you don’t include ^^^ or +++ in your panel, they will not show up.

Jupyter notebook markdown image size

You can embed all kinds of content inside of panels. For example, the following panels:

were created with:

See also

See the Sphinx Panels card layout documentation for more information.

Controlling the look and feel of panels¶

You can control the look and feel of panels by passing attaching bootstrap classes to panel headers/body/footers.You do this by passing configuration options to your {panels} directive.

For example:

See also

See the Panels card styling documentation for more information.

For example, you can control how many columns are in your panels by using Bootstrap column classes. Sony alpha shutter count tool. These panels:

Body A

Body B

Body C

Were created by this code:

Dropdowns¶

Dropdowns allows you to hide content behind a title and a button.There are two kinds of dropdowns in Jupyter Book:

The {dropdown} directive¶

Use the {dropdown} directive to create a clickable dropdown with a title.

For example:

Here’s my dropdown

Dropdown admonitions¶

You can also hide the body of your admonition blocks so that users must click a button to reveal their content.This is helpful if you’d like to include some text that isn’t immediately visible to the user.

To turn an admonition into a dropdown, add the dropdown class to them. For example:

You can use this in conjunction with {admonition} directives to include yourown titles and stylings. For example:

Important

Admonition dropdowns require JavaScript to be enabled on the browser which they are viewed.By contrast, the dropdown directive below works purely via HTML+CSS.

Definition lists¶

Definition lists are enabled by defining the following setting in your _config.yml:

How to do markdown in jupyter notebook

Definition lists utilise the markdown-it-py deflist plugin, which itself is based on the Pandoc definition list specification.

Here’s an example:

Term 1

Definition

Term 2

Definition

From the Pandoc documentation:

Each term must fit on one line, which may optionally be followed by a blank line, and must be followed by one or more definitions.A definition begins with a colon or tilde, which may be indented one or two spaces.

A term may have multiple definitions, and each definition may consist of one or more block elements (paragraphs, code blocks, lists, etc.)

Here is a more complex example, demonstrating some of these features:

Term with Markdown

Definition with reference

A second paragraph

A second definition

Term 2

Definition 2a

Definition 2b

Term 3

A quote

A final definition, that can even include images:

This was created with the following Markdown:

Quotations and epigraphs¶

Quotations and epigraphs provide ways to highlight information given by others.

Quotations¶

Regular quotations are controlled with standard Markdown syntax, i.e., byinserting a caret (>) symbol in front of one or more lines of text. For example:

Epigraphs¶

Epigraphs draw more attention to a quote and highlight its author. You shouldkeep these relatively short so that they don’t take up too much vertical space. Here’show an epigraph looks:

You can provide an attribution to an epigraph by adding -- to the final line, followed by the quote author. For example:

Glossaries¶

Glossaries allow you to define terms in a glossary so you can then link back to itthroughout your content. You can create a glossary with the followingsyntax:

which creates:

Term one¶

An indented explanation of term 1

A second term¶

An indented explanation of term2

To reference terms in your glossary, use the {term} role. For example,{term}`Termone` becomes Term one and {term}`Asecondterm`becomes A second term.

Tabbed content¶

You can also use sphinx-panels to produce tabbed content.This allows you to display a variety of tabbed content blocks that users can click on.

For example, here’s a group of tabs showing off code in a few different languages:

You can use this functionality with the {tabbed} directive. You can provide a sequence of {tabbed} directives, and each one will be used to generate a new tab (unless the :new-group: option is added to a {tabbed} directive.)

For example, the following code:

produces

My second tab with somecode!

Insert code outputs in your tabs with the glue functionality.

For example, the following tabs use this functionality to glue images and tables generated somewhere else in these docs:

Fig. 1 This is a caption, with an embedded {glue:text} element: 3.00!

firstsecondthird
02.8642793.0961703.040294
12.8505203.5829232.632284
23.1826123.0267273.013184
33.1597712.7932573.151598
43.0870323.1590383.132074

Fig. 2 A caption for a pandas table.

See the sphinx-panels tabbed documentation for more information on how to use this.

Substitutions and variables in markdown¶

Substitutions allow you to define variables in the front-matter of your page, and then insert those variables into your content throughout.

To use a substitution, first add front-matter content to the top of a page like so:

You can use these substitutions inline or as blocks, and you can even nest substitutions in other substitutions (but circular references are prohibited):

Inline: I’m a substitution

Block level:

You can also insert substitutions inside of other markdown structures like tables:

col1

col2

See also

For more information about Substitutions, see Substitutions (with Jinja2).

Define substitutions for your whole book¶

You can also define book-level substitution variables with the following configuration:

These substitutions will be available throughout your book. For example, the global substitution key my-global-substitution is defined in this book’s _config.yml file, and it produces: My global value!.

Formatting substitutions¶

MyST substitutions use Jinja templates in order to substite in key / values. This means that you can apply any standard Jinja formatting to your substitutions. For example, you can replace text in your substitutions like so:

The original key1: I’m a substitution

I’m the best substitution

Using substitutions in links¶

If you’d like to use substitutions to insert and modify links in your book, here are two options to explore:

  1. Define the entire markdown link as a variable. For example:

    Here’s my link: my repo url

  2. Use Jinja features to insert the variable.Because substitutions use Jinja templates, you also have access to Python formatting operations in your substitution.For example:

    Here’s my link: my repo: jupyter-book

Citations and cross-references¶

You can add citations and cross-references to your book. SeeCitations and bibliographies for more information on how to do this.

Figures¶

You can thoroughly customise the look of figures in your book. See Images and figures formore information.

Page layout and sidebar content¶

You can also use MyST to control various aspects of the page layout. For moreinformation on this, see Control the page layout.

Footnotes¶

You can include footnotes in your book using standard Markdown syntax.This will include a numbered reference to the footnote in-line, and append the footnoteto a list of footnotes at the bottom of the page.

Jupiter Notebook Variable In Markdown Code

To create a footnote, first insert a reference in-line with this syntax: [^mylabel].Then, define the text for that label like so:

You can define [^mylabel] anywhere in the page, though its definition will alwaysbe placed at the bottom of your built page. For example, here’s a footnote 1and here’s another one 2. You can click either of them to see the footnotesat the bottom of this page.

Custom <div> blocks¶

You can add custom div blocks along with whatever classes you’d like usingthe {div} directive. The {div} directive will wrap everything inside in a single <div> with the classes you provide. For example:

Will result in the following HTML when your book is built:

Jupyter Notebook Python Variable In Markdown

This can be useful if you’d like to style your book with custom CSS or JavaScript.

1

Here’s the text of my first note.

2

And the text of my second note.Note thatyou can include Markdown footnote definitions.