# Working for a new openEHR specifications website with Antora

**Category:** [Specifications](https://discourse.openehr.org/c/specifications/6)
**Created:** 2026-01-18 22:00 UTC
**Views:** 52
**Replies:** 1
**URL:** https://discourse.openehr.org/t/working-for-a-new-openehr-specifications-website-with-antora/11694

---

## Post #1 by @sebastian.iancu

Hello everyone,

I’d like to share an update on ongoing work on a new **openEHR specification website**, built and rendered using **Antora**.

This effort has been a fairly complex one, the topic was discussed in SEC (Specification Editorial Committee) during the past year, and over the last months I’ve worked the details together with @SevKohler to turn those discussions into a concrete, working implementation.

**What this is about?** 
The goal is to provide a more maintainable, navigable, and future-proof way of publishing the openEHR specifications.
* The site static content is generated with [Antora](https://antora.org/), a documentation site generator designed for large, multi-repository documentation sets.
* Antora is based on [AsciiDoc](https://asciidoc.org/) format, which allows specifications to be written in a structured, modular, and versioned way, while still producing high-quality HTML output - this is format however is still the same as we have it now.
* This approach separates content, structure, and presentation, which is particularly important for specifications that evolve over time.

**Model foundation changes**

A key underlying change is that some of the specification content which was historically derived from **UML models** has now been **migrated to BMM (Base Meta-Model)**.

* BMM now acts as the authoritative, machine-readable source of model semantics.
* The rendered specification pages consume this BMM-based information.
* This data forms the foundation for the **class definition views**, which are presented in the site as **tabbed sections** (e.g. attributes, constraints, inheritance, etc.).

The current development version is publicly available here: [https://sebastian-iancu.github.io/antora-openehr](https://sebastian-iancu.github.io/antora-openehr). However, this is far for being ready to replace the current website: several links are likely broken, the UI and styling is still the default of Antora, some landing pages are missing, etc. - but you can get an impression about the possibilities & features. For instance: a much evolved search box, better navigation, smaller pages by splitting the old ones, useful tabs, with more class definition information.

**Feedback requested**

At this stage, I’d like to promote the site to actively request feedback. In particular, I’m very interested in opinions on:

* The **overall structure and readability** of the specification pages
* The way **class definitions are rendered using tabs**
* The **navigation** options - see hyperlinks to switch specification components or versions on the left side of the page footer
* Does this improve clarity?  Is important information harder or easier to discover compared to previous representations?

Any feedback -conceptual, editorial, or technical is very welcome and will help guide the next iteration of this work. Thanks in advance for taking a look, and for any thoughts you’re willing to share.

Best regards,
Sebastian

---

## Post #2 by @joostholslag

 I like the navigator between specifications. 
But it’s rather hidden, could it be put on top? And ideally integrated with some of the other navigation elements. Archeype model is now in three places and version in 2. I would prefer a single place for both. 
![image|375x500](upload://yNS8uknrX2D8AY8kSOO8xrLGEqB.jpeg)

One issue is the outline of class definition table is incorrect for ‘functions’:

![image|344x500](upload://vPuwbZ7ZTEUyxo4pTjLLivnLdNg.png)

(iPad pro 11”, safari, request desktop site, zoom minimal( different zoom level doesn’t effect the issue). 

Also the space usage for menu vs content vs right hand side quick navigation isn’t ideal. With a portrait layout I would like to hide the quick nav. This is probably anthora and hard to customise?

Anther issue is figures aren't rendered. eg Figure 2. Archetype HRID Structure.

---


**Canonical:** https://discourse.openehr.org/t/working-for-a-new-openehr-specifications-website-with-antora/11694
**Original content:** https://discourse.openehr.org/t/working-for-a-new-openehr-specifications-website-with-antora/11694