# Blasdoc

> Blasdoc renders Markdown as real Angular components at runtime. Content arrives as a string, is parsed through unified/remark into a strongly typed intermediate representation (the Blasdoc IR), and is rendered as actual Angular component instances — with property, event and two-way bindings, `{{ interpolation }}`, `@if`/`@for`/`@switch`, live previews and Shiki syntax highlighting. Angular-first, never JSX. Open source, MIT licensed.

Every documentation page below is also available as plain Markdown: append `.md` to its URL (for example https://blasdoc.dev/docs/introduction.md).

## Overview

- [Home](https://blasdoc.dev/): Blasdoc renders Markdown as real Angular components at runtime: bindings, control flow, live previews and syntax highlighting, from one intermediate representation.
- [Documentation](https://blasdoc.dev/docs/introduction): Guides and reference for every Blasdoc feature.
- [Components](https://blasdoc.dev/docs/components): Angular components inside Markdown — registration, children, and how a tag is told apart from HTML.
- [Theme studio](https://blasdoc.dev/themes): Build a Blasdoc theme from presets and take away the CSS.
- [Updates](https://blasdoc.dev/updates): Release notes, newest first.

## Get started

- [Introduction](https://blasdoc.dev/docs/introduction): What Blasdoc is, what it is not, and the idea it is built on.
- [Installation](https://blasdoc.dev/docs/installation): Packages, providers and the build integration, step by step.
- [Quick start](https://blasdoc.dev/docs/quick-start): A page rendering real components, in three files.
- [Angular, Nx and Analog](https://blasdoc.dev/docs/frameworks): The same library in all three, and what differs in the wiring.

## Writing content

- [Markdown](https://blasdoc.dev/docs/markdown): Every Markdown and GFM construct Blasdoc renders.
- [Components](https://blasdoc.dev/docs/components): Angular components inside Markdown: registration, children, and how a tag is told apart from HTML.
- [Bindings](https://blasdoc.dev/docs/bindings): Attributes, property bindings, events and two-way — the four Angular channels, kept apart.
- [Interpolation](https://blasdoc.dev/docs/interpolation): Reading the context from the prose itself.
- [Control flow](https://blasdoc.dev/docs/control-flow): Angular block syntax in Markdown: @if, @for and @switch.
- [Lazy components](https://blasdoc.dev/docs/lazy-components): Fetching a component only when a document asks for it.

## Pages

- [Pages](https://blasdoc.dev/docs/pages): A `.md` file as an Angular component template, with `templateMD`.
- [Routing](https://blasdoc.dev/docs/routing): Lazy routes, titles and deep links for a page.
- [Page styles](https://blasdoc.dev/docs/page-styles): `styleUrl` reaching the rendered Markdown, and staying scoped.

## Code blocks

- [Code blocks](https://blasdoc.dev/docs/code-blocks): Syntax highlighting, fence meta, line numbers and titles.
- [Code groups](https://blasdoc.dev/docs/code-groups): Several fences as keyboard-navigable tabs.
- [Live previews](https://blasdoc.dev/docs/live-previews): A running component beside the source that produced it.
- [Syntax themes](https://blasdoc.dev/docs/themes): Registering Shiki themes, choosing one, and contrast.

## Theming

- [Theming](https://blasdoc.dev/docs/theming): Every value is a CSS custom property. Re-skin without forking.
- [Built-in components](https://blasdoc.dev/docs/components-reference): Callout, code group and code preview, and how to replace them.
- [Headless directives](https://blasdoc.dev/docs/headless): Your markup, Blasdoc behaviour: tabs, copy, mode and keyboard.

## Advanced

- [Diagnostics](https://blasdoc.dev/docs/diagnostics): Structured, source-located problems instead of silence.
- [Safety](https://blasdoc.dev/docs/safety): Why untrusted Markdown cannot execute anything.
- [Source model](https://blasdoc.dev/docs/source-model): Reading source back out of the IR, never out of the DOM.
- [SSR and hydration](https://blasdoc.dev/docs/ssr): Prerendering, adoption of server DOM, and caching.
- [Build integration](https://blasdoc.dev/docs/build): The Vite plugin, the Angular builder and the editor plugin behind `templateMD`.
- [CLI](https://blasdoc.dev/docs/cli): Set a project up, install a theme, and check what is wired.
- [MCP server and skills](https://blasdoc.dev/docs/mcp): Blasdoc as tools an AI agent can use, and the skills that teach it.
- [API reference](https://blasdoc.dev/docs/api): Every exported provider, component, directive and function.

## Updates

- [0.8 — Pages, written as Markdown](https://blasdoc.dev/updates/templatemd-pages): A Markdown file is now an Angular component template. Declare templateMD in @Component, keep styleUrl, and route the page like any other — the class itself is the binding context.

## Installation

### Using the CLI (recommended)

```bash
npx @blasdoc/cli init
```

It detects Angular CLI, Nx or Analog, writes the mechanical parts (the `.md` declaration, the loader, the editor plugin) and prints the provider list for you to paste.

### Manual installation

```bash
npm install @blasdoc/core @blasdoc/angular
npm install @blasdoc/highlight @blasdoc/components @blasdoc/theme-default
```

```ts
import { provideBlasdoc } from '@blasdoc/angular';
import { provideBlasdocHighlight } from '@blasdoc/highlight';
import { provideBlasdocTheme } from '@blasdoc/theme-default';

export const appConfig: ApplicationConfig = {
  providers: [
    provideBlasdoc(),
    provideBlasdocHighlight({
      themes: { github: { light: 'github-light', dark: 'github-dark' } },
      defaultTheme: 'github',
    }),
    provideBlasdocTheme(),
  ],
};
```

### A page

A page is an ordinary Angular component whose template is a Markdown file; the components its Markdown uses are the ones in its `imports`.

```ts
import { Component } from '@angular/core';
import templateMD from './guide.page.md';
import { AppButton } from './button';

@Component({
  selector: 'app-guide-page',
  templateMD,
  imports: [AppButton],
})
export class GuidePage {
  count = 0;
}
```

```md
# Getting started

Write the prose in **Markdown**, and drop in the components you already ship.

<app-button variant="primary" (click)="count = count + 1">
  Clicked {{ count }} times
</app-button>
```

## Packages

- `@blasdoc/core`: Markdown parsing, the Blasdoc IR, diagnostics and the source model. No Angular dependency.
- `@blasdoc/angular`: the renderer, the component registry, pages (`templateMD`) and bindings.
- `@blasdoc/highlight`: Shiki highlighting, producing IR nodes rather than HTML strings.
- `@blasdoc/components`: headless primitives — code block state, tabs, copy, preview mode.
- `@blasdoc/theme-default`: the optional default UI, driven entirely by `--blasdoc-*` CSS custom properties.
- `@blasdoc/build`: Angular builders and the build transform behind `templateMD`, plus the Vite plugin for Analog.
- `@blasdoc/cli`: `init`, `theme init`, `theme install` and `doctor`.
- `@blasdoc/mcp`: an MCP server with five tools and three skills, so an agent reads Blasdoc through the real parser.

## Key Features

- 🅰️ **Angular-first**: real component instances, Angular template syntax, the four binding channels kept apart.
- 🧱 **IR-first**: Markdown → MDAST → Blasdoc IR → Angular; never through an HTML string or `innerHTML`.
- 🔒 **Safe by default**: no `eval`, no `new Function`; raw HTML sanitised in the core; components only from an explicit list.
- 🎨 **Themeable**: every value is a `--blasdoc-*` custom property, light and dark, re-skinnable without forking.
- 🧩 **Headless**: behaviour and presentation separated, so the code block, tabs and previews can be replaced.
- ⚡ **SSR-ready**: prerendering, highlighted code carried in `TransferState`, hydration by DOM adoption.
- 🤖 **AI-ready**: every page as Markdown, this file, and an MCP server.

## Tech Stack

- Angular 22
- TypeScript
- unified / remark (remark-parse, remark-gfm)
- Shiki with rehype-pretty-code
- Nx

## License

MIT License — Open Source