Documentation

Overview

Two products share one rendering engine, so they produce the same articles:

• The editor - a real-time collaborative editor running on a Hugging Face Space. Zero setup: duplicate, sign in with your HF account, invite co-authors, publish in one click.
• The template - an Astro + MDX repository. Write chapters in MDX, craft D3 embeds by hand, version everything with git, deploy as a Docker Space.

Both give you KaTeX math, BibTeX citations, footnotes, interactive D3.js figures, automatic dark mode, brand-color theming, PDF export and an LLM-readable twin of the article at /llms.txt.

Editor or template?

You can start in the editor and graduate to the template later - the article format is the same.

Editor - quickstart

1. Open the editor Space and use the "..." menu, Duplicate this Space.
2. Sign in with Hugging Face OAuth - no API key to configure.
3. Share your Space URL with co-authors: anyone who signs in can join the document and edit live.

Documents autosave continuously and persist to a Hugging Face dataset in your namespace, so your writing survives Space restarts and rebuilds.

Editor - writing together

Collaboration is powered by Y.js CRDTs: every author sees live cursors and per-user colors, and concurrent edits merge without conflicts. On top of that:

• Comments - anchor a thread on any selection, resolve inline.
• AI assistant - ask for rewrites or content edits in a chat; it runs on your own HF Inference Providers quota.
• Blocks - math, code, tables, images, HTML embeds, footnotes and citations, reorderable by drag and drop.

Editor - AI embed studio

Describe a figure in plain language - or paste a CSV - and the studio generates a self-contained D3 embed, live in your article. Iterate in a chat loop until it looks right.

• Works from a prompt, a dataset, or both.
• The output is plain HTML + D3 you own and can edit by hand.
• Generated embeds follow the template's conventions (theme variables, ColorPalettes), so they retint with your brand color and dark mode automatically.

Editor - publishing

One click produces, in 15-25 seconds, while others keep editing:

• a static HTML page ready to share,
• a print-ready PDF with full typography,
• a social thumbnail captured automatically,
• a Markdown twin at /llms.txt, advertised in robots.txt.

Template - installation

The fastest way is the CLI (requires Node.js 20+):

# scaffold a new paper (interactive)
npx create-research-article my-paper

# or pick a layout directly
npx create-research-article my-paper --template=article
npx create-research-article my-paper --template=paper

cd my-paper/app
npm run dev   # http://localhost:4321

The CLI walks you through title, authors and affiliations, and can create and deploy a Hugging Face Space for you if huggingface-cli is installed. Alternatively, duplicate the template Space and clone it:

git clone git@hf.co:spaces/<you>/<your-space>
cd <your-space>/app
git lfs install && git lfs pull
npm install && npm run dev

Template - variants

Choose the layout in the article.mdx frontmatter:

template: "article"  # full: banner, sidebar TOC, figure numbering, citations, PDF
template: "paper"    # lighter: centered single column, link pills

The paper variant supports external links rendered as pill buttons (Paper, Code, Demo, Data...). Long titles are auto-balanced; force a break with \n:

title: "Why Open-Source LLMs\nAre Reshaping the AI Landscape"
links:
  - label: "Paper"
    url: "https://arxiv.org/abs/..."
  - label: "Code"
    url: "https://github.com/..."

Template - deploy & sync

Push to a Docker Space to build and deploy automatically:

# create a Docker Space at huggingface.co/new-space, then:
git remote add space git@hf.co:spaces/<you>/<your-space>
git push space main

A [slugified-title].pdf and a thumb.jpg are generated at build time. Serving dist/ from any static host works too. To pull the latest template improvements without touching your content:

npm run sync:template -- --dry-run   # preview
npm run sync:template                # update (preserves src/content/)

Article structure

Your article lives in app/src/content/. The entry point is article.mdx: frontmatter (title, authors, affiliations, DOI, template variant...) plus imported chapters:

# app/src/content/article.mdx
---
title: "My paper"
authors:
  - name: "Ada Lovelace"
    url: "https://huggingface.co/ada"
    affiliations: [1]
affiliations:
  - name: "Analytical Engines Lab"
published: "Aug 8, 2026"
template: "article"
---

import Introduction from "./chapters/introduction.mdx";

<Introduction />

Chapters are plain .mdx files in src/content/chapters/; the table of contents is generated from your headings.

Markdown & math

• Math - KaTeX: $e^{i\pi} + 1 = 0$ inline, $$...$$ for display equations.
• Citations - BibTeX entries in bibliography.bib, cited with [@vaswani2017attention] or grouped [@a; @b]. Pick the style (APA, IEEE, Vancouver...) in the frontmatter.
• Footnotes - [^note] with definitions anywhere in the file; they support math and citations.
• Mermaid - fenced ```mermaid blocks render as diagrams.
• Code, tables, audio - syntax-highlighted code blocks, GFM tables, audio players from local files.

Below, an actual rendered snippet - KaTeX equation, citation and footnote - exactly as it comes out of the engine. The markdown chapter of the demo shows every feature live.

Components

Import what you need at the top of any chapter:

import Note from "../../components/Note.astro";
import HtmlEmbed from "../../components/HtmlEmbed.astro";

A few of them, rendered right here (the accordion really opens):

The components chapter demonstrates each one live.

Interactive figures

Figures are self-contained .html files in src/content/embeds/: one root <div>, a scoped <style> and an IIFE <script> (D3 loaded from a CDN). Drop them into a chapter with:

<HtmlEmbed
  src="my-chart.html"
  title="Figure title"
  desc="Caption text"
  config={{ smoothing: true }}
/>

• Data files (CSV/JSON) go in src/content/assets/data/ and are served under /data/.
• config is passed to the embed via a data-config attribute - reusable embeds like the generic line chart read it.
• Embeds are theme-aware by convention: colors come from CSS variables and window.ColorPalettes, never hardcoded.

This is the demo article's generic line chart, running live from the exact HtmlEmbed call above (try the zoom and the smoothing toggle):

The gallery on the home page runs three more embeds from the demo article.

Colors & dark mode

One variable drives the whole article: --primary-color (an OKLCH color). Categorical, sequential and diverging palettes are derived from it at runtime:

const cat = window.ColorPalettes.getColors("categorical", 8);
const seq = window.ColorPalettes.getColors("sequential", 8);
const div = window.ColorPalettes.getColors("diverging", 7);

// change the brand color, notify listeners
document.documentElement.style.setProperty("--primary-color", "#6D4AFF");
window.ColorPalettes.refresh();

Embeds can listen to the palettes:updated event to retint themselves live. Dark mode flips automatically with the reader's system preference (data-theme on the root element); text, axes and surfaces use CSS variables so everything follows.

Drag the hue: the figure below re-derives its palette in real time.

Import LaTeX / Notion

The template ships importers to bootstrap an article from existing sources:

• LaTeX - converts sections, math, citations and figures to MDX chapters.
• Notion - pulls a shared page through a Notion integration token, locally or directly on the Space.

Setup details live in the import chapter of the demo.

Help & links

• Demo article - the full reference, written with the template itself.
• Editor Space - try or duplicate the collaborative editor.
• GitHub repository - source, issues and discussions.
• Report an issue - bugs and feature requests welcome.
• Community gallery - real articles published with the engine.