This is the release notes for Cristal.

The main changes of this release are:

• A rework of the page storage format. Pages are now stored as markdown which makes them more easily accessible and readable outside Cristal.
• A replacement for the prototype extension required for XWiki integration.
• Preliminary support for client-side macros.

New and Noteworthy (since Cristal 0.19)

Full list of issues fixed and Dashboard for 0.19.

For Users

• Mardown storage: Until now, document storage was based on json files stored on a physical or virtual file system.

  With this release, pages are stored as markdown files with a front-matter describing meta-data.

  Attachments are stored in hidden directories with the same name as the page without its extension. For instance for page space/mypage, the mardown is stored in space/mypage.md, and an attachment image.png in space/.mypage/attachments/image.png

  WarningWe do not provide migration support from the old format.

  Example:

  ---
  name: My Page Title
  ---
  
  This is the content of the **page**.
  

• Initial macros support: Client-side macros are now supported. A macro is defined as a custom block or inline content that can be behave and render in a custom way inside the BlockNote editor. Macros:

  • Can be inserted using the slash menu
  • Are rendered like normal elements, can be copy-pasted, and be dragged around in the editor
  • Have parameters to customize them (for instance, an alert may have the type of alert such as "warning" or "info" as a parameter)
  • Are persisted, along with their parameters, in documents

  Due to current limitations with the editor, macros are read-only and cannot have nested content.

• Remove multi-column support: Support for multi-column was removed, alongside the @blocknote/xl-multi-column package, due a license conflict.

  Note that multi-columns weren't persisted before, so this is not a major UX change.

For Admins

• New extension for XWiki integration: A new XWiki extension has been released to support integration with an XWiki instance. This replaces the existing prototype extension that can now be safely uninstalled from now on.

  Please note that previous Cristal versions are not compatible with the new extension, while this release and future ones require it.

  Warning

  You will not be able to interact with XWiki instances that do not install this new extension.

  You can have a look at the updated setup instructions for the XWiki backend.

For Developers

Support for read-only, client-side macros

 
The c-blocknote-view component's editorProps property now has a macros field which enables registering custom macros into the editor.

That same package exposes a DEFAULT_MACROS object containing a set of common-use macros.

Macros can be automatically registered in the slash menu for easy insertion, and can hold a set of parameters. They are persisted through UniAst, and are currently supported in Markdown using XWiki's extended syntax (curly braces).

Rendering is performed through a React component.

Two macros are currently provided: XWikiMacroHTMLBlock and XWikiMacroInlineHTML, respectively a block and an inline content, taking a raw HTML string and a metadata string as parameters. The raw HTML is rendered as is, and the metadata is ignored but persisted in UniAst. The goal of these two macros is to allow rendering server-side XWiki macros using their generated HTML, and perserve the parameters they were built with.

Collaboration extension

 
A new Collaboration API is now available. It allows resolving a collaboration provider by collaboration.

This automatic resolution is not mandatory, and individual collaboration managers can be resolved manually when a dynamic resolution is not required.

Two providers are also made available HocusPocus (the current default until now) and XWiki (client for Yjs).

Page extension

 
A new page extension allows reading and writing markdown pages in a standardized format.

c-blocknote-view takes a collaboration provider instead of a server url

 
The main vue template from Blocknote Headless now expects a collaboration provider instead of an url for real-time collaboration.

Example:

<script setup lang="ts">
import { collaborationManagerProviderName } from "@xwiki/cristal-collaboration-api";
import type {
  CollaborationInitializer,
  CollaborationManagerProvider,
  User,
} from "@xwiki/cristal-collaboration-api";
const collaborationManager = container
    .get<CollaborationManagerProvider>(collaborationManagerProviderName)
    .get();
const collaborationProvider = await collaborationManager.get();
</script>
<template>
  <CBlockNoteView
    ref="editorInstance"
    :editor-props
    :editor-content
    :container
    :collaboration-provider="collaborationProvider"
    @instant-change="saveStatus = SaveStatus.UNSAVED"
    @debounced-change="save"
  />
</template>

Miscellaneous

• User id getter: The authentication API now provides a getUserId method returning synchronously the id of the current user.

• saved attachements can be resolved to a new url: The saveAttachments method from Storage can now return resolved URLs for the newly uploaded attachments.

Upgrades

Security Issues

Security issues are not listed in issue lists or dashboards to avoid disclosing ways to use them, but they will appear automatically in them once they're disclosed. See the XWiki Security Policy for more details.

Known issues

• Bugs we know about

Credits