Skip to content

Commit e478d63

Browse files
mikebarkminmikebarkmin
committed
update READMEs
1 parent da524b2 commit e478d63

8 files changed

Lines changed: 234 additions & 13 deletions

File tree

‎README.md‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,26 @@ support modern standards and runs superfast.
77
- **Repository:** https://github.com/openpatch/hyperbook
88
- **Community**: https://matrix.to/#/#openpatch:matrix.org
99

10+
## Packages
11+
12+
This monorepo contains the following packages:
13+
14+
### Core Packages
15+
16+
- **[hyperbook](packages/hyperbook)** - Main CLI tool for creating, building, and serving Hyperbook projects
17+
- **[@hyperbook/markdown](packages/markdown)** - Markdown processing engine with 30+ custom directives
18+
- **[@hyperbook/fs](packages/fs)** - File system utilities for managing Hyperbook projects
19+
- **[@hyperbook/types](packages/types)** - TypeScript type definitions for the Hyperbook ecosystem
20+
- **[create-hyperbook](packages/create)** - Interactive CLI for scaffolding new Hyperbook projects
21+
22+
### Components
23+
24+
- **[@hyperbook/web-component-excalidraw](packages/web-component-excalidraw)** - Excalidraw web component for diagrams
25+
26+
### Platforms
27+
28+
- **[hyperbook-studio](platforms/vscode)** - Visual Studio Code extension with preview, snippets, and validation
29+
1030
## Documentation
1131

1232
If you want to work on the documentation, run the

‎packages/create/README.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,11 @@
11
# create-hyperbook <a href="https://npmjs.com/package/create-hyperbook"><img src="https://img.shields.io/npm/v/create-hyperbook" alt="npm package"></a>
22

3+
CLI tool for scaffolding new Hyperbook projects. This package provides an interactive prompt-based setup that creates a new Hyperbook project with sample content and configuration.
4+
35
## Scaffolding Your First Hyperbook Project
46

57
> **Compatibility Note:**
6-
> Hyperbook requires [Node.js](https://nodejs.org/en/) version 20+. Please upgrade if your package manager warns about it.
8+
> Hyperbook requires [Node.js](https://nodejs.org/en/) version 18+. Please upgrade if your package manager warns about it.
79
810
With NPM:
911

‎packages/fs/README.md‎

Lines changed: 25 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,33 @@
11
# @hyperbook/fs
22

3+
File system utilities for Hyperbook projects. This package handles:
4+
5+
- Loading and validating `hyperbook.json` and `hyperlibrary.json` configuration files
6+
- Reading and processing markdown files with frontmatter
7+
- Building navigation structures from file hierarchies
8+
- Managing project structure (hyperbook, hyperlibrary, hyperproject)
9+
- Handling virtual files (VFile) for glossary, archives, snippets, and public assets
10+
- Handlebars template registration and helpers
11+
312
## Installation
413

514
```sh
6-
yarn add @hyperbook/fs
15+
pnpm add @hyperbook/fs
716
# or
817
npm i @hyperbook/fs
918
```
19+
20+
## Usage
21+
22+
```typescript
23+
import { hyperbook, hyperlibrary, hyperproject } from "@hyperbook/fs";
24+
25+
// Load a hyperbook project
26+
const book = await hyperbook.make("/path/to/book");
27+
28+
// Access configuration
29+
console.log(book.config.name);
30+
31+
// Get navigation
32+
const navigation = book.navigation;
33+
```

‎packages/hyperbook/README.md‎

Lines changed: 109 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,109 @@
1+
# hyperbook
2+
3+
The main CLI tool for creating, building, and serving Hyperbook projects. Hyperbook is a quick and easy way to build interactive workbooks that support modern standards and run superfast.
4+
5+
## Features
6+
7+
- **Quick Project Setup** - Scaffold new projects with `hyperbook new`
8+
- **Development Server** - Live-reload development server with hot module replacement
9+
- **Production Builds** - Optimized static site generation
10+
- **Interactive Elements** - Support for 30+ custom directives (alerts, videos, code environments, etc.)
11+
- **Multi-language Support** - Built-in i18n for 7 languages
12+
- **Search** - Full-text search with Lunr.js
13+
- **Navigation** - Automatic navigation generation from file structure
14+
- **Themes** - Customizable colors and styling
15+
- **Archives** - Downloadable file archives for students
16+
- **Glossary** - Automatic term indexing and tooltips
17+
18+
## Installation
19+
20+
Install globally:
21+
22+
```sh
23+
npm install -g hyperbook
24+
# or
25+
pnpm add -g hyperbook
26+
```
27+
28+
Or use directly with npx:
29+
30+
```sh
31+
npx hyperbook@latest new my-book
32+
```
33+
34+
## Usage
35+
36+
### Create a new Hyperbook project
37+
38+
```sh
39+
hyperbook new my-documentation
40+
cd my-documentation
41+
```
42+
43+
### Start development server
44+
45+
```sh
46+
hyperbook dev
47+
# or with custom port
48+
hyperbook dev --port 3000
49+
```
50+
51+
The development server will start at `http://localhost:8080` with live reload.
52+
53+
### Build for production
54+
55+
```sh
56+
hyperbook build
57+
```
58+
59+
This generates a static site in the `public` directory ready for deployment.
60+
61+
## Project Structure
62+
63+
A Hyperbook project consists of:
64+
65+
```
66+
my-book/
67+
├── hyperbook.json # Main configuration
68+
├── glossary.md # Glossary definitions
69+
├── book/ # Content directory
70+
│ ├── index.md # Home page
71+
│ ├── chapter1/
72+
│ │ ├── index.md
73+
│ │ └── page.md
74+
│ └── chapter2/
75+
│ └── index.md
76+
└── public/ # Built output (after build)
77+
```
78+
79+
## Configuration
80+
81+
The `hyperbook.json` file configures your project:
82+
83+
```json
84+
{
85+
"name": "My Documentation",
86+
"description": "Interactive documentation",
87+
"language": "en",
88+
"basePath": "",
89+
"colors": {
90+
"brand": "#3b82f6"
91+
},
92+
"links": [
93+
{
94+
"label": "GitHub",
95+
"href": "https://github.com/org/repo"
96+
}
97+
]
98+
}
99+
```
100+
101+
## Learn More
102+
103+
- **Documentation**: https://hyperbook.openpatch.org
104+
- **Repository**: https://github.com/openpatch/hyperbook
105+
- **Community**: https://matrix.to/#/#openpatch:matrix.org
106+
107+
## License
108+
109+
MIT © Mike Barkmin

‎packages/markdown/README.md‎

Lines changed: 31 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,41 @@
1-
# @bitflow/markdown
1+
# @hyperbook/markdown
2+
3+
Markdown processing engine for Hyperbook. This package provides extensive markdown transformation capabilities with 30+ custom directives and plugins:
4+
5+
**Core Features:**
6+
- Custom markdown directives (alerts, videos, collapsibles, tabs, etc.)
7+
- Code execution environments (Python, SQL, Web IDE)
8+
- Interactive elements (Excalidraw, Mermaid, JSXGraph, GeoGebra)
9+
- Media embedding (YouTube, audio, video)
10+
- Math support (KaTeX)
11+
- Syntax highlighting (Shiki with Pretty Code)
12+
- Table of contents generation
13+
- Search document indexing
14+
- Emoji support (GitHub emojis)
15+
- Image processing with attributes
16+
17+
**Supported Directives:**
18+
`:alert`, `:video`, `:youtube`, `:audio`, `:archive`, `:download`, `:embed`, `:excalidraw`, `:mermaid`, `:plantuml`, `:collapsible`, `:tabs`, `:tiles`, `:slideshow`, `:term`, `:pagelist`, `:bookmarks`, `:qr`, `:protect`, `:textinput`, `:pyide`, `:sqlide`, `:webide`, `:onlineide`, `:scratchblock`, `:h5p`, `:geogebra`, `:jsxgraph`, `:abcmusic`, `:learningmap`, `:struktog`, `:typst`, and more.
219

320
## Installation
421

522
```sh
6-
yarn add @bitflow/markdown
23+
pnpm add @hyperbook/markdown
724
# or
8-
npm i @bitflow/markdown
25+
npm i @hyperbook/markdown
926
```
1027

11-
## Math
28+
## Usage
1229

13-
Import KaTeX CSS:
30+
```typescript
31+
import { process } from "@hyperbook/markdown";
1432

15-
```
16-
import "@hyperbook/katex.css";
33+
const result = await process({
34+
content: "# Hello\n\n:alert[Warning]{type=warning}",
35+
config: hyperbookConfig,
36+
// ...
37+
});
38+
39+
console.log(result.html); // Transformed HTML
40+
console.log(result.data.headings); // Extracted headings
1741
```

‎packages/types/README.md‎

Lines changed: 21 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,29 @@
11
# @hyperbook/types
22

3+
TypeScript type definitions for Hyperbook. This package provides all the core types used across the Hyperbook ecosystem, including:
4+
5+
- Configuration types for `hyperbook.json` and `hyperlibrary.json`
6+
- Page and section navigation types
7+
- Language and layout definitions
8+
- Element and directive configuration types
9+
- Glossary and frontmatter types
10+
311
## Installation
412

513
```sh
6-
yarn add @hyperbook/types
14+
pnpm add @hyperbook/types
715
# or
816
npm i @hyperbook/types
917
```
18+
19+
## Usage
20+
21+
```typescript
22+
import type { HyperbookJson, Language, Navigation } from "@hyperbook/types";
23+
24+
const config: HyperbookJson = {
25+
name: "My Documentation",
26+
language: "en",
27+
// ...
28+
};
29+
```

‎packages/web-component-excalidraw/README.md‎

Lines changed: 23 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,29 @@
1-
# @hyperbook/element-excalidraw
1+
# @hyperbook/web-component-excalidraw
2+
3+
Web component wrapper for Excalidraw integration in Hyperbook. This package provides a custom element that embeds the Excalidraw drawing tool as a reusable web component.
4+
5+
**Features:**
6+
- Standalone Excalidraw web component
7+
- Built with React and converted to web component via `@r2wc/react-to-web-component`
8+
- Compatible with any HTML environment
9+
- Used by the `:excalidraw` directive in `@hyperbook/markdown`
210

311
## Installation
412

513
```sh
6-
yarn add @hyperbook/element-excalidraw
14+
pnpm add @hyperbook/web-component-excalidraw
715
# or
8-
npm i @hyperbook/element-excalidraw
16+
npm i @hyperbook/web-component-excalidraw
17+
```
18+
19+
## Usage
20+
21+
```html
22+
<!-- In HTML -->
23+
<hyperbook-excalidraw data="..."></hyperbook-excalidraw>
24+
```
25+
26+
```javascript
27+
// In JavaScript
28+
import "@hyperbook/web-component-excalidraw";
929
```

‎platforms/vscode/README.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,8 @@
77
[![GitHub Contributors](https://img.shields.io/github/contributors/openpatch/hyperbook.svg?)](https://github.com/openpatch/hyperbook/graphs/contributors)
88
[![License](https://img.shields.io/github/license/openpatch/hyperbook)](https://github.com/openpatch/hyperbook)
99

10+
Complete tooling for authoring Hyperbooks in Visual Studio Code. This extension provides live preview, snippets, auto-completion, syntax highlighting, and schema validation for Hyperbook projects.
11+
1012
All you need for writing Hyperbooks (auto preview, snippets, auto-completion and more).
1113

1214
## Features

0 commit comments

Comments
 (0)