Astelar turns specifications, architecture notes and API references into a single continuous narrative. Readers start with why the system exists and descend, at their own pace, to how every endpoint behaves.
Narrative documents and technical docs share a routing model, a type scale and a search index.
Progressive depth
An investor reads four screens. An engineer keeps scrolling into schemas, limits and failure modes.
Authored in MDX
Every layout on this site is a component. Writers compose pages; the system holds the craft.
Contents
06 sections
01The productWhy documentation is the first surface of a product, and what Astelar changes.8 min
02ArchitectureThe content pipeline from source repository to rendered page.12 min
03API referenceProjects, documents, builds and the search index, with worked examples.Reference
04GuidesInstall the SDK, model a document set, deploy to your own domain.14 pages
05ChangelogEvery release since the first private build, in one continuous timeline.2024—
06The visionNarrative engineering: one knowledge graph, every audience, every output.Manifesto
Bring your own repository.
Point Astelar at a folder of Markdown and an OpenAPI schema. The first build takes about ninety seconds.
Get started
Documentation
Introduction
Astelar is a documentation platform for teams whose product is difficult to explain in a paragraph. It holds narrative documents and technical references in the same system, so a reader can move from a manifesto to a request schema without leaving the page.
How a project is structured
Every Astelar project is a tree of documents. A document is MDX: prose, components, and frontmatter that declares where it belongs. There is no separate CMS and no separate marketing site.
Setting depth: 'progressive' tells the renderer to collapse reference material behind the narrative until the reader asks for it. Nothing is hidden from search or from crawlers.
The first build
folios — zsh
$ astelar init
✓ 2 sources detected — content/, openapi.yaml
$ astelar build
✓ Compiled 214 documents in 8.4s ▍
Where to go next
Architecture
How sources become pages.
API reference
Projects, documents, builds.
01 — Product
The first thing anyone reads is the documentation.
Before a demo, before a call, someone opens the docs to decide whether your system is serious. That page is doing the work of a pitch, and almost nobody designs it that way.
The problem
Most teams run two systems. A marketing site holds the story and gets design attention. A docs site holds the truth and gets none. The two drift, and the reader pays for it — the story oversells, the reference under-explains, and neither answers the question the reader actually arrived with.
The approach
Astelar treats both as one document with a depth axis. The top of that axis is narrative: what the system is for, what it refuses to do, who it is built for. The bottom is exhaustive: schemas, limits, error codes, migration notes. The reader chooses their altitude and the layout follows.
ALTITUDE 1
Narrative
Vision, positioning, case studies. Four screens, no jargon.
ALTITUDE 2
System
Architecture, data model, guarantees, trade-offs made explicit.
ALTITUDE 3
Reference
Endpoints, types, quotas, changelog. Generated, never hand-copied.
What it is not
Astelar is not a wiki, and it is not a page builder. Content lives in your repository and moves through review like code. The platform's job is rendering, indexing and pacing — not storage.
“We stopped maintaining a marketing site. The overview page is the top of our docs now, and it converts better than the thing it replaced.”
Head of Engineering — Folios
02 — Architecture
The content pipeline
Four stages run between a commit and a rendered page. Each is idempotent and independently cacheable, so an edit to one document rebuilds one document.
SOURCE
Ingest
Git webhook pulls MDX, OpenAPI and assets. Frontmatter is validated against the project schema.
PARSE
Compile
MDX compiles to a serialisable tree. Components resolve against the registered library; unknown tags fail the build.
INDEX
Index
Headings, prose and endpoint metadata are written to a single index with altitude scores attached.
EDGE
Serve
Static shells go to the edge; search and interactive blocks hydrate on demand.
● p50 build 8.4s● incremental per document● full rebuild ~90s
Guarantees
Build determinism
The same commit produces byte-identical output. Builds are cached by content hash.
Reference accuracy
Endpoint pages are generated from the schema. Prose may annotate them; it cannot contradict them.
No dead links
Internal links resolve at compile time. A broken reference fails the build rather than the reader.
03 — Reference
Documents API
Create, read and publish documents. All requests are authenticated with a project token and return JSON.
POST/v1/documents
Creates a document in a project. The body is MDX; frontmatter determines placement in the tree. Returns the compiled document with a build id.
Body parameters
project_idstringrequired
Identifier of the project that owns the document.
contentstringrequired
MDX source, up to 512 KB. Components must be registered in the project library.
altitude1 | 2 | 3
Depth band used for pacing and search ranking. Inferred from frontmatter when omitted.
publishboolean
Publish immediately after a successful build. Defaults to false.
Errors
422Unknown component or invalid frontmatter. The build log is returned in detail.
429More than 60 builds per minute for one project.
Diagrams are a first-class element in Astelar, not an export from a modelling tool. Each family has one job, one visual grammar, and renders as responsive SVG. The diagram type fits the story: a sequence never looks like an org chart.
Editorial before technical
A diagram earns its place by explaining, not by being complete.
Every line has meaning
Fine strokes, thin connectors, glow reserved for the one node that matters.
One grammar
Shared node shapes, type and motion across all families — readable in docs and on stage.
01
Ecosystem map
How products relate. One parent, its platforms, and what each carries.
02
Layered architecture
Infrastructure as strata. Depth increases downward; the external boundary is drawn, not implied.
03
Sequence
A request in time. One CFDI stamp, from checkout to government validation and back.
04
Financial flow
Money in motion. Every hop is observable; the ledger is the source of truth.
05
Motion language
Motion communicates depth, not decoration. Every animation must answer one of four questions; anything else is cut.
Where am I?
Ambient backgrounds drift over a minute; each chapter has its own light.
What changed?
Diagrams construct themselves — node, connection, label, then flow.
What's connected?
Pulses trace real request paths; a line only glows when data moves on it.
What next?
Reveals pace the reading downward; nothing animates continuously in view.
Renderers
Authors declare intent in MDX; Astelar picks the most expressive renderer, or the author overrides it.
svg
Custom SVG in the house grammar. The default for anything a reader will remember.
DEFAULT
svg.animated
Motion on scroll for hero diagrams. Flow lines, staged reveals, nothing gratuitous.
HERO
d2
Declarative architecture diagrams, re-themed to the house style at build time.
ARCHITECTURE
graphviz
Dependency graphs too large to draw by hand. Layout is computed, style is ours.
GRAPHS
mermaid
Quick, editable diagrams during drafting. Promoted to svg before publishing.
DRAFTS
sketch
Hand-drawn style for early concepts, so unfinished thinking looks unfinished.
CONCEPTS
In MDX: <Diagram family="sequence" renderer="svg.animated" src="./cfdi-stamp.d2" /> — the family sets the grammar, the renderer sets the medium.
05 — Changelog
Releases
Every change since the first private build. Entries are generated from release tags and annotated by the team.
{{ r.version }}{{ r.date }}
{{ r.title }}
{{ r.body }}
{{ t }}
FOLIOS — A FILM IN FIVE SCENES
The
Final
Seal.
Every transaction deserves one. This is the story of the 41 seconds nobody sees.
SCROLL
What happens in the 41 seconds after a guest checks out?
SCENE I — THE MAP IS THE DOCUMENTATION
This diagram is not a picture.
Click any node — it opens its chapter.
Guest
CHAPTER 01
HostCasa
PRODUCT
CFDI Engine
API REFERENCE
SAT
DIAGRAM LANGUAGE
XML + PDF
CHANGELOG
Ledger
ARCHITECTURE
SCENE II — 41 SECONDS, SIDEWAYS
The timeline runs the other way.
DRAG →
01
The folio closes
A stay becomes a bill. HostCasa fires one event and steps out of the way.
T+0.0s
02
The guest scans
A QR on the receipt opens the portal. The RFC validates as it is typed — errors die at the keyboard.
T+12s
03
The seal
Folios composes the CFDI, the PAC stamps it, SAT records it. Idempotent; retries are free.
T+29s
04
The inbox
XML and PDF arrive before the taxi does. The ledger already balanced itself.
T+41s — MEDIAN
SCENE III — THE SYSTEM, BREATHING
These numbers are alive right now.
STAMPING UPTIME
{{ uptime }}%
INVOICES SEALED TODAY
{{ stamps }}
LAST UUID
{{ uuid }}
STAMPED ✓
“I've never seen software explained like this.”
Engineering Cinema.
Watch Chapter 01
Read the docs
Manifesto
Narrative engineering.
Not docs. Not a wiki. A medium. Astelar compiles what a team knows into experiences every audience can read — documentation becomes compiled, not rendered.
Modes reweight the same knowledge graph — nothing is rewritten, nothing can drift. Reading becomes conversational: ask for a CTO summary, only the diagrams, or a slide deck, and the publication engine answers from the same source.
A category, not a competitor:
Astelar manages understanding.
Read Chapter 01 — Folios
Chapter 01
The Beginning
Every transaction leaves a trace. Every trace deserves trust.
SCROLL
Every reservation ends with trust.
Folios is the invoice engine behind HostCasa — the final seal of every stay. A guest scans a code; a legally valid CFDI arrives before they reach the lobby door.
Compliance was designed for accountants, not for guests.
In Mexico, every stay can end with a fiscal invoice — an RFC, a CFDI, a stamped XML filed with the tax authority. Hotels handle this with a desk, a form and a three-day wait. The most reliable moment to get it right, the checkout itself, is the moment everyone ignores.
Vision
Invoicing is part of checkout, not paperwork after it.
Folios treats the invoice as the last step of the guest experience. Validation happens while the guest types; stamping happens in the seconds between payment and receipt. Nothing waits for later, because later is where compliance fails.
Architecture
Seven hops, one promise.
TicketFOLIO CLOSED
QR PortalGUEST SCANS
RFC ValidationLIVE, AS TYPED
CFDI EngineFOLIOS CORE
TimbradoPAC STAMP
SATGOVERNMENT LEDGER
XML + PDFTO GUEST EMAIL
MEDIAN, SCAN TO INBOX — 41 SECONDS
Implementation
One call closes the folio.
HostCasa calls Folios when the folio closes. Everything after — validation, stamping, delivery — is Folios’ responsibility, observable through build events.
Create, cancel, reissue. Each carries its CFDI, UUID and delivery state.
fiscal_profiles
Validated RFCs with usage defaults, reusable across every stay.
Future
From invoices to the whole money story.
The ledger already sees every peso move. Owner statements, revenue analytics and tax provisioning are chapters Folios has not written yet — the sequence diagram just gets longer.