lookatme Documentation

lookatme is an interactive, terminal-based markdown presentation tool. Key features include:

• Themes: Support for different visual styles.
• Syntax highlighting: For code blocks within slides.
• Embedded YAML configuration: Styling and settings can be defined directly in the Markdown YAML header.
• Embedded terminals: Run terminal sessions as part of your presentation.
• Live reloading: Supports both live and manual source reloading.
• Extensions: Support for contributor extensions.
• Smart Slide Splitting: Intelligent handling of slide boundaries.

If your input Markdown does not contain horizontal rules (--- or ***), lookatme uses an automatic splitting mechanism based on heading levels to create slides. The behavior depends on the frequency of the lowest-level heading:

1. Single occurrence of lowest heading: If the lowest heading level (e.g., h1 if no h2 exists) appears only once, that heading becomes the presentation title. The next lowest heading level (e.g., h2) is then used as the marker to split the content into individual slides.
2. Multiple occurrences of lowest heading: If the lowest heading level appears multiple times, that heading level is used as the slide separator marker, and no presentation title is set.

Extensions in lookatme allow you to override and redefine how Markdown is rendered. They function as namespace packages within lookatme.contrib.

Extensions have 'first-chance' opportunities to handle rendering function calls. An extension can either:

1. Provide its own implementation of a rendering function (e.g., render_table) to change behavior (like adding sortable rows).
2. Ignore a specific rendering function call by raising an IgnoredByContrib exception, which allows the original lookatme behavior (or other extensions) to handle the call.

Extensions are modules that redefine lookatme behavior. To implement an extension, you can redefine functions like render_code (found in lookatme/render/markdown_block.py).

To allow the default lookatme behavior to take over when your extension does not want to handle a specific token or language, you must raise the lookatme.exceptions.IgnoredByContrib exception.

import datetime
import calendar
import urwid

from lookatme.exceptions import IgnoredByContrib


def render_code(token, body, stack, loop):
    lang = token["lang"] or ""
    if lang != "calendar":
        # Raising this allows default lookatme behavior to handle the block
        raise IgnoredByContrib()
    
    today = datetime.datetime.utcnow()
    return urwid.Text(calendar.month(today.year, today.month))

Extensions in lookatme can intercept specific Markdown rendering events. Developers can create custom renderers by using the @contrib_first decorator. This allows an extension to have the first opportunity to handle a specific token (like a code block) before the default renderer processes it.

When a renderer handles a token, it typically returns a list of UI elements (e.g., urwid components) to be displayed.

@contrib_first
def render_code(token, body, stack, loop):
    # ... implementation ...
    return [
        urwid.Divider(),
        res,
        urwid.Divider(),
    ]

Styling in lookatme is resolved by applying overrides to a base set of default styles. The resolution follows a specific order of precedence, where later sources override earlier ones via a deep merge of nested dictionaries.

To determine the final style used for rendering markdown, lookatme applies settings in this order:

1. Default style settings (defined in lookatme.schemas)
2. Theme settings
3. Slide's YAML header
4. Command-line options

If a setting is partially defined in an override, only the specified keys are updated, while other keys from the previous level are preserved.

The lookatme.contrib.file_loader builtin extension allows you to source external files directly into a code block in your markdown presentation. This is achieved by using a code block with the language identifier file and providing a YAML configuration block inside it.

When using this extension, the content of the code block is replaced by the contents of the file specified in the path key. You can optionally specify a language for syntax highlighting, a transformation command, and a specific range of lines to display.

path: ../source/main.c
lang: c

Extensions must be implemented as implicit namespace packages within the lookatme.contrib submodule. It is recommended to use the lookatme.contrib-template for new development.

Required Directory Structure: An extension should follow this layout (note that __init__.py is not required in the contrib path due to the implicit namespace package format):

examples/calendar_contrib/
├── lookatme
│   └── contrib
│       └── calendar.py
└── setup.py

The lookatme.contrib.terminal extension allows you to embed interactive terminals within your slides using a specific markdown code block language format.

To use the basic format, use a code block with the language identifier terminal followed by a number (e.g., terminal8). The number specifies the height (number of rows) of the terminal.

Interaction:

• Focus: Click inside the terminal to gain focus for typing and interaction.
• Escape: Press ctrl+a to escape from the terminal mode.

bash -il

For more control over the terminal behavior, use the terminal-ex language identifier. This mode requires the content of the code block to be a YAML object conforming to the TerminalExSchema.

Configuration Options:

• command: (required) The command to run in the terminal.
• rows: The number of rows for the terminal height.
• init_text: Initial text to feed to the command (uses the expect command). Useful for pre-loading text on a prompt.
• init_wait: The prompt string to wait for using expect. Required if init_text is set.
• init_codeblock: Boolean indicating whether to show a codeblock containing the init_text.
• init_codeblock_lang: The language to use for the init_text codeblock.

command: bash -il
rows: 20
init_text: echo hello
init_wait: '$> '
init_codeblock_lang: bash

To use an extension in your presentation, follow these two steps:

1. Install the extension via pip using its full namespace path:

   pip install lookatme.contrib.XXX

2. Register the extension in your slide's YAML frontmatter under the extensions key:

---
title: TITLE
author: AUTHOR
date: 2019-11-01
extensions:
  - XXX
---

# Slide 1

...

Note: Replace XXX with the actual name of the extension.