codexa 0.0.3

A Git-native content compiler for building typed public and private knowledge artifacts.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135

---
schema: codexa.document@2
id: codexa.guides.quick-start
title: Codexa Quick Start
description: Organize a Git repository, author compatible Markdown, validate links, and build endpoint artifacts.
kind: guide
status: active
visibility: public
tags:
  - codexa
  - quick-start
  - markdown
  - git
navigation:
  root: docs
  product: codexa
  section: Guides
  order: 10
distribution:
  notion: true
  web: public
  obsidian: true
notion:
  workspace: codexa
web:
  slug: /docs/codexa/guides/quick-start
---

# Codexa Quick Start

Codexa reads Markdown documents from one or more Git repositories and emits a shared bundle plus endpoint-specific artifacts. The repositories remain authoritative; generated output is disposable.

## 1. Organize the repository

A typical documentation subtree looks like this:

```text
docs/
├── index.md
├── guides/
│   └── quick-start.md
├── concepts/
└── reference/
```

The physical folder layout helps humans and GitHub users. The canonical navigation tree comes from frontmatter.

## 2. Add required frontmatter

Every Codexa source document begins with YAML frontmatter using `codexa.document@2`:

```yaml
---
schema: codexa.document@2
id: example.guides.quick-start
title: Example Quick Start
description: Configure and build the example repository.
kind: guide
status: active
visibility: public
tags:
  - example
navigation:
  root: docs
  product: example
  section: Guides
  order: 10
distribution:
  notion: true
  web: public
  obsidian: true
notion:
  workspace: codexa
web:
  slug: /docs/example/guides/quick-start
---
```

See [[codexa.reference.frontmatter|required and optional frontmatter fields]] for the full contract.

## 3. Link documents by stable ID

Use logical links instead of relative file paths:

```md
[[codexa.reference.frontmatter]]
[[orbexa.guides.quick-start|Orbexa Quick Start]]
```

Codexa validates the target IDs across every source repository supplied to the build. See [[codexa.concepts.navigation-and-links|Navigation and Links]].

## 4. Validate repositories

```bash
codexa validate \
  --source-root "$MATRIX/crates/codexa" orbyts/codexa \
  --source-root "$MATRIX/crates/orbexa" orbyts/orbexa
```

Validation rejects unsupported schemas, duplicate document IDs, malformed logical links, and links to missing documents.

## 5. Build artifacts

```bash
codexa build \
  --source-root "$MATRIX/crates/codexa" orbyts/codexa \
  --source-root "$MATRIX/crates/orbexa" orbyts/orbexa \
  --output dist
```

The build produces:

```text
dist/
├── bundle.json
├── notion/
│   ├── manifest.json
│   └── pages/
└── web/
    ├── manifest.json
    └── pages/
```

## 6. Publish to an endpoint

Codexa does not call Notion or deploy a website. Endpoint tools consume its artifacts.

For Notion:

```bash
orbexa init
orbexa apply dist/notion
```

Continue with [[orbexa.guides.quick-start|Orbexa Quick Start]]. Loomara will consume the web artifacts using the same document IDs, navigation tree, and links.