Skip to content

Commit 91e2a27

Browse files
rowanc1rowanc1
authored
🦸 Docs hero section (#35)
1 parent edef257 commit 91e2a27

7 files changed

Lines changed: 319 additions & 5 deletions

File tree

‎docs/hero.webp‎

582 KB
Loading

‎docs/index.md‎

Lines changed: 12 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,19 @@
11
---
22
title: OXA Schema
3+
site:
4+
hide_outline: true
5+
hide_title_block: true
36
---
47

5-
> **A foundation for interoperable, structured scientific content.**
6-
> OXA defines open, extensible JSON schemas that describe modular and composable scientific documents — bridging the gap between authoring systems like **Stencila**, **MyST**, **Quarto** and the scientific publishing ecosystem which uses tools like **JATS**.
7-
8-
## Overview
8+
:::{hero .col-screen} OXA Documentation
9+
:background-image: hero.webp
10+
:max-width: 100
11+
:overlay: 60
12+
:kicker: Open Exchange Architecture
13+
:actions: [Get Started](./install.md) [Schema](./schema-overview.md)
14+
:footer: OXA defines open, extensible JSON schemas that describe modular and composable scientific documents — bridging the gap between authoring systems like Stencila, MyST, Quarto and the scientific publishing ecosystem which uses tools like JATS.
15+
A foundation for interoperable, structured scientific content.
16+
:::
917

1018
The **Open Exchange Architecture (OXA)** is a specification for representing scientific documents and their components as structured JSON objects.
1119
It’s designed to enable **exchange, interoperability, and long-term preservation** of scientific knowledge, while remaining compatible with modern web and data standards.

‎docs/install.md‎

Lines changed: 189 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,189 @@
1+
---
2+
title: Get Started
3+
---
4+
5+
OXA provides tools and libraries for working with OXA documents in multiple languages. This guide will help you get started quickly.
6+
7+
## Installation
8+
9+
### Command Line Tool
10+
11+
The OXA CLI tool allows you to validate OXA documents from the command line.
12+
13+
::::{tab-set}
14+
:::{tab-item sync=js} NPM
15+
16+
```bash
17+
npm install -g oxa
18+
```
19+
20+
:::
21+
22+
:::{tab-item sync=py} Python
23+
24+
```bash
25+
pip install oxa
26+
```
27+
28+
:::
29+
::::
30+
31+
## Quick Start
32+
33+
### Validate a Document
34+
35+
Once installed, you can validate OXA documents:
36+
37+
```bash
38+
# Validate a JSON file
39+
oxa validate document.json
40+
41+
# Validate multiple files
42+
oxa validate *.json
43+
44+
# Validate from stdin
45+
cat document.json | oxa validate -
46+
47+
# Validate YAML files
48+
oxa validate document.yaml
49+
50+
# Validate against a specific node type
51+
oxa validate --type Heading heading.json
52+
53+
# Quiet mode (only show errors)
54+
oxa validate -q *.json
55+
```
56+
57+
### Example Document
58+
59+
Create a simple OXA document in `example.json`:
60+
61+
```json
62+
{
63+
"type": "Document",
64+
"children": [
65+
{
66+
"type": "Heading",
67+
"level": 1,
68+
"children": [
69+
{
70+
"type": "Text",
71+
"value": "Hello, OXA!"
72+
}
73+
]
74+
},
75+
{
76+
"type": "Paragraph",
77+
"children": [
78+
{
79+
"type": "Text",
80+
"value": "This is a simple OXA document."
81+
}
82+
]
83+
}
84+
]
85+
}
86+
```
87+
88+
Validate it:
89+
90+
```bash
91+
oxa validate example.json
92+
```
93+
94+
## Programmatic Libraries
95+
96+
For programmatic usage in your applications, install the appropriate library for your language:
97+
98+
::::{tab-set}
99+
:::{tab-item sync=js} JavaScript/TypeScript
100+
101+
```bash
102+
# Core validation library
103+
npm install @oxa/core
104+
105+
# TypeScript type definitions
106+
npm install oxa-types
107+
```
108+
109+
:::
110+
111+
:::{tab-item sync=py} Python
112+
113+
```bash
114+
pip install oxa-types
115+
```
116+
117+
:::
118+
119+
:::{tab-item sync=rs} Rust
120+
121+
Add to your `Cargo.toml`:
122+
123+
```toml
124+
[dependencies]
125+
oxa-types = "0.1.0"
126+
```
127+
128+
:::
129+
::::
130+
131+
### Using the Programmatic API
132+
133+
::::{tab-set}
134+
135+
:::{tab-item sync=js} JavaScript/TypeScript
136+
137+
```typescript
138+
import { validate } from "@oxa/core";
139+
import type { Document } from "oxa-types";
140+
141+
const document: Document = {
142+
type: "Document",
143+
children: [
144+
{
145+
type: "Paragraph",
146+
children: [{ type: "Text", value: "Hello, world!" }],
147+
},
148+
],
149+
};
150+
151+
const result = validate(document);
152+
if (result.valid) {
153+
console.log("Document is valid!");
154+
} else {
155+
console.error("Validation errors:", result.errors);
156+
}
157+
```
158+
159+
:::
160+
161+
:::{tab-item sync=py} Python
162+
163+
```python
164+
from oxa_types import Document, Paragraph, Text
165+
166+
document = Document(
167+
children=[
168+
Paragraph(
169+
children=[
170+
Text(value="Hello, world!")
171+
]
172+
)
173+
]
174+
)
175+
```
176+
177+
:::
178+
::::
179+
180+
## Next Steps
181+
182+
- Learn about the [OXA Schema](./schema.md) structure
183+
- Explore the [Schema Reference](./schema/index.md) for detailed node types
184+
- Check out examples in the [OXA repository](https://github.com/oxa-dev/oxa)
185+
186+
## Getting Help
187+
188+
- Join the [Discord community](https://discord.oxa.dev)
189+
- Report issues on [GitHub](https://github.com/oxa-dev/oxa)

‎docs/myst.yml‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,10 +11,16 @@ project:
1111
AST: Abstract Syntax Tree
1212
JATS: Journal Article Tag Suite
1313
JSON: JavaScript Object Notation
14+
CLI: Command Line Interface
15+
API: Application Programming Interface
1416
toc:
1517
- file: index.md
18+
- file: install.md
19+
- file: schema-overview.md
1620
- title: Schema Reference
1721
children:
1822
- pattern: schema/*.md
1923
site:
2024
template: book-theme
25+
options:
26+
folders: true

‎docs/schema-overview.md‎

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
---
2+
title: Schema
3+
---
4+
5+
# OXA Schema
6+
7+
The OXA schema defines the structure and types for representing scientific documents as JSON objects. All OXA documents conform to JSON Schema Draft-07, enabling validation and interoperability.
8+
9+
## Schema Overview
10+
11+
Every OXA node follows a common structure:
12+
13+
```yaml
14+
type: NodeType # Required: The node type identifier
15+
id: optional-string # Optional: Unique identifier for referencing
16+
classes: [] # Optional: Styling or semantic classes
17+
data: {} # Optional: Arbitrary metadata
18+
children: [] # Optional: Nested content nodes
19+
```
20+
21+
### Common Properties
22+
23+
| Property | Type | Description |
24+
| ---------- | ---------------------- | --------------------------------------------------------- |
25+
| `type` | `string` (Capitalized) | The node type, e.g. `"Paragraph"`, `"Text"`, `"Heading"`. |
26+
| `id` | `string` | Unique identifier for referencing and linking nodes. |
27+
| `classes` | `array[string]` | Optional styling or semantic classes. |
28+
| `data` | `object` | Arbitrary metadata (e.g. attributes, provenance, DOI). |
29+
| `children` | `array` | Nested content nodes — block or inline types. |
30+
31+
## Node Types
32+
33+
OXA defines several categories of node types:
34+
35+
### Document Node
36+
37+
The root node of every OXA document:
38+
39+
- [Document](#oxa:document) — The root container with metadata, title, and block content
40+
41+
### Block Nodes
42+
43+
Block-level content that forms the document structure:
44+
45+
- [Heading](#oxa:heading) — Section headings with levels (1-6)
46+
- [Paragraph](#oxa:paragraph) — Text paragraphs
47+
48+
### Inline Nodes
49+
50+
Inline content that appears within block nodes:
51+
52+
- [Text](#oxa:text) — Plain text content
53+
- [Strong](#oxa:strong) — Strong emphasis (typically bold)
54+
55+
## Accessing the Schema
56+
57+
### Download the Schema
58+
59+
The OXA schema is available as a JSON Schema file:
60+
61+
<https://oxa.dev/v0.1.0/schema.json>
62+
63+
### Schema Versioning
64+
65+
OXA uses semantic versioning for schema releases. The current version is **0.1.0**. When accessing schemas programmatically, always specify the version:
66+
67+
```bash
68+
# Download specific version
69+
curl https://oxa.dev/v0.1.0/schema.json > schema.json
70+
```
71+
72+
## Design Principles
73+
74+
The OXA schema follows these design principles:
75+
76+
- **Open by design:** JSON Schema–based and CC0-licensed for reuse and extension
77+
- **Composable:** Each node is self-contained, typed, and can be nested or reused
78+
- **Interoperable:** Compatible with MyST Markdown, Stencila, Quarto, and similar formats
79+
- **Extensible:** Add new node types while preserving schema validation
80+
- **Typed & linked:** Everything has a clear `type`, optional `id`, and structured `data` field
81+
- **Modular:** Documents and components can link across projects
82+
- **Computational:** Built-in support for executable and interactive research components
83+
84+
## Related Resources
85+
86+
- [Get Started Guide](./install.md) — Installation and quick start
87+
- [Schema Reference](./schema/index.md) — Detailed node type documentation
88+
- [OXA Repository](https://github.com/oxa-dev/oxa) — Source code and examples

‎docs/schema/index.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
# Schema Reference
2+
3+
For detailed documentation on each node type, see the [Schema Reference](./schema/index.md):
4+
5+
- [Document](./schema/document.md) — Root document structure
6+
- [Block Nodes](./schema/block.md) — Block-level content types
7+
- [Inline Nodes](./schema/inline.md) — Inline content types
8+
- [Heading](./schema/heading.md) — Section headings
9+
- [Paragraph](./schema/paragraph.md) — Text paragraphs
10+
- [Text](./schema/text.md) — Plain text nodes
11+
- [Strong](./schema/strong.md) — Strong emphasis

‎scripts/lib/generate-docs.ts‎

Lines changed: 13 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,12 +5,13 @@
55
* directory, formatted for use in documentation sites.
66
*/
77

8-
import { mkdirSync, rmSync, writeFileSync, existsSync } from "fs";
8+
import { mkdirSync, rmSync, writeFileSync, existsSync, readFileSync } from "fs";
99
import { join } from "path";
1010

1111
import { loadMergedSchema } from "./schema.js";
1212

1313
const OUTPUT_DIR = join(import.meta.dirname, "../../docs/schema");
14+
const INDEX_FILE = join(OUTPUT_DIR, "index.md");
1415

1516
interface SchemaProperty {
1617
type?: string;
@@ -34,12 +35,23 @@ interface SchemaDefinition {
3435
}
3536

3637
export async function generateDocs(): Promise<void> {
38+
// Preserve index.md if it exists
39+
let indexContent: string | null = null;
40+
if (existsSync(INDEX_FILE)) {
41+
indexContent = readFileSync(INDEX_FILE, "utf-8");
42+
}
43+
3744
// Delete and recreate output directory
3845
if (existsSync(OUTPUT_DIR)) {
3946
rmSync(OUTPUT_DIR, { recursive: true, force: true });
4047
}
4148
mkdirSync(OUTPUT_DIR, { recursive: true });
4249

50+
// Restore index.md if it was preserved
51+
if (indexContent !== null) {
52+
writeFileSync(INDEX_FILE, indexContent);
53+
}
54+
4355
const schema = loadMergedSchema();
4456
const definitions = schema.definitions as Record<string, SchemaDefinition>;
4557

0 commit comments

Comments
 (0)