Balisage Paper: Efficient Development of TEI Rendering Web Applications Using Vue.js

Introduction

Publishing digitally edited texts, glossaries, bibliographies, etc., in TEI (Text Encoding Initiative), on the web requires painstaking effort, especially for humanities scholars. Scholars often need to write code to process TEI documents because there is no universal environment that can render TEI like web browsers for HTML. Even for scholars familiar with web development, spending excessive effort on web application development can reduce the time available for primary scholarly work. Some might build a website by outsourcing, but that might undermine the flexibility of updating the application features.

To tackle this issue, my study aims to find an easier, faster way to build and maintain a web application for digital editorial projects using TEI. This paper proposes using Vue.js to address this problem. Vue.js is one of the modern front-end web application frameworks that allows us to develop more effectively through simpler, more efficient coding.

As a preceding study about TEI encoding and rendering, the website for the “Chymistry of Isaac Newton” project (https://chymistry.org) at Indiana University has edited around 750,000 words from the Newton manuscripts on alchemy.^[1] This is one of the largest projects for digital manuscript editing with TEI. I have been engaged in this project for over six years, mainly as an editorial assistant and web developer. The website offers a great reading experience, including its dynamic web view. On the other hand, it has maintainability issues. Since the website was initially developed through outsourcing, few people can currently modify it. Furthermore, the website's structure is complicated, which takes a developer a long time and effort to learn. This forms the background for developing a simplified web application for TEI.

This paper is divided into five sections to introduce the benefits of Vue.js web applications. In the first section, the paper begins with a fundamental question: What is the significance of creating a digital/web edition? Without answering it, we cannot convince anyone to adopt TEI and web technologies for historical research. The second section introduces an editorial project in my dissertation, “Alchemy in Medieval Islam and Abū Bakr al-Rāzī” (Indiana University, 2025). In the dissertation, I edited an Arabic text from two manuscript witnesses and encoded it into TEI.^[2] At the same time, I developed a Vue.js web application to render the TEI edition into a reader-friendly format with dynamic features. This section also elaborates on the logic and structure of the Vue.js web application. The third section summarizes the benefits of Vue.js for TEI rendering. In the last section, we discuss further possibilities of the Vue.js web application.

This paper makes three main contributions: First, it proposes a lightweight and reproducible architecture for rendering TEI documents using a modern front-end framework. Second, it demonstrates a practical method for integrating XSLT transformation with Vue.js components. Third, it identifies and resolves technical issues arising from the incompatibility between XSLT and Vue.js syntax (e.g., colon-prefixed attributes), providing a reusable workaround.

What is the significance of creating a digital/web edition?

Making a critical edition from manuscript sources is necessary in the field of history. Critical editions help later researchers in terms of accessibility and reliability because they no longer have to collect and compare multiple witnesses of the primary source. Even with cutting-edge AI technology, it does not guarantee the complete accuracy in transcribing the text from manuscript sources. Although we can take advantage of such technologies in the process of editing, scholars must remain responsible for finalizing the editing process.

Since humans are not perfect, we make mistakes. Also, as years go by, researchers may encounter new research questions regarding the same primary source. If your scholarly edition is paper-based, since it is supposed to be the final version, it is impossible to change the content so often once it is published. On the other hand, publishing a scholarly edition on the web allows you to apply the corrections right after you find a minor typo. You can implement a new analysis tool in the web application after the first launch.

TEI^[3] is probably the most standardized way of encoding primary sources. Thus, once a critical edition is created in TEI, it can be shared among many scholars easily. On the other hand, the readability of the TEI source code is usually not friendly, especially for most historians. Therefore, unless the usage of the encoded text is limited to data processing, it is definitely necessary to render it into a reader-friendly format, which is usually realized through a web application. However, developing and deploying a web application often has many obstacles, especially for small-scale research projects, due to financial capacity, workload, learning cost, and so forth.

This paper presents one practical approach that addresses several of these difficulties. Using a modern generation JavaScript front-end framework makes the application structure simpler. It enables us to develop faster with a small number of people, even those who are not full-time web developers. In order that more historians use TEI as a method of scholarly edition, research with TEI-edited sources has to be easier, more convenient, more comfortable, and more useful. The solution here would lower the bar of using TEI for historical research.

Case Study: Rendering a TEI Scholarly Edition in Arabic into Web View

Structure

First of all, the following is the environment of the web application:

• Vue.js (3.5.17)

• Vuetify.js (3.8.11, a GUI framework for Vue.js)

• SaxonJS 2 (an XSLT engine)

• GitHub Pages (deployment destination)

The version of Vue.js used is 3, which is currently the latest major version.^[7] Vuetify.js version 3 is a compatible version with Vue 3.^[8] SaxonJS is necessary to execute XSLT code. Version 2 supports XSLT 3.0 execution.^[9] GitHub Pages basically offers a static website space, being read from a repository, but when we commit a Vue.js project, the Pages automatically deploys it as a Vue.js web application.^[10]

The data flow of this Vue.js application is illustrated in the following chart:

Figure 1: Data Flow of the Application

This figure shows the data flow from TEI input to Vue.js rendering. The transformation is executed on the client side using SaxonJS.

The basic structure is probably the same as other web applications that render TEI-edited sources. However, in this application, instead of converting into HTML, the XSLT code here is designed to convert into the <template> part of the Vue.js code.^[11] In order to have the benefit of Vue.js and other modern frameworks, this web application is built as a single-page application (SPA). As a result, every content of the application is called through the main view.

The website structure is simple and straightforward:

                     
Main View
├── Home
├── About
├── Edition (Currently containing 2 scholarly Editions)
├── Translation (not ready to publish)
├── Glossary (not ready to publish)
└── Analysis (not ready to publish)

In this web application, the Vue.js code converted from TEI is embedded in the “Edition” view, which serves as the primary source viewer.

As for the structure of the web application, the project directory is organized as follows:

                     
arabic-tei/
├── docs/
├── node_modules/
├── public/
└── src/
    ├── assets/
    ├── image/
    ├── tei/
    ├── xslt/
    ├── components/
    ├── pages/
    ├── plugins/
    ├── router/
    ├── styles/
    ├── main.js
    └── App.vue

Technically, once we generate a project folder and install plugins with a project management tool (such as npm),^[12] the development is largely confined to the src directory.

Logic of the Conversion from TEI to Vue.js code

The file called edition.vue, located in /src/pages indicated above, renders TEI editions into a reader-friendly view. The webpage appears like this:

Figure 2: The “Edition” Page

This is the appearance of the initial state of the “Edition” page.

The left foldable column is a list of edited primary sources. When you press the title, the conversion process is executed, and the text of the chosen primary source appears on the right. In the conversion process, an XSLT program is invoked to process the TEI file corresponding to the chosen primary source.

The chosen text shows like this:

Figure 3: The Rendered Text

This is the appearance of the rendered text.

Here, the XSLT program processes mainly two parts. The part before the main text, which includes, the title, author and list of witnesses, is data extracted from the TEI header (i.e., <teiHeader>). The other part is the converted result of the <text> element in the TEI file.

In both cases, the conversion result has to follow the Vue.js and Vuetify.js coding conventions. For example, the list of the witnesses shown above consists of expansion panels provided from Vuetify.js. Thus, the converted code is supposed to be like:

                     
<v-expansion-panels multiple class="mb-10">
  <v-expansion-panel>
    <v-expansion-panel-title class="text-h5">
      [SHELF MARK]
    </v-expansion-panel-title>
    <v-expansion-panel-text>
      [DETAIL INFO OF THE CODEX]
    </v-expansion-panel-text>
    ･･･
  </v-expansion-panel>
</v-expansion-panels>

Then, XSLT can be written as follows:

                     
<xsl:element name="v-expansion-panels">
  <xsl:attribute name="multiple"/>
  <xsl:attribute name="class">mb-10</xsl:attribute>
  <xsl:for-each select="fileDesc/sourceDesc/msDesc">
    <xsl:element name="v-expansion-panel">
      <xsl:element name="v-expansion-panel-title">
        <xsl:attribute name="class">text-h5</xsl:attribute>
        <xsl:value-of select="[SHELF MARK]"/>
      </xsl:element>
      <xsl:element name="v-expansion-panel-text">
        <xsl:value-of select="DETAIL INFO OF THE CODEX"/>
      </xsl:element>
    </xsl:element>
  </xsl:for-each>
</xsl:element>

Although most of the XSLT coding is straightforward and has no major difference from when converting into HTML, some of the Vue.js coding conventions cause a critical issue in XSLT execution.

The problem is processing colon (:). In Vue.js, a colon is involved in an attribute when using the v-bind feature in some of the cases. The v-bind gives a dynamic value to an attribute of an element. Therefore, it is almost inevitable to use it as long as using Vue.js. In the case of my web application, the following Vue.js code is desired:

                     
<v-menu :nudge-width="150" :close-on-content-click="false">

:nudge-width is an abbreviated form of v-bind:nudge-width. In this way, we have to add a colon to use this feature in Vue.js. However, the colon is a reserved character in XSLT, which uses it to express namespaces. Therefore, if a colon is included in a value or attribute in XSLT, this causes errors during XSLT processing. In my web application, I invented a workaround that lets JavaScript code in the Vue.js file convert colon-involved parts. In order to output the code above, the XSLT adds an intermediary id attribute like the following:

                     
<xsl:element name="v-menu">
  <xsl:attribute name="id">v-menu-config</xsl:attribute>
</xsl:element>
･･･

Then JavaScript replaces it:

                     
while (!!doc.querySelector('#v-menu-config')) {
  doc.querySelector('#v-menu-config').setAttribute(':nudge-width', '150')
  doc.querySelector('#v-menu-config').setAttribute(':close-on-content-click', 'false')
  doc.querySelector('#v-menu-config').removeAttribute('id')
}

This workaround highlights a broader compatibility issue between XML-based transformation pipelines and modern JavaScript frameworks. The proposed solution is not limited to this project but can be applied to similar cases where XSLT-generated output must conform to framework-specific syntactic constraints.

Aside from this problem, XSLT can easily create Vuetify.js GUI components, which makes the website look quite well organized and equipped with dynamic features without extra effort. For specific website GUI features, please refer to the website.

Benefits of Using Vue.js

The improvements over conventional TEI rendering applications can be summarized as follows. The first is low running cost. To run a Vue.js application, we do not need a fully equipped server space. GitHub Pages or other so-called BaaS, such as Firebase, which only requires an inexpensive subscription, would be enough to host a Vue.js application. This is an affordable running cost for any researcher, even for those who do not receive research funds. The second is the simple application structure. We only have to edit a few of the folders in the project folder, which does not require any complicated configurations or stylesheets. This enables one or a few persons to develop the entire application without taking time. This is also appropriate from a maintainability standpoint. The third is efficient but powerful GUI development. The use of Vue.js and Vuetify.js (which can be other GUI frameworks for Vue.js) not only allows us to use sophisticated GUI components, but also to make them dynamic quickly. This is because a Vue.js file includes both template and script parts. In other words, it is straightforward to map methods and variables in the script to the GUI component in the template. Compared to alternative approaches such as server-side rendering or static HTML transformation, Vue.js enables a tighter integration between transformed TEI content and interactive user interfaces through its component-based architecture. This could promote more scholars to consider editing primary sources in TEI.

Further Possibilities of the Web Application

As explained above, one of the advantages of creating scholarly editions digitally is being able to update. There are also several plans for my web application in the dissertation project. Some can be implemented without taking much time and effort. Others may require more time to learn to do so. The former is, for example, to create a glossary of the technical terms of a specific topic. In the case of my scholarly editing project, generating the list of substances used in alchemy out of all edited sources would be useful. As long as terms are tagged by the element such as <term type="substance">, XSLT can easily extract those words.

More difficult plans are implementing analyzing tools based on natural language theories or AI-related features. In terms of natural language processing, LSA (latent semantic analysis) is a good method for finding similar passages within a corpus. If we can use LLM (large language model) APIs in a web application, we can analyze the corpus more flexibly. Of course, since LLMs are not always accurate, their use should be limited to a heuristic tool.

Conclusion

Many historians would think that developing one’s own web application to render TEI-edited primary sources is an unfeasible task. This represents a major obstacle to the creation of digital editions for most scholars. That is, due to the poor readability of TEI code, it is almost impossible to use it to consult primary sources. Only after it is rendered into a reader-friendly format do TEI editions become usable sources to refer to. Therefore, unless we can reduce the effort required to develop rendering applications, wider adoption of TEI among scholars is likely to remain challenging. This paper demonstrates a practical and reproducible method for integrating TEI and modern front-end frameworks with minimal technical overhead. Developing the web application with Vue.js could at least make scholars feel less overwhelmed, though many of them might still hesitate to try. Even those who might still hesitate to develop web applications can take advantage of the recent availability of LLM chatbots, which can assist with some of the most time-consuming tasks, such as coding. The more digital scholarly editions are created, the more we can analyze primary sources using computational methods, leading to new insights into historical sources.