README.md

gatsby-theme-ceteicean

This Gatsby theme implements HTML5 Custom Elements for XML publishing, particularly with TEI.

It re-implements parts of CETEIcean excluding behaviors; instead, to customize the behavior of specific elements, you can define React components with React TEI Router.

How to use

You can add this theme to a new or existing Gatsby project. First install it:

npm install gatsby-theme-ceteicean

Then add the theme to your gatsby-config.js.

module.exports = {
  plugins: [
    "gatsby-theme-ceteicean"
  ],
}

Make sure to source your XML (TEI) files so that they are available in GraphQL:

module.exports = {
  plugins: [
    "gatsby-theme-ceteicean",
    {
      resolve: "gatsby-source-filesystem",
      options: {
        path: "PATH_TO_DIR_WITH_XML",
      },
    },
  ],
}

To lean more about how the XML files are sourced, see gatsby-transformer-ceteicean. You can pass transformation functions to gatsby-transformer-ceteicean via options:

const preTransform = require('./preTransform')
const postTransform = require('./postTransform')

{
  resolve: `gatsby-theme-ceteicean`,
  options: {
    applyBefore: [preTransform],
    applyAfter: [postTransform],
  }
},

Defining behaviors

Once the XML documents are rendered as HTML Custom Elements, they can be styled via CSS, for example:

tei-p {
  display: block;
}

More complex transformations can be performed via React components. The theme provides some default behaviors for TEI.

Behaviors rely on react-teirouter to traverse the XML document and render a given element via a provided React component. To provide new behaviors, it is recommended to use the Behavior component for conformance to CETEIcean behaviors (for example, it preserves the original content in an hidden element).

import { TEINodes } from "react-teirouter"
import { Behavior } from "gatsby-theme-ceteicean/src/components//Behavior"

const Code = (props) => {
  return (<Behavior node={props.teiNode}>
    <code>
      {<TEINodes 
          teiNodes={props.teiNode.childNodes}
          {...props}/>}
    </code>
  </Behavior>)
}

Finally, you will need to shadow Ceteicean.tsx and provide new behaviors via the routes parameter. Routes are provided as an object:

{
  "matching-element": YourComponent,
  "another-element": AnotherComponent
}

Here is a more full example of how to shadow Ceteicean.tsx:

import React from "react"
import Ceteicean from "gatsby-theme-ceteicean/src/components/Ceteicean"

import MyTeiHeader from "./MyTeiHeader"

export default function ShadowedCeteicean({pageContext}) {

  const routes = {
    "tei-teiheader": MyTeiHeader
  }

  return(
    <Ceteicean pageContext={pageContext} routes={routes} />
  )

}

Other options

options.fullShadow

By default, gatsby-theme-ceteicean will create a page for each sourced XML file. You can turn this off and write your own createPages function.

{
  resolve: `gatsby-theme-ceteicean`,
  options: {
    fullShadow: true
  }
},

options.exclude

You can exclude some files from being converted into web pages by providing their file names.

{
  resolve: `gatsby-theme-ceteicean`,
  options: {
    exclude: ["tei1.xml", "tei2.xml"]
  }
},

Using theme components without shadowing

It is possible to use the theme's underlying components without shadowing. In this case we recommend starting from the Renderer component.

This can be useful when rendering TEI fragments as opposed to full TEI documents to put in a page.

import { Renderer } from "gatsby-theme-ceteicean/src/components/Renderer"

export default function MyComponent() {

  return(
    <Renderer name="example" elements={["tei-tei"]} prefixed="<tei-tei/>" routes={} />
  )

}

Beyond TEI

Other namespaces besides TEI can be passed on to the transformer. They will get prefixed and registered, but you will have to define styles and behaviors. You can pass a set of namespaces as an option in gatsby-config.js that will replace the default namespaces.

{
  resolve: `gatsby-theme-ceteicean`,
  options: {
    namespaces: {
      "http://www.tei-c.org/ns/1.0": "tei",
      "http://www.tei-c.org/ns/Examples": "teieg",
      "http://www.w3.org/2001/XInclude": "xi"
    }
  }
},