This example shows how to embed TEI content into a static website using markdown for the content pages. The site was created with Hugo, a popular static website generator, which allows you to get a simple website, e.g. a blog, up and running within minutes.

Hugo creates static files which you can either copy into an existing webserver of your own, or host on free services like render. Obviously you still need a TEI Publisher instance somewhere which hosts the TEI content.

Setup

  1. created a new site with hugo new site

  2. installed a standard theme (even) into themes

  3. copied config.toml from themes/even/exampleSite and modified it slightly

  4. copied themes/even/layouts/partials/scripts.html to layouts/partials and added two lines to import the TEI Publisher component library (view on github):

  5. in the same way copied themes/even/layouts/partials/header.html to change the logo

  6. created a custom css file in static/css and linked it from config.toml

  7. generated a set of favicons and extracted them into /static

Given this setup, we can start using TEI Publisher web components from within our markdown.

Embed HTML directly

The easiest approach is to directly embed HTML into markdown as demonstrated by the example below:

The source code for above example is given below:

The data is loaded from the TEI Publisher instance running on teipublisher.com, but you could use any other instance here, given that you allow the host running your hugo site to access TEI Publisher. This is configured in the modules/config.xqm of your TEI Publisher or a stand-alone custom edition created by it. Just add a regular expression matching your hugo host to the whitelist. In my case, hugo runs on https://teipublisher.render.com:

Using Shortcodes

While you can use TEI Publisher custom elements directly in markdown, hugo provides a way to extend markdown with custom commands, so called shortcodes. Creating a shortcode is fairly straightforward: just create an .html file in layouts/shortcodes which contains the template snippet you want to insert. I created one called tei-embed, which takes a number of parameters for setting the ODD, document path and view. The parameters are passed on to the corresponding HTML attributes. Check the code on github.

In general I find Hugo’s template syntax a bit difficult, but that’s probably because I never tried it before.

Embedding Facsimiles

Beyond embedding TEI content, we can also use any other component provided by TEI Publisher, e.g. pb-facsimile to integrate a IIIF viewer: