Contrib Extensions¶
lookatme allows an extension to override and redefine how markdown is rendered. Extensions have first-chance opportunities to handle rendering function calls. Extensions also have the ability to ignore specific rendering function calls and allow original lookatme behavior (or other extensions) to handle the call to that rendering function.
For example, an extension may provide its own implementation of the render
function render_table
to provide custom table rendering, such as sortable
rows, alternating row background colors, etc.
Using Extensions¶
Extensions are namespace packages within lookatme.contrib
. The are used by
- Installing the extension with
pip install lookatme.contrib.XXX
- Adding the extension to the list of extensions required by your slides:
---
title: TITLE
author: AUTHOR
date: 2019-11-01
extensions:
- XXX
---
# Slide 1
...
Extension Layout¶
It is highly recommended that you use the lookatme.contrib-template to create new extensions.
Extensions must be a namespaced module within the lookatme.contrib
submodule. The basic tree layout for such an extension is below:
examples/calendar_contrib/
├── lookatme
│ └── contrib
│ └── calendar.py
└── setup.py
Notice that there is not an __init__.py
file in the contrib path. This is
using the implicit namespace package
format for creating namespace packages, where an __init__.py
is not
needed.
Extension setup.py¶
Below is the setup.py
from the examples/calendar_contrib
extension:
"""
Setup for lookatme.contrib.calender example
"""
from setuptools import setup, find_namespace_packages
import os
setup(
name="lookatme.contrib.calendar",
version="0.0.0",
description="Adds a calendar code block type",
author="James Johnson",
author_email="d0c.s4vage@gmail.com",
python_requires=">=3.5",
packages=find_namespace_packages(include=["lookatme.*"]),
)
Overriding Behavior¶
Any function within lookatme that is decorated with @contrib_first
may be
overridden by an extension by defining a function of the same name within the
extension module.
For example, to override the render_code
function that is declared in
lookatme in lookatme/render/markdown_block.py,
the example calender extension must declare its own function named
render_code
that accepts the same arguments and provides the same return
values as the original function:
"""
Defines a calendar extension that overrides code block rendering if the
language type is calendar
"""
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":
raise IgnoredByContrib()
today = datetime.datetime.utcnow()
return urwid.Text(calendar.month(today.year, today.month))
Notice how the extension code above raises the IgnoredByContrib
exception
to allow the default lookatme behavior to occur.
Overrideable Functions¶
Below is an automatically generated list of all overrideable functions that
are present in this release of lookatme. See the
lookatme.tui.SlideRenderer.do_render
function for details on markdown_block
render function arguments and return values.
render_newline
render_hrule
render_heading
render_table
render_list_start
render_list_end
render_list_item_start
render_loose_item_start
render_list_item_end
render_text
render_paragraph
render_block_quote_start
render_block_quote_end
render_code
inline_html
text
escape
autolink
footnote_ref
image
link
double_emphasis
emphasis
codespan
linebreak
strikethrough