IPySlides 5.8.97 Documentation

Creating slides with IPySlides

Abdul Saboor¹

Aug 01, 2025

¹My University is somewhere in the middle of nowhere

Introduction
Adding Slides and Content
Layout and Theme Settings
Useful Functions for Rich Content
Loading from File/Exporting to HTML
Advanced Functionality
Presentation Code

This is summary of current section

Oh we can use inline columns

Column A

Column B

here and what not!

Markdown

        section`Introduction` 
```multicol .block-green
toc[True]`## Table of contents`
+++
### This is summary of current section
Oh we can use inline columns stack`Column A || Column B` here and what not!
%{btn}
```
        

Main App

Slides(extensions=[], **settings)

Interactive Slides in IPython Notebook. Only one instance can exist. settings are passed to Slides.settings() if you like to set during initialization. You can also edit file .ipyslides-assets/settings.json to make settings persistent across sessions and load/sync them via GUI in sidepanel.

To suppress unwanted print from other libraries/functions, use:

Python

        with slides.suppress_stdout():
    some_function_that_prints() # This will not be printed
    print('This will not be printed either')
    display('Something') # This will be printed
        

The traitlets callables under settings returns settings back to enable chaining without extra typing, like Slides.settings.logo().layout()... .

Use Slides.instance() class method to keep older settings. Slides() apply default settings every time.
Run slides.demo() to see a demo of some features.
Run slides.docs() to see documentation.
Instructions in left settings panel are always on your fingertips.
Creating slides in a batch using Slides.create is much faster than adding them one by one.
In JupyterLab, right click on the slides and select Create New View for Output for optimized display.
To jump to source cell and back to slides by clicking buttons, set Windowing mode in Notebook settings to defer or none.
See Slides.xmd_syntax for extended markdown syntax, especially variables formatting.
Inside python scripts or for encapsulation, use Slides.fmt to pick variables from local scope.

Slides can be indexed same way as list for sorted final indices. For indexing slides with given number, use comma as Slides[number,] -> Slide or access many via list as Slides[[n1,n2,..]] -> tuple[Slide]. Use indexing with given number to apply persistent effects such as CSS.

Jump between slides

Slides.link(label, back_label=None, icon=None, back_icon=None)

Create a link to jump to another slide. Use label for link text and back_label for the optional text on the target slide if need to jump back.

Use link.origin to create a link to jump to target slide where link.target is placed.
If back_label was provided, link.target will be able to jump back to the link.origin.
In makdown, you can use created link as variables like %{link.origin} and %{link.target} to display links.
Use similar links in markdown as `` and ``.
In markdown, icons can be passed in label as "fa`arrow` label text".

Skip to dynamic content

Python

        skipper = self.link('Skip to dynamic content', 'Back to link info', icon='arrow', back_icon='arrowl')
skipper.origin.display() # skipper.target is set later somewhere, can do backward jump too
        

Adding Slides

Besides function below, you can add slides with %%slide number [-m] magic as well.

Slides.build(slide_number, /, content=None)

Build slides with a single unified command in three ways:

slides.build(number, callable) to create a slide from a callable(slide) immediately, e.g. lambda s: slides.write(1,2,3) or as a decorator.
- Docstring of callable (if any) is parsed as markdown before calling function.
with slides.build(number): creates single slide. Equivalent to %%slide number magic.
- Use fsep() from top import or Slides.fsep() to split content into frames.
- Use for item in fsep.iter(iterable): block to automatically add frame separator.
- Use fsep(True) / fsep.iter(...,stack=True) to join content of frames incrementally.
slides.build(number, str | fmt) creates many slides with markdown content. Equivalent to %%slide number -m magic in case of one slide.
- Frames separator is double dashes -- and slides separator is triple dashes ---. Same applies to Slides.sync_with_file too.
- Use %++ to join content of frames incrementally.
- Markdown multicol before -- creates incremental columns if %++ is provided.
- See slides.xmd_syntax for extended markdown usage.
- To debug markdown content, use EOF on its own line to keep editing and clearing errors. Same applies to Slides.sync_with_file too.
- In case of str input, varaiables such as %{var} can be updated by creating/updating var in notebook.
- In case of fmt(str, **kwargs), varaiables are picked from kwargs or local scope and can't be changed later. Useful in python scripts.

In all cases, number could be used as -1.
Use yoffetinteger in px in markdown or Slides.this.yoffset(integer) to make all frames align vertically to avoid jumps in increments.
You can use build_(...) (with underscore at end) in python file instead of build(-1,...).

Slides.sync_with_file(start_slide_number, /, path, interval=500)

Auto update slides when content of markdown file changes. You can stop syncing using Slides.unsync function. interval is in milliseconds, 500 ms default. Read Slides.build docs about content of file.

The variables inserted in file content are used from top scope.

You can add files inside linked file using include\`file_path.md\` syntax, which are also watched for changes. This helps modularity of content, and even you can link a citation file in markdown format as shown below. Read more in Slides.xmd_syntax about it.

Markdown

        ```citations footnote
@key1: Saboor et. al., 2025
@key2: A citations can span multiple lines, but key should start on new line
<!-- Or put this content in a file 'bib.md' and then inside citations block use include`bib.md` -->
```
        

To debug the linked file or included file, use EOF on its own line to keep editing and clearing errors.

Important Methods on Slide

Use slide handle or Slides[number,] to apply these methods becuase index can change on new builds.

Slide.yoffset(value)

Set yoffset (in percent) for frames to have equal height in incremental content. Set global yoffset in layout settings.

Slide.set_animation(this=None, main=None, frame=None)

Set animation of this slide. Provide None if need to stop animation. Use main and frame to set animation to all slides.

Slide.set_bg_image(src=None, opacity=1, filter=None, contain=False)

Adds background image to this slide. src can be a url or a local image path or an svg str. filter is a CSS filter like blur(5px), grayscale() etc.

This function enables you to add a slide purely with an image, possibly with opacity=1 and contain = True.

Slide.update_display(go_there=True)

Update display of this slides including reloading citations, widgets etc.

Slide.get_source(name=None, height='400px', **kwargs)

Return source code of this slide, markdwon or python or None if no source exists. kwargs are passed to Slides.code.from_string.

Slide.show()

Show this slide in cell.

Slide.set_css(this: dict = None, overall: dict = None)

Attributes at the root level of the dictionary are only picked if they are related to background. Each call will reset previous call if props given explicitly, otherwise not.

See Slides.css_syntax for information on how to write CSS dictionary.
Unlike slides.html('style',props), you can set CSS variables at top level here including theme variables --fg[1,2,3]-color ,--bg[1,2,3]-color and --[accent, pointer]-color to tweek appearance of individual or all slides.

CSS is formatted using a props nested dictionary to simplify the process. There are few special rules in props:

All nested selectors are joined with space, so '.A': {'.B': ... } becomes .A .B {...} in CSS.
A '^' in start of a selector joins to parent selector without space, so '.A': {'^:hover': ...} becomes .A:hover {...} in CSS. You can also use '.A:hover' directly but it will restrict other nested keys to hover only.
A list/tuple of values for a key in dict generates CSS fallback, so '.A': {'font-size': ('20px','2em')} becomes .A {font-size: 20px; font-size: 2em;} in CSS.

Read about specificity of CSS selectors here.

Python

        props = {
  ".A": {
    "z-index": "2",
    ".B": {
      "font-size": [
        "24px",
        "2em"
      ],
      "^:hover": {
        "opacity": "1"
      }
    },
    "> h1": {
      "padding": "0",
      "@media screen and (min-width: 650px)": {
        "padding": "2em"
      }
    },
    ".C p": {
      "font-size": "14px"
    }
  },
  ".D": {
    "transform": "translate(-2px,1px)",
    "^, h1": {
      "background": "red",
      "span, i": {
        "color": "whitemoke",
        "@keyframes animation-name": {
          "from": {
            "opacity": 0
          },
          "to": {
            "opacity": 1
          }
        }
      }
    }
  }
}
        

Output of html('style',props), set_css(props) etc. functions. Top selector would be different based on where it is called.

CSS

        <style>
.SlideArea .A {
    z-index : 2;
}
.SlideArea .A .B {
    font-size : 24px;
    font-size : 2em;
}
.SlideArea .A .B:hover {
    opacity : 1;
}
.SlideArea .A > h1 {
    padding : 0;
}
@media screen and (min-width: 650px) {
    .SlideArea .A > h1 {
        padding : 2em;
    }
}
.SlideArea .A .C p {
    font-size : 14px;
}
.SlideArea .D {
    transform : translate(-2px,1px);
}
.SlideArea .D,
.SlideArea .D  h1 {
    background : red;
}
.SlideArea .D span,
.SlideArea .D  i,
.SlideArea .D h1 span,
.SlideArea .D h1  i {
    color : whitemoke;
}
@keyframes animation-name {
    from {
        opacity : 0;
    }
    to {
        opacity : 1;
    }
}
</style>
        

Extended Markdown

Extended syntax on top of Python-Markdown supports almost full presentation from Markdown.

Presentation Structure

Slides & Frames Separators

Triple dashes --- is used to split text in slides inside markdown content of Slides.build function or markdown file. Double dashes -- is used to split text in frames. Alongwith this `` can be used to increment text on framed slide.

Sections & TOC

section`content` to add a section that will appear in the table of contents. toc`Table of content header text` to add a table of contents. See Slides.docs() for creating a TOC accompanied by section summary.

Notes

notes`This is slide notes` to add notes to current slide.

Including Files

include`markdown_file.md[optional list slicing to pick lines from file such as [2:5], [10:]]` to include a file in markdown format. These files are watched for edits if included in synced markdown file via Slides.sync_with_file.

Citations

cite`key1,key2` / @key1,@key2 to add citation to current slide. citations are automatically added in suitable place and should be set once using Slides.set_citations function (or see below).
With citations mode set as 'footnote', you can add refs`ncol_refs` or Slides.refs to add citations anywhere on slide. If ncol_refs is not given, it will be picked from layout settings.
Force a citation to be shown inline by appending a ! even in footnote mode, such as @key! or cite`key1,key2!`.
In the synced markdown file (also its included files) through Slides.sync_with_file, you can add citations with block sytnax:
::: citations [inline or footnote]
@key1: Saboor et. al., 2025
@key2: A citations can span multiple lines, but key should start on new line

Extended Markdown

Content Blocks

The general block syntax is ::: type-or-classes [args] attributes.

You can use / to divide css properties from node attributes such as ::: note-info border="1px solid red" / id="mynote" dir="ltr". Node attributes come after /.
You can create inline blocks by adding | in header (only takes effect if body is empty), such as ::: block-red | text will create a block with red background and text inside.
Both | and / can be escaped in header by backslah to interpret them as literal characters instead of block body and attributes splitters respectively.
You can optionally continue block header on next multiple adjacent lines with : at start of each line. This multiline header is not available in ``` blocks.
Theme colors such as fg1=red bg2=black upto 3, can be assigned for each block to tweak look and feel of content.
Blocks can be escaped by having a space before ::: at start of line, such as ::: block-red will not be parsed as block.
Some block levels HTML tags are handled specially, such as p, pre, ul, ol, blockquote, details, summary, table.
You can use ::: block nested inside ``` block at same indentation level but otherwise must be correctly indented.

This table, itself created with a `::: table` block, lists common block types and their usage. Each of these blocks can have additional CSS classes and properties, besides the limited set shown below.
Block Syntax	Description
`::: raw/pre`	Raw text or preformatted text, no markdown parsing. Use `raw` or `pre` as first word in block.
`::: code`	Code block with syntax highlighting, parameters are passed to highlight function.
`::: tag or classes`	tags are block level elements such as `p`, `details`, `summary`, `table`, `center`, etc.
`::: columns/multicol [widths]`	Create columns with relative widths, e.g. `columns 4 6` for 40% and 60% width. Use `+++` separator to reveal content incrementally/make display columns.
`::: md-[pos]`	Parse markdown in the block, with showing source code at `pos=[before,after,left,right]`. Add `-c` to collapse code and show on click.
`::: table [col widths]`	Create a table with optional column widths, e.g. `::: table 1 2` for 33% and 66% width. Use `caption-side=top/bottom` to place caption on top/bottom.
`::: citations [inline or footnote]`	Add citations in the block, with `inline` or `footnote` mode. Use `@key: value` syntax to add citations in block.

Extended Markdown

Layouts

Inline Columns: Inline columns/rows can be added by using stack`Column A || Column B` sytnax. You can escape pipe | with | to use it as text inside stack. See at end how to nest such stacking.
Block Columns: You can create columns using ::: columns or ::: multicol syntax. Column separator is triple plus +++ if intended in display mode.

Markdown

        ::: columns 6 1 4 block-blue 
: border="1px dashed red"
    ::: block-red
        - `::: columns/muticol` with a +++ separator act like `write` command and reveal content incrementally when `` is used
        - children inside `columns` picks relative width from parent's `columns` block evem if '+++' is not used.
          In thise children should be visually blocks themselves like headings, paragraphs, lists etc or wrapped in `::: block` to make them obvious blocks like this one.
        - CSS classes and attributes can be used to style columns besides relative widths.

    ::: block-blue border="1px solid red" | alert`inline` color`block` text 

    ::: block-yellow border="2px solid orange" padding="10px"
        - Top level `columns` is necessary to create columns or use simple block with `display=flex`.
        and frame speactor is used at end of block.
        - Indentation is important, so use tabs or spaces consistently.
        

::: columns/muticol with a +++ separator act like write command and reveal content incrementally when `` is used
children inside columns picks relative width from parent's columns block evem if '+++' is not used. In thise children should be visually blocks themselves like headings, paragraphs, lists etc or wrapped in ::: block to make them obvious blocks like this one.
CSS classes and attributes can be used to style columns besides relative widths.

inline block text

Top level columns is necessary to create columns or use simple block with display=flex. and frame speactor is used at end of block.
Indentation is important, so use tabs or spaces consistently.

Extended Markdown

Code Display

Inline Code: Inline code can be highlighted using hl`code` syntax, e.g. hl`print('Hello')` → print('Hello').
Code Blocks: Use standard markdown fenced code blocks or ::: code blocks for syntax highlighting.

Markdown

        ```python
print('Hello, I was highlighted from a code block!')
```

::: code language=bash name=Shell lineno=False style=vim
    echo "Hello, I was highlighted from a code block!"
    ls -l | grep ".py" | wc -l
        

Python

        print('Hello, I was highlighted from a code block!')
        

Shell

        echo "Hello, I was highlighted from a code block!"
ls -l | grep ".py" | wc -l
        

In ::: code block, you need to set parameters that are passed to highlight function, such as language, name, lineno, css_class, etc.
The ``` code block does not support parameters for highligh function, but support attributes.

Extended Markdown

Variables Substitution

Variables from Python code can be embedded directly into Markdown.

Basic Usage

Syntax: Use %{variable} to display a variable. Legacy `{variable}` is also supported.
Formatting: Apply formatting using %{variable:format_spec} or conversions with %{variable!conversion}. This works like Python's str.format method.
Notebook Display: To render an object as it would appear in a notebook output cell, use %{variable:nb}. This is useful for complex objects like plots.
For custom objects, it's better to use Slides.serializer to define their HTML representation, which allows them to be displayed correctly in place with such as %{fig}. Using %{fig:nb} might show the object at the end of the slide.

Variable Scope & Updates

Live Updates: Variables are automatically updated in your slides when their values change in the notebook.
Scope Resolution: Variables are resolved from the global scope. To use variables from a local scope (e.g., inside a function), wrap your markdown content in Slides.fmt(content, **kwargs).
Forcing Updates: You can force a refresh of variables on a specific slide using Slide[number,].rebuild(**kwargs). This is also useful for setting unique variable values on different slides.
Attribute/Index Access: When using expressions like %{var.attr} or %{var['key']}, the output will only update if the base variable var itself is reassigned.

Important Notes

Use unique variable names for each slide to prevent unintended updates.
Widgets and objects using :nb are only displayed correctly in the first level of nested blocks.
The %{variable:nb} formatter can sometimes disrupt the document flow if used inside elements like headings. It's safest to use it on its own line or within a paragraph.
Widgets behave same with or without :nb format spec.
Formatting is done using str.format method, so f-string like literal expressions are not supported.

Extended Markdown

Inline Python Functions

Functions (that can also take extra args [python code as strings] as func[arg1,x=2,y=A]`arg0`) include:

vspace`number in units of em`
hspace`number in units of em`
line`length in units of em, [color, width and style]`
today`format_spec like %b-%d-%Y`
alert`text`
color`text`
hl`inline code highlight. Accepts langauge as keywoard.`
textbox`text`
image`path/src or clip:filename`
raw`text, or use ::: raw block`
svg`path/src`
iframe`src`
details`text or use ::: details block`
styled`style objects with CSS classes and inline styles or use block ::: with css classes and props inline`
zoomable`zoom a block of html when hovered or used ::: zoomable block`
center`text or %{variable} or use ::: center, ::: align-center blocks`
stack`text separated by || in inline mode, or use ::: columns block`

Upto 4 level nesting is parsed in inline functions using (level + 1) number of / (at least two) within backticks in functions given below.

Markdown

        stack[(6,4),css_class="block-blue"]`////
    This always parse markdown in `returns=True` mode. ||
    stack[css_class="info"]`/// B ||
        color["skyblue"]`//alert`Alerted Text` Colored Text //`
    ///` 
////`
        

This always parse markdown in returns=True mode.

Alerted Text Colored Text

Extended Markdown

General Syntax

Use include`markdown_file.md[optional list slicing to pick lines from file such as [2:5], [10:]]` to include a file in markdown format.
Use fa`icon_name` to add FontAwesome icons, e.g. fa`arrow-right` → , fa`check` → , fa`info-circle` → etc.
Use syntax `` and `` to jump between slides. See Slides.link for more details.
Cells in markdown table can be spanned to multiple rows/columns by attributes | cell text \{: rowspan="2" colspan="1"}| inside a cell, should be a space bewteen text and attributes.
Escape a backtick with \, i.e. \\` → `, other escape characters include @, %, /, |. In Python >=3.12, you need to make escape strings raw, including the use of $ \LaTeX $ and re module.
Use _`sub` and ^`sup` for subscript and superscript respectively, e.g. H₂O, E = mc².
Definition list syntax:

Markdown

        Item 1 Header
: Item 1 details ^`1`
Item 1 Header
: Item 1 details _`2`
        

Item 1 Header

Item 1 details¹
Item 1 Header: Item 1 details₂

Extending Syntax

You can use Slides.extender to extend additional syntax using Markdown extensions such as markdown extensions and PyMdown-Extensions.
These markdown extensions are inluded by default ['tables', 'footnotes', 'attr_list', 'md_in_html', 'def_list'].
You can serialize custom python objects to HTML using Slides.serializer function. Having a __format__ method in your class enables to use {obj} syntax in python formatting and %{obj} in extended Markdown.

Adding Content

Besides functions below, you can add content to slides with %%xmd,%xmd as well.

Slides.write(*objs, widths=None, css_class=None)

Write objs to slides in columns. To create rows in a column, wrap objects in a list or tuple.
You can optionally specify widths as a list of percentages for each column. css_class can have multiple classes separated by space, works only for multiple columns.

Write any object that can be displayed in a cell with some additional features:

Strings will be parsed as as extended markdown that can have citations/python code blocks/Javascript etc.
Display another function to capture its output in order using Slides.hold(func,...). Only body of the function will be displayed/printed. Return value will be ignored.
Dispaly IPython widgets such as ipywidgets or ipyvolume by passing them directly.
Display Axes/Figure form libraries such as matplotlib, plotly altair, bokeh etc. by passing them directly.
Display source code of functions/classes/modules or other languages by passing them directly or using Slides.code API.
Use Slides.alt function to display obj/widget on slides and alternative content/screenshot of widgets in exported slides.
ipywidgets.[HTML, Output, Box] and their subclasses will be displayed as Slides.alt(html_converter_func, widget). The value of exported HTML will be most recent.
Other options include but not limited to:
- Output of functions in ipyslides.utils module that are also linked to Slides object.
- PIL images, SVGs etc.
- IPython display objects such as Image, SVG, HTML, Audio, Video, YouTubeVideo, IFrame, Latex, Markdown, JSON, Javascript, etc.
- Any object that has a `_repr_html_{method, you can create one for your own objects/third party objects by:
  Slides.serializerAPI. IPython'sdisplay` automatically takes care of such objects on export to html.
  IPython.core.formatters API for third party libraries.}

Use Slides.frozen to avoid display formatting and markdown parsing over objects in write and for some kind of objects in display too.
write is a robust command that can handle most of the cases. If nothing works, repr(obj) will be displayed.
You can avoid repr(obj) by Slides.hold(func, ...) e.g. Slides.hold(plt.show). This can also be used to delay display until it is captured in a column.
You can use display(obj, metadata = {'text/html': 'html repr by user'}) for any object to display object as it is and export its HTML representation in metadata.
A single string passed to write is equivalent to parse command.
You can add mini columns inside a column by markdown syntax or Slides.stack, but content type is limited in that case.
In markdown multicol/columns block syntax is similar to write command if +++ separartor is used there.

Slides.parse(xmd, returns=False)

Parse extended markdown and display immediately. If you need output html, use returns = True but that won't display variables.

Example

Markdown

        # Normal Markdown
```multicol 40 60
# First column is 40% width
If 40 60 was not given, all columns will be of equal width, this paragraph will be inside info block due to class at bottom
{.info}
+++
# Second column is 60% wide
This \%{var_name} (or legacy \`{var_name}\`) can be substituted with `fmt` function or from notebook if whole slide is built with markdown.
```

```python
# This will not be executed, only shown
```
stack`Inline-column A || Inline-column B`
        

Each block can have class names (speparated with space or .) after all other options such as python .friendly or multicol .Sucess.info.
- For example, python .friendly will be highlighted with friendly theme from pygments.
- Pygments themes, however, are not supported with multicol.
- You need to write and display CSS for a custom class.
The block with ::: class_type syntax accepts extra classes in quotes, for example ::: multicol "Success" "info".
There are special CSS classes jupyter-only and export-only that control appearance of content in different modes.

Nested blocks are supported via indentation in md-[before,after,left,right] and multicol, but may be broken in display contexts.

Find special syntax to be used in markdown by Slides.xmd_syntax.
Use Slides.extender or ipyslides.xmd.extender to add markdown extensions.

Slides.as_html(obj)

Convert supported (almost any) obj to html format.

Slides.html(tag, children=None, css_class=None, **node_attrs)

Returns html node with given children and node attributes like style, id etc. If an ttribute needs '-' in its name, replace it with '_'.
tag can be any valid html tag name. A tag that ends with / will be self closing e.g. hr/ will be <hr/>. Empty tag gives unwrapped children. children expects:

If None, returns node such as 'image' -> and 'image/' ->
str: A string to be added as node's text content.
list/tuple of [objects]: A list of objects that will be parsed and added as child nodes. Widgets are not supported.
dict if tag is 'style', this will only be exported to HTML if called under slide builder, use slides[number,].set_css otherwise. See Slides.css_syntax to learn about requirements of styles in dict.

Example:

Python

        html('img',src='ir_uv.jpg') #Returns IPython.display.HTML("<img src='ir_uv.jpg'></img>") and displas image if last line in notebook's cell.
        

To keep an image persistently embeded, use ipyslides.utils.imge function instead of just an html tag.

Adding Speaker Notes

You can use alert

notes`notes content`in markdown.

This is experimental feature, and may not work as expected.

Slides.notes.display()

Slides.notes.insert(content)

Add notes to current slide. Content could be any object except javascript and interactive widgets.

In markdown, you can use notes`notes content`.

Displaying Source Code

In markdown, the block md-[before,after,left,right] [-c] parses and displays source as well.

Slides.code.cast

(obj, language='python', name=None, css_class=None, style='default', color=None, background=None, hover_color='var(--bg3-color)', lineno=True, height='400px')

Highlight code (any python object that has a source or str of code) with given language and style.

style only works if css_class is given.
If css_class is given and matches any of pygments.styles.get_all_styles(), then style will be applied immediately.
color is used for text color as some themes dont provide text color.
CSS properties like color and background are applied if css_class is provided.
height is max-height of code block, it does not expand more than code itself.
If obj is a file-like object, it's read method will be accessed to get source code.

If you want plain inline syntax highlighting, use Slides.hl.

Slides.code.context(returns=False, **kwargs)

Execute and displays source code in the context manager. kwargs are passed to Slides.highlight function. Useful when source is written inside context manager itself. If returns is False (by default), then source is displayed before the output of code. Otherwise you can assign the source to a variable and display it later anywhere.

Usage:

Python

        with source.context(returns = True) as s: 
    do_something()
    write(s) # or s.display(), write(s)

#s.raw, s.value are accesible attributes.
#s.focus_lines, s.show_lines are methods that are used to show selective lines.
        

Slides.code.from_file(file, language=None, name=None, **kwargs)

Returns source object with show_lines and focus_lines methods. name is alternate used name for language.
kwargs are passed to Slides.highlight.

It tries to auto detect lanaguage from filename extension, if language is not given.

Slides.code.from_source(obj, **kwargs)

Returns source code from a given obj [class,function,module,method etc.] with show_lines and focus_lines methods. kwargs are passed to Slides.highlight

Slides.code.from_string(text, language='python', name=None, **kwargs)

Creates source object from string. name is alternate used name for language. kwargs are passed to Slides.highlight.

Introduction
Adding Slides and Content
Layout and Theme Settings
Useful Functions for Rich Content
Loading from File/Exporting to HTML
Advanced Functionality
Presentation Code

Layout and Theme Settings

Slides.Settings

Apply settings to slides programatically. Fewer settings are available as widgets.

Settings can be nested or individual attributes as set as well. For example:

Python

        Slides.settings(layout = {"aspect": 16/10}) # Top 
Slides.settings.layout(aspect = 16/10) # Individual
Slides.settings.layout.aspect = 16/10  # Attribute
        

All settings calls including top level returns settings instance to apply method chaining. e.g. Slides.settings.layout(aspect = 16/10).footer(text="ABC").logo(...).

Slides.Settings.Code

Set code block styles. background and color may be needed for some styles.

Slides.Settings.dump(path)

Dump the settings state to a json file. Use it once you have finalized a settings setup of slides.

Slides.Settings.Fonts

Set fonts of text and code and size.

Slides.Settings.Footer

Set footer attributes of slides.

Slides.Settings.Layout

Set layout of slides.

Slides.Settings.load(path)

Load settings from a json file. You may need to dump settings and then edit for correct usage.

Slides.Settings.Logo

Set logo for all slides. left and bottom take precedence over right and top respectively.

Slides.Settings.Theme

Set theme value. colors and code have their own nested traits.

Slides.Settings.Toggle

Toggle ON/OFF checks in settings panel.

Useful Functions for Rich Content

Slides.alt(exportable_data, obj)

Display obj for slides and output of exportable_data will be and displayed only in exported formats as HTML.

exportable_data should be an html str or a callable to receive obj as its only argument.
- A callable will give the latest representation of widget in exported slides and runtime representation of any other obj.
- An html str, it will export the runtime representation of obj.

Python

        import ipywidgets as ipw
slides.alt(lambda w: f'<input type="range" min="{w.min}" max="{w.max}" value="{w.value}">', ipw.IntSlider()).display()
        

If you happen to be using alt many times for same type, you can use Slides.serializer.register and then pass that type of widget without alt.
ipywidgets's HTML, Box and Output widgets and their subclasses directly give html representation if used inside write command.

Slides.AnimationSlider

(*, continuous_update=<traitlets.traitlets.Bool object at 0x000002A202AB5880>, cyclic=<traitlets.traitlets.Bool object at 0x000002A202AB58B0>, description=<traitlets.traitlets.Unicode object at 0x000002A202AB5760>, interval=<traitlets.traitlets.Float object at 0x000002A202AB5820>, loop=<traitlets.traitlets.Bool object at 0x000002A202AB57C0>, nframes=<traitlets.traitlets.CInt object at 0x000002A202AB57F0>, playing=<traitlets.traitlets.Bool object at 0x000002A202AB5850>, value=<traitlets.traitlets.CInt object at 0x000002A202AB5790>, **kwargs)

This is a simple slider widget that can be used to control the animation with an observer function.

You need to provide parameters like nframes and interval (milliseconds) to control the animation. The value trait can be observed to get the current frame index. The cyclic trait can be set to True to make the animation cyclic and only works when loop mode is ON.

Python

        from plotly.graph_objects import FigureWidget

fig = FigureWidget()
fig.add_scatter(y=[1, 2, 3, 4, 5])
widget = slides.AnimationSlider() # assuming slides is the instance of Slides app

def on_change(change):
    value = change['new']
    fig.data[0].color = f'rgb({int(value/widget.nframes*100)}, 100, 100)' # change color based on frame index

widget.observe(on_change, names='value')
display(widget, fig) # display it in the notebook
        

This widget can be passed to ipywidgets.interactive as keyword argument to create a dynamic control for the animation.

Python

        from ipywidgets import interact

@interact(frame=widget)
def show_frame(frame):
    print(frame)
        

Slides.alert(text)

Alerts text!

Slides.block(*objs, widths=None)

Format a block like in LATEX beamer with objs in columns and immediately display it. Format rows by given an obj as list of objects.

Block is automatically displayed and returns nothing.
Available functions include: block_<red,green,blue,yellow,cyan,magenta,gray>.
You can create blocks just by CSS classes in markdown as {.block}, {.block-red}, {.block-green}, etc.
See documentation of write command for details of objs and widths.

Slides.bokeh2html(bokeh_fig, title='')

Write bokeh figure as HTML string to use in ipyslide.utils.write. Parameters

bokeh_fig : Bokeh figure instance.
title : Title for figure.

Slides.bullets(iterable, ordered=False, marker=None, css_class=None)

A powerful bullet list. iterable could be list of anything that you can pass to write command.
marker could be a unicode charcter or string, only effects unordered list.

Slides.color(text, fg='var(--accent-color, blue)', bg=None)

Colors text, fg and bg should be valid CSS colors

Slides.details(obj, summary='Click to show content')

Show/Hide Content in collapsed html.

Slides.doc(obj, prepend_str=None, members=None, itself=True)

Returns documentation of an obj. You can prepend a class/module name. members is True/List of attributes to show doc of.

Slides.error(name, msg)

Add error without breaking execution.

Slides.fmt(*args, **kwargs)

Markdown string wrapper that will be parsed with given kwargs lazily. If markdown contains variables not in kwargs, it will try to resolve them from local/global namespace and raise error if name is nowhere. Use inside python scripts when creating slides. In notebook, variables are automatically resolved, although you can still use it there.

Being as last expression of notebook cell or using self.parse() will parse markdown content.

Slides.frozen(obj, metadata=None)

Display object as it it and export metadata if not str. A frozen object may not appear in exported html if metadata is not given.

Returned object has a display method, or can be directly passed to display/write commands.

Slides.cast

(obj, language='python', name=None, css_class=None, style='default', color=None, background=None, hover_color='var(--bg3-color)', lineno=True, height='400px')

Highlight code (any python object that has a source or str of code) with given language and style.

style only works if css_class is given.
If css_class is given and matches any of pygments.styles.get_all_styles(), then style will be applied immediately.
color is used for text color as some themes dont provide text color.
CSS properties like color and background are applied if css_class is provided.
height is max-height of code block, it does not expand more than code itself.
If obj is a file-like object, it's read method will be accessed to get source code.

If you want plain inline syntax highlighting, use Slides.hl.

Slides.html(tag, children=None, css_class=None, **node_attrs)

If None, returns node such as 'image' -> and 'image/' ->
str: A string to be added as node's text content.
list/tuple of [objects]: A list of objects that will be parsed and added as child nodes. Widgets are not supported.
dict if tag is 'style', this will only be exported to HTML if called under slide builder, use slides[number,].set_css otherwise. See Slides.css_syntax to learn about requirements of styles in dict.

Example:

Python

        html('img',src='ir_uv.jpg') #Returns IPython.display.HTML("<img src='ir_uv.jpg'></img>") and displas image if last line in notebook's cell.
        

To keep an image persistently embeded, use ipyslides.utils.imge function instead of just an html tag.

Slides.iframe(src, width='100%', height='auto', **kwargs)

Display src in an iframe. kwrags are passed to IPython.display.IFrame

Slides.image(data=None, width='95%', caption=None, crop=None, css_props={}, **kwargs)

Displays PNG/JPEG files or image data etc, kwrags are passed to IPython.display.Image. crop is a tuple of (left, top, right, bottom) in percentage of image size to crop the image. css_props are applied to figure element, so you can control top layout and nested img tag. You can provide following to data parameter:

An opened PIL image. Useful for image operations and then direct writing to slides.
A file path to image file.
A url to image file.
A str/bytes object containing image data.
A str like "clip:image.png" will load an image saved in clips directory.
A filename like "image.png" will look for the file in current directory and then in Slides.clips_dir if not found. Use 'clip:image.png' to pick image from Slides.clips_dir directly if another file 'image.png' also exists in current directory.

Returns an IMG object which can be exported to other formats (if possible):

IMG.to_pil() returns PIL.Image or None.
IMG.to_numpy() returns image data as numpy array for use in plotting libraries or None.

Slides.notify(content, timeout=5)

Send inside notifications for user to know whats happened on some button click. Send 'x' in content to clear previous notification immediately.

Slides.plt2html(plt_fig=None, transparent=True, width=None, caption=None, crop=None)

Write matplotib figure as HTML string to use in ipyslide.utils.write. Parameters

plt_fig : Matplotlib's figure instance, auto picks as well.
transparent: True of False for fig background.
width : CSS style width. Default is figsize.
caption : Caption for figure.
crop : Crop SVG to given box in fraction 0-1 as tuple of (left, top, right, bottom).

Slides.raw(text, css_class=None)

Keep shape of text as it is (but apply dedent), preserving whitespaces as well.

Slides.set_dir(path)

Context manager to set working directory to given path and return to previous working directory when done.

Slides.sig(callable, prepend_str=None)

Returns signature of a callable. You can prepend a class/module name.

Slides.stack(objs, sizes=None, vertical=False, css_class=None, **css_props)

Stacks given objects in a column or row with given sizes.

objs: list/tuple of objects or a markdown string with '||' as separator.
sizes: list/tuple of sizes(int, float) for each object, if not given, all objects will have equal size.
vertical: bool, to stack objects vertically or horizontally, default is horizontal.
css_class: str, to add a class to the container div.
css_props: dict, applied to the container div, so you can control top layout.

Slides.styled(obj, css_class=None, **css_props)

Add a class to a given object, whether a widget or html/IPYthon object. CSS inline style properties should be given with names including '-' replaced with '_' but values should not. Only a subset of inline properties take effect if obj is a widget.

Objects other than widgets will be wrapped in a 'div' tag. Use html function if you need more flexibility.

Slides.suppress_output(stdout=True)

Suppress output of a block of code. If stdout is False, only display data is suppressed.

Slides.suppress_stdout()

Suppress stdout in a block of code, especially unwanted print from functions in other modules.

Slides.svg(data=None, width=None, caption=None, crop=None, css_props={}, **kwargs)

Display svg file or svg string/bytes with additional customizations. crop is a tuple of (left, top, right, bottom) in percentage of image size to crop the image. css_props are applied to figure element, so you can control top layout and nested svg tag. kwrags are passed to IPython.display.SVG. You can provide url/string/bytes/filepath for svg.

Slides.table(data, headers=None, widths=None)

Creates a table of given data like DataFrame, but with rich elements. data should be a 2D matrix-like. headers is a list of column names. widths is a list of widths for each column.

Example:

Python

        import pandas as pd
df = pd.DataFrame({'A': [1,2,3], 'B': [4,5,6]})
slides.table(df.values, headers=df.columns, widths=[1,2])

slides.table([[1,2,3],[4,5,6]], headers=['A','B','C'], widths=[1,2,3])
        

Slides.textbox(text, **css_props)

Formats text in a box for writing e.g. inline refrences. css_props are applied to box and - should be <sub> like </sub>font-size -> font_size. text is not parsed to general markdown i.e. only bold italic etc. applied, so if need markdown, parse it to html before. You can have common CSS for all textboxes using class text-box.

Slides.today(fmt='%b %d, %Y', fg='inherit')

Returns today's date in given format.

Slides.vspace(em=1)

Returns html node with given height in em.

Slides.zoomable(obj)

Wraps a given obj in a parent with 'zoom-child' class or add 'zoom-self' to widget, whether a widget or html/IPYthon object

Citations and Sections

Use syntax cite`key` / @key to add citations which should be already set by Slides.set_citations(data, mode) method. Citations are written on suitable place according to given mode. Number of columns in citations are determined by Slides.settings.layout(..., ncol_refs = int). ¹

Add sections in slides to separate content by section`text`. Corresponding table of contents can be added with toc`title`.

Slides.set_citations(data, mode='footnote')

Set citations from dictionary or string with content like @key: citation value on their own lines, key should be cited in markdown as cite`key` / @key, optionally comma separated keys. mode for citations should be one of ['inline', 'footnote']. Number of columns in citations are determined by Slides.settings.layout(..., ncol_refs=N).

Python

        set_citations({"key1":"value1","key2":"value2"})

set_citations('''
@key1: citation for key1
@key2: citation for key2
''')

with open("citations_file.md","r") as f:
    set_citations(f.read()) # same content as string above

with open("citations_file.json","r") as f:
    set_citations(json.load(f))
        

You should set citations in start if using voila or python script. Setting in start in notebook is useful as well.
Citations are replaced with new ones, so latest use of this function reprsents available citations.
Makrdown equivalent of this function is a citation block only supported in Slides.sync_with_file's context.

Citation A

Back to link info

Dynamic Content

Slides.ei.interact(*funcs: List[Callable], auto_update: bool = True, app_layout: dict = None, grid_css: dict = {}, **kwargs) -> None

Enhanced interactive widget with multiple callbacks, grid layout and fullscreen support.

This function is used for quick dashboards. Subclass InteractBase for complex applications.

Features:

Multiple function support with selective updates
CSS Grid layout system
Extended widget trait observation
Dynamic widget property updates
Built-in fullscreen support

Basic Usage:

Python

        from ipyslides.interaction import interactive, callback, monitor
import ipywidgets as ipw
import plotly.graph_objects as go

fig = go.FigureWidget()

@callback('out-plot', timeit=True)  # check execution time
def update_plot(x, y, fig):
    fig.data = []
    fig.add_scatter(x=[0, x], y=[0, y])

def resize_fig(fig, fs):
    fig.layout.autosize = False # double trigger
    fig.layout.autosize = True # plotly's figurewidget always make trouble with sizing

# Above two functions can be merged since we can use changed detection
@monitor  # check execution time
def respond(x, y, fig , fs, changed):
    if 'fs' in changed: # or changed('fs')
        fig.layout.autosize = False # double trigger
        fig.layout.autosize = True
    else:
        fig.data = []
        fig.add_scatter(x=[0, x], y=[0, y])

dashboard = interactive(
    update_plot,
    resize_fig, # responds to fullscreen change
    # respond, instead of two functions
    x = ipw.IntSlider(0, 0, 100),
    y = ipw.FloatSlider(0, 1),
    fig = ipw.fixed(fig),
    changed = '.changed', # detect a change in parameter
    fs = '.isfullscreen', # detect fullscreen change on instance itself
)
        

Parameters:

*funcs: One or more callback functions
auto_update: Update automatically on widget changes
app_layout: Initial layout configuration, see relayout() method for details
grid_css: CSS Grid properties for layout
- Use :fullscreen at root level of dict to apply styles in fullscreen mode
- Use [Button, ToggleButton(s)].add_class('content-width-button') to fix button widths easily.
- See CSS Grid Layout Guide.
**kwargs: Widget parameters

Widget Parameters:

Regular ipywidgets
Fixed widgets via ipw.fixed()
String pattern 'widget.trait' for trait observation, 'widget' must be in kwargs or '.trait' to observe traits on this instance.
You can use '.fullscreen' to detect fullscreen change and do actions based on that.
You can use changed = '.changed' to detect which parameters of a callback changed by checking changed('param') -> Bool in a callback.
Any DOM widget that needs display (inside fixed too). A widget and its observed trait in a single function are not allowed, such as f(fig, v) where v='fig.selected'.
Plotly FigureWidgets (use patched_plotly)
ipywidgets.Button for manual updates on callbacks besides global auto_update. Add tooltip for info on button when not synced.
- You can have multiple buttons in a single callback and check btn.clicked attribute to run code based on which button was clicked.

Widget Updates:

Functions can modify widget traits (e.g. options, min/max)
Order matters for dependent updates
Parameter-less functions run with any interaction
Animation widgets work even with manual updates
Output Widget Behavior:
- Output widgets are created only if a CSS class is provided via @callback.
- If no CSS class is provided, the callback will use the main output widget labeled as 'out-main'.

CSS Classes:

Parameter names from kwargs
Custom 'out-*' classes from @callback, and 'out-main' class.
'btn-main' for manual update button

Notes:

Avoid modifying global slide state
Use widget descriptions to prevent name clashes
See set_css() method for styling options
interactive(no_args_func,) is perfectly valid and run on button click to do something like fetch latest data from somewhere.

Python dictionary to CSS

CSS is formatted using a props nested dictionary to simplify the process. There are few special rules in props:

All nested selectors are joined with space, so '.A': {'.B': ... } becomes .A .B {...} in CSS.
A '^' in start of a selector joins to parent selector without space, so '.A': {'^:hover': ...} becomes .A:hover {...} in CSS. You can also use '.A:hover' directly but it will restrict other nested keys to hover only.
A list/tuple of values for a key in dict generates CSS fallback, so '.A': {'font-size': ('20px','2em')} becomes .A {font-size: 20px; font-size: 2em;} in CSS.

Read about specificity of CSS selectors here.

Tips:

You can use this inside columns using delayed display trick, like write('First column', C2) where C2 = Slides.hold(Slides.ei.interact, f, x = 5) or Slides.ei.interactive(f, x = 5).
You can also use this under Slides.capture_content to display later in a specific place.

Python

        import time

@self.ei.interact(auto_update=False, grid_css = dict({'.out-main': dict(height='2em')},background='var(--bg2-color)'), date = False)  # self is Slides here
def update_time(date): 
    local_time = time.localtime()
    objs = ['Time: {3}:{4}:{5}'.format(*local_time)] # Print time in HH:MM:SS format
    if date:
        objs.append('Date: {0}/{1}/{2}'.format(*local_time))
    self.stack(objs).display()
        

Python

        import datetime

@self.on_load  # self is Slides here
def push_toast(slide):
    t = datetime.datetime.now()
    time = t.strftime('%H:%M:%S')
    self.notify(f'Notification at {time} form slide {slide.index} and frame {slide.indexf}', timeout=5)
        

Slides.on_load(func)

Decorator for running a function when slide is loaded into view. No return value is required. Use this to e.g. notify during running presentation. func accepts single arguemnet, slide.

See Slides.docs() for few examples.

Do not use this to change global state of slides, because that will affect all slides.
This can be used single time per slide, overwriting previous function.

Content Styling

You can style or colorize your content and text. Provide CSS for that using Slides.html("style",...) or use some of the available styles. See these styles with Slides.css_styles property as shown on right.

Use any or combination of these styles in markdown blocks or css_class argument of writing functions:

css_class	Formatting Style
`text-[value]`	[value] should be one of tiny, small, big, large, huge.
`align-[value]`	[value] should be one of center, left, right.
`rtl`	اردو، فارسی، عربی، ۔۔۔
`info`	Blue text. Icon ℹ️ for note-info class.
`tip`	Blue text. Icon💡 for note-tip class.
`warning`	Orange text. Icon ⚠️ for note-warning class.
`success`	Green text. Icon ✅ for note-success class.
`error`	Red text. Icon⚡ for note-error class.
`note`	Text with note icon, can combine other classes as shown above.
`export-only`	Hidden on main slides, but will appear in exported slides.
`jupyter-only`	Hidden on exported slides, but will appear on main slides.
`block`	Block of text/objects
`block-[color]`	Block of text/objects with specific background color from red, green, blue, yellow, cyan, magenta and gray.
`raw-text`	Text will be shown as printed style.
`zoom-self`	Zooms object on hover, when Zoom is enabled.
`zoom-child`	Zooms child object on hover, when Zoom is enabled.
`no-zoom`	Disables zoom on object when it is child of 'zoom-child'.

Besides these CSS classes, you always have Slide.set_css, Slides.html('style',...) functions at your disposal.

Show Markdown Source

        stack[(3,7)]`//
## Content Styling
You can **style**{.error} or **color["teal"]`colorize`** your *content*{: style="color:hotpink;"} and *color["hotpink","yellow"]`text`*.
Provide **CSS**{.info} for that using hl`Slides.html("style",...)` or use some of the available styles. 
See these **styles**{.success} with `Slides.css_styles` property as shown on right.
|| %{self.css_styles}
//`
        

Highlighting Code

pygments is used for syntax highlighting ¹. You can highlight code using highlight function ² or within markdown using code blocks enclosed with three backticks:

Python

        import ipyslides as isd
        

Javascript

        import React, { Component } from "react";
        

Source code of slide can be embeded via variable too:

Python

        fmt("""

## Highlighting Code
[pygments](https://pygments.org/) is used for syntax highlighting cite`A`.
You can **highlight**{.error} code using `highlight` function cite`B` or within markdown using code blocks enclosed with three backticks:
```python
import ipyslides as isd
```
```javascript
import React, { Component } from "react";
```
Source code of slide can be embeded via variable too: %{self.this.source}
""",
self = '<Slides at 0x2a202645340>'
)
        

Citation A

Citation B

Loading from File/Exporting to HTML

You can parse and view a markdown file. The output you can save by exporting notebook in other formats.

Slides.sync_with_file(start_slide_number, /, path, interval=500)

The variables inserted in file content are used from top scope.

Markdown

        ```citations footnote
@key1: Saboor et. al., 2025
@key2: A citations can span multiple lines, but key should start on new line
<!-- Or put this content in a file 'bib.md' and then inside citations block use include`bib.md` -->
```
        

To debug the linked file or included file, use EOF on its own line to keep editing and clearing errors.

Slides.demo()

Demo slides with a variety of content.

Slides.docs()

Create presentation from docs of IPySlides.

Slides.export_html(path='Slides.html', overwrite=False, progressbar=True)

Build html slides that you can print.

Use 'overrides.css' file in same folder to override CSS styles.
If a slide has only widgets or does not have single object with HTML representation, it will be skipped.
You can take screenshot (using system's tool) of a widget, save it using Clips GUI in side panel and laod as image to keep PNG view of a widget.
If progressbar is set to True, 'bottom' or 'top', a progressbar while shown accordingly. True -> 'bottom'.

PDF printing of slide width is 210mm (8.25in). Height is determined by aspect ratio provided.
Use Save as PDF option instead of Print PDF in browser to make links work in output PDF. Alsp enable background graphics in print dialog.

Introduction
Adding Slides and Content
Layout and Theme Settings
Useful Functions for Rich Content
Loading from File/Exporting to HTML
Advanced Functionality
Presentation Code

Adding content on frames incrementally

Python

        self.write("## Adding content on frames incrementally yoffset`0`")
self.frozen(widget := (code := s.get_source()).as_widget()).display()
self.fsep(stack=True) # frozen in above line get oldest metadata for export
def highlight_code(slide): widget.value = code.focus_lines(range(slide.indexf + 1)).value
self.on_load(highlight_code)

for ws, cols in self.fsep.iter(zip([None, (2,3),None], [(0,1),(2,3),(4,5,6,7)])):
    cols = [self.html('h1', f"{c}",style="background:var(--bg3-color);margin-block:0.05em !important;") for c in cols]
    self.write(*cols, widths=ws)
        

Adding content on frames incrementally

Python

        self.write("## Adding content on frames incrementally yoffset`0`")
self.frozen(widget := (code := s.get_source()).as_widget()).display()
self.fsep(stack=True) # frozen in above line get oldest metadata for export
def highlight_code(slide): widget.value = code.focus_lines(range(slide.indexf + 1)).value
self.on_load(highlight_code)

for ws, cols in self.fsep.iter(zip([None, (2,3),None], [(0,1),(2,3),(4,5,6,7)])):
    cols = [self.html('h1', f"{c}",style="background:var(--bg3-color);margin-block:0.05em !important;") for c in cols]
    self.write(*cols, widths=ws)
        

0

Adding content on frames incrementally

Python

        self.write("## Adding content on frames incrementally yoffset`0`")
self.frozen(widget := (code := s.get_source()).as_widget()).display()
self.fsep(stack=True) # frozen in above line get oldest metadata for export
def highlight_code(slide): widget.value = code.focus_lines(range(slide.indexf + 1)).value
self.on_load(highlight_code)

for ws, cols in self.fsep.iter(zip([None, (2,3),None], [(0,1),(2,3),(4,5,6,7)])):
    cols = [self.html('h1', f"{c}",style="background:var(--bg3-color);margin-block:0.05em !important;") for c in cols]
    self.write(*cols, widths=ws)
        

0

1

Adding content on frames incrementally

Python

        self.write("## Adding content on frames incrementally yoffset`0`")
self.frozen(widget := (code := s.get_source()).as_widget()).display()
self.fsep(stack=True) # frozen in above line get oldest metadata for export
def highlight_code(slide): widget.value = code.focus_lines(range(slide.indexf + 1)).value
self.on_load(highlight_code)

for ws, cols in self.fsep.iter(zip([None, (2,3),None], [(0,1),(2,3),(4,5,6,7)])):
    cols = [self.html('h1', f"{c}",style="background:var(--bg3-color);margin-block:0.05em !important;") for c in cols]
    self.write(*cols, widths=ws)
        

0

1

2

Adding content on frames incrementally

Python

        self.write("## Adding content on frames incrementally yoffset`0`")
self.frozen(widget := (code := s.get_source()).as_widget()).display()
self.fsep(stack=True) # frozen in above line get oldest metadata for export
def highlight_code(slide): widget.value = code.focus_lines(range(slide.indexf + 1)).value
self.on_load(highlight_code)

for ws, cols in self.fsep.iter(zip([None, (2,3),None], [(0,1),(2,3),(4,5,6,7)])):
    cols = [self.html('h1', f"{c}",style="background:var(--bg3-color);margin-block:0.05em !important;") for c in cols]
    self.write(*cols, widths=ws)
        

0

1

2

3

Adding content on frames incrementally

Python

        self.write("## Adding content on frames incrementally yoffset`0`")
self.frozen(widget := (code := s.get_source()).as_widget()).display()
self.fsep(stack=True) # frozen in above line get oldest metadata for export
def highlight_code(slide): widget.value = code.focus_lines(range(slide.indexf + 1)).value
self.on_load(highlight_code)

for ws, cols in self.fsep.iter(zip([None, (2,3),None], [(0,1),(2,3),(4,5,6,7)])):
    cols = [self.html('h1', f"{c}",style="background:var(--bg3-color);margin-block:0.05em !important;") for c in cols]
    self.write(*cols, widths=ws)
        

0

1

2

3

4

Adding content on frames incrementally

Python

        self.write("## Adding content on frames incrementally yoffset`0`")
self.frozen(widget := (code := s.get_source()).as_widget()).display()
self.fsep(stack=True) # frozen in above line get oldest metadata for export
def highlight_code(slide): widget.value = code.focus_lines(range(slide.indexf + 1)).value
self.on_load(highlight_code)

for ws, cols in self.fsep.iter(zip([None, (2,3),None], [(0,1),(2,3),(4,5,6,7)])):
    cols = [self.html('h1', f"{c}",style="background:var(--bg3-color);margin-block:0.05em !important;") for c in cols]
    self.write(*cols, widths=ws)
        

0

1

2

3

4

5

Adding content on frames incrementally

Python

        self.write("## Adding content on frames incrementally yoffset`0`")
self.frozen(widget := (code := s.get_source()).as_widget()).display()
self.fsep(stack=True) # frozen in above line get oldest metadata for export
def highlight_code(slide): widget.value = code.focus_lines(range(slide.indexf + 1)).value
self.on_load(highlight_code)

for ws, cols in self.fsep.iter(zip([None, (2,3),None], [(0,1),(2,3),(4,5,6,7)])):
    cols = [self.html('h1', f"{c}",style="background:var(--bg3-color);margin-block:0.05em !important;") for c in cols]
    self.write(*cols, widths=ws)
        

0

1

2

3

4

5

6

Adding content on frames incrementally

Python

        self.write("## Adding content on frames incrementally yoffset`0`")
self.frozen(widget := (code := s.get_source()).as_widget()).display()
self.fsep(stack=True) # frozen in above line get oldest metadata for export
def highlight_code(slide): widget.value = code.focus_lines(range(slide.indexf + 1)).value
self.on_load(highlight_code)

for ws, cols in self.fsep.iter(zip([None, (2,3),None], [(0,1),(2,3),(4,5,6,7)])):
    cols = [self.html('h1', f"{c}",style="background:var(--bg3-color);margin-block:0.05em !important;") for c in cols]
    self.write(*cols, widths=ws)
        

0

1

2

3

4

5

6

7

Adding User defined Objects/Markdown Extensions

I will be on exported slides

Python

        self.write('## Adding User defined Objects/Markdown Extensions')
self.write(
    self.hold(display, self.html('h3','I will be on main slides',css_class='warning'),
        metadata = {'text/html': '<h3 class="warning">I will be on exported slides</h3>'}
    ), # Can also do 'Slides.serilaizer.get_metadata(obj)' if registered
    s.get_source(), widths = [1,3]
)
self.write(r'If you need to serialize your own or third party objects not serialized by this module, you can use `\@Slides.serializer.register` to serialize them to html.\n{.note .info}')
self.doc(self.serializer,'Slides.serializer', members = True, itself = False).display()
self.write('**You can also extend markdown syntax** using `markdown extensions`, ([See here](https://python-markdown.github.io/extensions/) and others to install, then use as below):')
self.doc(self.extender,'Slides.extender', members = True, itself = False).display()
        

If you need to serialize your own or third party objects not serialized by this module, you can use @Slides.serializer.register to serialize them to html.\n{.note .info}

Slides.serializer.get_func(obj_type)

Get serializer function for a type. Returns None if not found.

Slides.serializer.get_html(obj_type)

Get html str of a registerd obj_type.

Slides.serializer.get_metadata(obj_type)

Get metadata for a type to use in display(obj, metadata) for export purpose. This take precedence over object's own html representation. Returns {} if not found.

Slides.serializer.register(obj_type, verbose=True)

Decorator to register html serializer for an object type.

Decoracted function accepts one argument that will take obj_type and should return HTML string.
This definition will take precedence over any other in the module.
All regeisted serializers only exist for the lifetime of the module in a namespace.
Only a single serializer can be registered for an object type.

Usage

Python

        class MyObject:
    def __repr__(self):
        return 'My object is awesome'

slides = ipyslides.Slides()
@slides.serializer.register(MyObject)
def parse_myobject(obj):
    return f'<h1>{obj!r}</h1>'

my_object = MyObject()
slides.write(my_object) #This will write "My object is awesome" as main heading
parse_myobject(my_object) #This will return "<h1>My object is awesome</h1>"

#This is equivalent to above for custom objects(builtin objects can't be modified)
class MyObject:
    def _repr_html_(self):
        return '<h1>My object is awesome</h1>'

my_object = MyObject()
slides.write(my_object)
        

Serializer function should return html string. It is not validated for correct code on registration time.
Serializer is useful for buitin types mostly, for custom objects, you can always define a `_repr_html_{method which works as expected.}
Serialzers for widgets are equivalent to Slides.alt(func, widget)insidewritecommand for export purpose. Other commands such asSlides.[cols,rows,...]` will pick oldest value only.
IPython's display function automatically take care of serialized objects.

Slides.serializer.unregister(obj_type)

Unregister all serializer handlers for a type.

Slides.serializer.unregisterall()

Unregister all serializer handlers.

You can also extend markdown syntax using markdown extensions, (See here and others to install, then use as below):

Slides.extender.clear()

Clear all extensions and their configurations added by user.

Slides.extender.config(configs_dict)

Add configurations to the Markdown extensions. configs_dict is a dictionary like {'extension_name': config_dict}

Slides.extender.extend(extensions_list)

Add list of extensions to the Markdown parser.

Focus on what matters

There is a zoom button on top bar which enables zooming of certain elements. This can be toggled by Z key.
Most of supported elements are zoomable by default like images, matplotlib, bokeh, PIL image, altair plotly, dataframe, etc.
You can also enable zooming for an object/widget by wrapping it inside `Slide.zoomable` function conveniently.
You can also enable by manully adding zoom-self, zoom-child classes to an element. To prevent zooming under as zoom-child class, use no-zoom class.

Focus on Me 😎

If zoom button is enabled, you can hover here to zoom in this part!
You can also zoom in this part by pressing Z key while mouse is over this part.

SVG Icons

Icons that apprear on buttons inslides (and their rotations) available to use in your slides as well besides standard ipywidgets icons.

Python

        import ipywidgets as ipw
btn = ipw.Button(description='Chevron-Down Icon',icon='chevrond')    
self.write(btn)
        

Source code of this slide

Python

        with self.capture_content() as c:
    with self.code.context():
        import ipywidgets as ipw
        btn = ipw.Button(description='Chevron-Down Icon',icon='chevrond')    
        self.write(btn)

group = zip(self.icon.available[::2], self.icon.available[1::2]) # make 4 columns table
self.write(['''
    ## SVG Icons
    Icons that apprear on buttons inslides (and their rotations) available to use in your slides as well
    besides standard ipywidgets icons.
    ''', *c.outputs, 'line`200`**Source code of this slide**',self.this.get_source()], 
    self.table([(f'`{j}`', self.icon(j,color='crimson').svg,f'`{k}`', self.icon(k,color='crimson').svg) for j, k in group],headers=['Name','Icon','Name','Icon']),
widths=[3,2])
        

Auto Slide Numbering

Use -1 as placeholder to update slide number automatically.

In Jupyter notebook, this will be updated to current slide number.
In python file, it stays same.
You need to run cell twice if creating slides inside a for loop while using -1.
Additionally, in python file, you can use Slides.build<sub> instead of using </sub>-1.

Some kernels may not support auto slide numbering inside notebook.

Presentation Code

Python

        def docs(self):
    "Create presentation from docs of IPySlides."
    self.close_view() # Close any previous view to speed up loading 10x faster on average
    self.clear() # Clear previous content
    self.create(range(31)) # Create slides faster

    from ..core import Slides

    self.set_citations({'A': 'Citation A', 'B': 'Citation B'}, mode = 'footnote')
    self.settings.footer(text=self.get_logo("1em") + "IPySlides Documentation", date=None)

    with self.build(0): # Title page
        self.this.set_bg_image(self.get_logo(),0.25, filter='blur(10px)', contain=True)
        self.write(f'## IPySlides {self.version} Documentation\n### Creating slides with IPySlides')
        self.center(self.fmt('''
            alert`Abdul Saboor` ^`1`

            today``
            {.text-small}

            %{logo}

            ::: text-box
                ^`1`My University is somewhere in the middle of nowhere
            ''', logo = self.get_logo("4em"))).display()

    self.build(-1, self.fmt('''
        ```md-after
            section`Introduction` 
            ```multicol .block-green
            toc[True]`## Table of contents`
            +++
            ### This is summary of current section
            Oh we can use inline columns stack`Column A || Column B` here and what not!
            %{btn}
            ```
        ```''', btn = self.draw_button))

    with self.build(-1):
        self.write('# Main App')
        self.doc(Slides).display()

    with self.build(-1):
        self.write('# Jump between slides')
        self.doc(self.link, 'Slides').display()
        with self.code.context(returns=True) as c:
            skipper = self.link('Skip to dynamic content', 'Back to link info', icon='arrow', back_icon='arrowl')
            skipper.origin.display() # skipper.target is set later somewhere, can do backward jump too
        c.display()

    with self.build(-1):
        self.write('## Adding Slides section`Adding Slides and Content`')
        self.write('Besides function below, you can add slides with `%%slide number [-m]` magic as well.\n{.note .info}')
        self.write([self.doc(self.build,'Slides'), self.doc(self.sync_with_file,'Slides')])

    with self.build_():
        self.write('''
            ## Important Methods on Slide
            ::: note-warning
                Use slide handle or `Slides[number,]` to apply these methods becuase index can change on new builds.
        ''')
        self.doc(self[0], members='yoffset set_animation set_bg_image update_display get_source show set_css'.split(), itself = False).display()
        self.css_syntax.display()

    self.build(-1, re.sub(r'^---\s*$', '---\n## Extended Markdown' ,_syntax.xmd_syntax, flags=re.MULTILINE))

    with self.build(-1):
        self.write('## Adding Content')
        self.write('Besides functions below, you can add content to slides with `%%xmd`,`%xmd` as well.\n{.note .info}')
        self.write(self.doc(self.write,'Slides'), [self.doc(self.parse,'Slides'),self.doc(self.as_html,'Slides'),self.doc(self.html,'Slides')])

    with self.build(-1):
        self.write('## Adding Speaker Notes')
        self.write([rf'styled["note success"]`You can use alert`notes\`notes content\`` in markdown.`',
                   'This is experimental feature, and may not work as expected.\n{.note-error .error}'])
        self.doc(self.notes,'Slides.notes', members = True, itself = False).display()

    with self.build(-1):
        self.write('## Displaying Source Code')
        self.write('In markdown, the block `md-[before,after,left,right] [-c]` parses and displays source as well.')
        self.doc(self.code,'Slides.code', members = True, itself = False).display()

    self.build(-1, r'section`//Layout and color["yellow","black"]`Theme` Settings//` toc`### Contents`')

    with self.build(-1) as s:
        s.set_css({
            '--bg1-color': 'linear-gradient(45deg, var(--bg3-color), var(--bg2-color), var(--bg3-color))',
            '.highlight': {'background':'#8984'}
        }) 
        self.styled('## Layout and Theme Settings', 'info', border='1px solid red').display()
        self.doc(self.settings,'Slides', members=True,itself = True).display()

    with self.build(-1):
        self.write('## Useful Functions for Rich Content section`//Useful Functions for alert`Rich Content`//`')
        self.doc(self.alt,'Slides').display()

        members = sorted((
            'AnimationSlider alert block bokeh2html bullets styled fmt color details doc '
            'today error zoomable highlight html iframe image frozen notify plt2html '
            'raw set_dir sig stack table textbox suppress_output suppress_stdout svg vspace'
        ).split())
        self.doc(self, 'Slides', members = members, itself = False).display()

    with self.build(-1):
        self.write(r'''
            ## Citations and Sections
            Use syntax alert`cite\`key\`` / alert`\@key` to add citations which should be already set by hl`Slides.set_citations(data, mode)` method.
            Citations are written on suitable place according to given mode. Number of columns in citations are determined by 
            hl`Slides.settings.layout(..., ncol_refs = int)`. @A

            Add sections in slides to separate content by alert`section\`text\``. Corresponding table of contents
            can be added with alert`toc\`title\``.
        ''')
        self.doc(self, 'Slides', members = ['set_citations'], itself = False).display()

    with self.build(-1):
        skipper.target.display() # Set target for skip button
        self.write('## Dynamic Content')

        with self.capture_content() as cap, self.code.context():
            import time

            @self.ei.interact(auto_update=False, grid_css = dict({'.out-main': dict(height='2em')},background='var(--bg2-color)'), date = False)  # self is Slides here
            def update_time(date): 
                local_time = time.localtime()
                objs = ['Time: {3}:{4}:{5}'.format(*local_time)] # Print time in HH:MM:SS format
                if date:
                    objs.append('Date: {0}/{1}/{2}'.format(*local_time))
                self.stack(objs).display()

        with self.code.context(returns=True) as c:
            import datetime

            @self.on_load  # self is Slides here
            def push_toast(slide):
                t = datetime.datetime.now()
                time = t.strftime('%H:%M:%S')
                self.notify(f'Notification at {time} form slide {slide.index} and frame {slide.indexf}', timeout=5)

        self.write(
            [self.doc(self.ei.interact,'Slides.ei')], 
            [*cap.outputs, c, self.doc(self.on_load,'Slides')],
        )

    self.build(-1, fmt("""
    ```md-after -c
    stack[(3,7)]`//
    ## Content Styling
    You can **style**{.error} or **color["teal"]`colorize`** your *content*{: style="color:hotpink;"} and *color["hotpink","yellow"]`text`*.
    Provide **CSS**{.info} for that using hl`Slides.html("style",...)` or use some of the available styles. 
    See these **styles**{.success} with `Slides.css_styles` property as shown on right.
    || %{self.css_styles}
    //`     
    ```
    """))

    self.build(-1, self.fmt('''
    ## Highlighting Code
    [pygments](https://pygments.org/) is used for syntax highlighting cite`A`.
    You can **highlight**{.error} code using `highlight` function cite`B` or within markdown using code blocks enclosed with three backticks:
    ```python
    import ipyslides as isd
    ```
    ```javascript
    import React, { Component } from "react";
    ```
    Source code of slide can be embeded via variable too: %{self.this.source}
    ''', self=self))


    with self.build(-1):
        self.write('## Loading from File/Exporting to HTML section`Loading from File/Exporting to HTML`')
        self.write('You can parse and view a markdown file. The output you can save by exporting notebook in other formats.\n{.note .info}')
        self.write([self.doc(attr,'Slides') for attr in (self.sync_with_file,self.demo,self.docs,self.export_html)])

    self.build(-1, 'section`Advanced Functionality` toc`### Contents`')

    with self.build_() as s:
        self.write("## Adding content on frames incrementally yoffset`0`")
        self.frozen(widget := (code := s.get_source()).as_widget()).display()
        self.fsep(stack=True) # frozen in above line get oldest metadata for export
        def highlight_code(slide): widget.value = code.focus_lines(range(slide.indexf + 1)).value
        self.on_load(highlight_code)

        for ws, cols in self.fsep.iter(zip([None, (2,3),None], [(0,1),(2,3),(4,5,6,7)])):
            cols = [self.html('h1', f"{c}",style="background:var(--bg3-color);margin-block:0.05em !important;") for c in cols]
            self.write(*cols, widths=ws)

    with self.build(-1) as s:
        self.write('## Adding User defined Objects/Markdown Extensions')
        self.write(
            self.hold(display, self.html('h3','I will be on main slides',css_class='warning'),
                metadata = {'text/html': '<h3 class="warning">I will be on exported slides</h3>'}
            ), # Can also do 'Slides.serilaizer.get_metadata(obj)' if registered
            s.get_source(), widths = [1,3]
        )
        self.write(r'If you need to serialize your own or third party objects not serialized by this module, you can use `\@Slides.serializer.register` to serialize them to html.\n{.note .info}')
        self.doc(self.serializer,'Slides.serializer', members = True, itself = False).display()
        self.write('**You can also extend markdown syntax** using `markdown extensions`, ([See here](https://python-markdown.github.io/extensions/) and others to install, then use as below):')
        self.doc(self.extender,'Slides.extender', members = True, itself = False).display()

    with self.build(-1):
        self.write(r'''
        ## Focus on what matters
        - There is a zoom button on top bar which enables zooming of certain elements. This can be toggled by `Z` key.
        - Most of supported elements are zoomable by default like images, matplotlib, bokeh, PIL image, altair plotly, dataframe, etc.
        - You can also enable zooming for an object/widget by wrapping it inside \`Slide.zoomable\` function conveniently.
        - You can also enable by manully adding `zoom-self`, `zoom-child` classes to an element. To prevent zooming under as `zoom-child` class, use `no-zoom` class.

        ::: zoom-self block-red
            ### Focus on Me 😎
            - If zoom button is enabled, you can hover here to zoom in this part!
            - You can also zoom in this part by pressing `Z` key while mouse is over this part.
        ''')

    with self.build(-1):
        with self.capture_content() as c:
            with self.code.context():
                import ipywidgets as ipw
                btn = ipw.Button(description='Chevron-Down Icon',icon='chevrond')    
                self.write(btn)

        group = zip(self.icon.available[::2], self.icon.available[1::2]) # make 4 columns table
        self.write(['''
            ## SVG Icons
            Icons that apprear on buttons inslides (and their rotations) available to use in your slides as well
            besides standard ipywidgets icons.
            ''', *c.outputs, 'line`200`**Source code of this slide**',self.this.get_source()], 
            self.table([(f'`{j}`', self.icon(j,color='crimson').svg,f'`{k}`', self.icon(k,color='crimson').svg) for j, k in group],headers=['Name','Icon','Name','Icon']),
        widths=[3,2])


    with self.build_():
        self.write("""
            # Auto Slide Numbering
            Use alert`-1` as placeholder to update slide number automatically. 

            - In Jupyter notebook, this will be updated to current slide number. 
            - In python file, it stays same.
            - You need to run cell twice if creating slides inside a for loop while using `-1`.
            - Additionally, in python file, you can use `Slides.build_` instead of using `-1`.

            ::: note-warning
                Some kernels may not support auto slide numbering inside notebook.
        """)

    self.build(-1, lambda s: self.write(['## Presentation Code section`Presentation Code`',self.docs]))
    self.navigate_to(0) # Go to title
    return self
        