MahmoudEmad/herolib
1
0
Fork 0
Code Issues 55 Pull Requests 1 Actions Packages Projects Releases 26 Wiki Activity

refactor: Update documentation for HeroLib Docusaurus integration

Browse Source 
- Refactor site.page_category and site.page arguments
- Update hero command usage for ebook paths
- Clarify Atlas and Doctree integration
- Add new ebook structure examples
- Update HeroScript actions reference
This commit is contained in:
Mahmoud-Emad
2025-12-01 11:59:16 +02:00
parent 8fc560ae78
commit ba46ed62ef
3 changed files with 307 additions and 97 deletions
Download Patch File Download Diff File Expand all files Collapse all files

61
aiprompts/docusaurus/docusaurus_ebook_manual.md
View File

@@ -2,13 +2,38 @@
This manual provides a comprehensive guide on how to leverage HeroLib's Docusaurus integration, Doctree, and HeroScript to create and manage technical ebooks, optimized for AI-driven content generation and project management.
## Quick Start - Recommended Ebook Structure
The recommended directory structure for an ebook:
```
my_ebook/
├── scan.hero # Atlas collection scanning
├── config.hero # Site configuration
├── menus.hero # Navbar and footer configuration
├── include.hero # Docusaurus define and atlas export
├── 1_intro.heroscript # Page definitions (numbered for ordering)
├── 2_concepts.heroscript # More page definitions
└── 3_advanced.heroscript # Additional pages
```
**Running an ebook:**
```bash
# Start development server
hero docs -d -p /path/to/my_ebook
# Build for production
hero docs -p /path/to/my_ebook
```
## 1. Core Concepts
To effectively create ebooks with HeroLib, it's crucial to understand the interplay of three core components:
* **HeroScript**: A concise scripting language used to define the structure, configuration, and content flow of your Docusaurus site. It acts as the declarative interface for the entire process.
* **HeroScript**: A concise scripting language used to define the structure, configuration, and content flow of your Docusaurus site. It acts as the declarative interface for the entire process. Files use `.hero` extension for configuration and `.heroscript` for page definitions.
* **Docusaurus**: A popular open-source static site generator. HeroLib uses Docusaurus as the underlying framework to render your ebook content into a navigable website.
* **Atlas (and Doctree)**: HeroLib's document collection layer. In the current pipeline, Atlas exports markdown "collections" and "pages" that Docusaurus consumes via the Atlas client. Doctree and `doctreeclient` are legacy/alternative ways to provide the same collections.
* **Atlas**: HeroLib's document collection layer. Atlas scans and exports markdown "collections" and "pages" that Docusaurus consumes.
## 2. Setting Up a Docusaurus Project with HeroLib
@@ -246,32 +271,36 @@ This is where you define the actual content pages and how they are organized int
```heroscript
// Define a category
!!site.page_category path:'introduction' label:"Introduction to Ebook" position:10
!!site.page_category name:'introduction' label:"Introduction to Ebook"
// Define a page within that category, linking to Doctree content
!!site.page path:'introduction' src:"my_doctree_collection:chapter_1_overview"
// Define pages - first page specifies collection, subsequent pages reuse it
!!site.page src:"my_collection:chapter_1_overview"
title:"Chapter 1: Overview"
description:"A brief introduction to the ebook's content."
position:1 // Order within the category
hide_title:true // Hide the title on the page itself
!!site.page src:"chapter_2_basics"
title:"Chapter 2: Basics"
// New category with new collection
!!site.page_category name:'advanced' label:"Advanced Topics"
!!site.page src:"advanced_collection:performance"
title:"Performance Tuning"
hide_title:true
```
**Arguments:**
* **`site.page_category`**:
* `path` (string, required): The path to the category directory within your Docusaurus `docs` folder (e.g., `introduction` will create `docs/introduction/_category_.json`).
* `name` (string, required): Category identifier (used internally).
* `label` (string, required): The display name for the category in the sidebar.
* `position` (int, optional): The order of the category in the sidebar.
* `sitename` (string, optional): If you have multiple Docusaurus sites defined, specify which site this category belongs to. Defaults to the current site's name.
* `position` (int, optional): The order of the category in the sidebar (auto-incremented if omitted).
* **`site.page`**:
* `src` (string, required): **Crucial for Doctree integration.** This specifies the source of the page content in the format `collection_name:page_name`. HeroLib will fetch the markdown content from the specified Doctree collection and page.
* `path` (string, required): The relative path and filename for the generated markdown file within your Docusaurus `docs` folder (e.g., `introduction/chapter_1.md`). If only a directory is provided (e.g., `introduction/`), the `page_name` from `src` will be used as the filename.
* `title` (string, optional): The title of the page. If not provided, HeroLib will attempt to extract it from the markdown content or use the `page_name`.
* `src` (string, required): **Crucial for Atlas/collection integration.** Format: `collection_name:page_name` for the first page, or just `page_name` to reuse the previous collection.
* `title` (string, optional): The title of the page. If not provided, HeroLib extracts it from the markdown `# Heading` or uses the page name.
* `description` (string, optional): A short description for the page, used in frontmatter.
* `position` (int, optional): The order of the page within its category.
* `hide_title` (boolean, optional): If `true`, the title will not be displayed on the page itself.
* `draft` (boolean, optional): If `true`, the page will be marked as a draft and not included in production builds.
* `title_nr` (int, optional): If set, HeroLib will re-number the markdown headings (e.g., `title_nr:3` will make `# Heading` become `### Heading`). Useful for consistent heading levels across imported content.
* `draft` (boolean, optional): If `true`, the page will be hidden from navigation.
### 3.7. Collections and Atlas/Doctree Integration

280
lib/web/docusaurus/README.md
View File

@@ -2,100 +2,256 @@
This module allows you to build and manage Docusaurus websites using a generic configuration layer provided by `lib/web/site`.
### Workflow
1. **Configure Your Site**: Define your site's metadata, navigation, footer, pages, and content sources using `!!site.*` actions in a `.heroscript` file. This creates a generic site definition.
2. **Define Docusaurus Build**: Use `!!docusaurus.define` to specify build paths and other factory-level settings.
3. **Link Site to Docusaurus**: Use `!!docusaurus.add` to link your generic site configuration to the Docusaurus factory. This tells HeroLib to build this specific site using Docusaurus.
4. **Run Actions**: Use actions like `!!docusaurus.dev` or `!!docusaurus.build` to generate and serve your site.
### Hero Command (Recommended)
For quick setup and development, use the hero command:
```bash
# Start development server
hero docs -d -path /path/to/your/site
hero docs -d -p /path/to/your/ebook
# Build for production
hero docs -b -path /path/to/your/site
hero docs -p /path/to/your/ebook
# Build and publish
hero docs -bp -path /path/to/your/site
hero docs -bp -p /path/to/your/ebook
```
### Example HeroScript
---
## Ebook Directory Structure
The recommended structure for an ebook follows this pattern:
```
my_ebook/
├── scan.hero # Atlas collection scanning
├── config.hero # Site configuration
├── menus.hero # Navbar and footer configuration
├── include.hero # Docusaurus define and atlas export
├── 1_intro.heroscript # Page definitions (numbered for ordering)
├── 2_concepts.heroscript # More page definitions
└── 3_advanced.heroscript # Additional pages
```
### File Descriptions
#### `scan.hero` - Scan Collections
Defines which collections to scan for content:
```heroscript
// Scan local collections
!!atlas.scan path:"../../collections/my_collection"
// Define the Docusaurus build environment, is optional
// Scan remote collections from git
!!atlas.scan git_url:"https://git.example.com/org/repo/src/branch/main/collections/docs"
```
#### `config.hero` - Site Configuration
Core site settings:
```heroscript
!!site.config
name:"my_ebook"
title:"My Awesome Ebook"
tagline:"Documentation made easy"
url:"https://docs.example.com"
url_home:"docs/"
base_url:"/my_ebook/"
favicon:"img/favicon.png"
copyright:"© 2024 My Organization"
default_collection:"my_collection"
!!site.config_meta
description:"Comprehensive documentation for my project"
title:"My Ebook - Documentation"
keywords:"docs, ebook, tutorial"
```
**Note:** When `url_home` ends with `/` (e.g., `docs/`), the first page in the sidebar automatically becomes the landing page. This means both `/docs/` and `/docs/intro` will work.
#### `menus.hero` - Navigation Configuration
```heroscript
!!site.navbar
title:"My Ebook"
!!site.navbar_item
label:"Documentation"
to:"docs/"
position:"left"
!!site.navbar_item
label:"GitHub"
href:"https://github.com/myorg/myrepo"
position:"right"
!!site.footer
style:"dark"
!!site.footer_item
title:"Docs"
label:"Getting Started"
to:"docs/"
!!site.footer_item
title:"Community"
label:"GitHub"
href:"https://github.com/myorg/myrepo"
```
#### `include.hero` - Docusaurus Setup
Links to shared configuration or defines docusaurus directly:
```heroscript
// Option 1: Include shared configuration with variable replacement
!!play.include path:'../../heroscriptall' replace:'SITENAME:my_ebook'
// Option 2: Define directly
!!docusaurus.define name:'my_ebook'
!!atlas.export include:true
```
#### Page Definition Files (`*.heroscript`)
Define pages and categories:
```heroscript
// Define a category
!!site.page_category name:'getting_started' label:"Getting Started"
// Define pages (first page specifies collection, subsequent pages reuse it)
!!site.page src:"my_collection:intro"
title:"Introduction"
!!site.page src:"installation"
title:"Installation Guide"
!!site.page src:"configuration"
title:"Configuration"
// New category
!!site.page_category name:'advanced' label:"Advanced Topics"
!!site.page src:"my_collection:performance"
title:"Performance Tuning"
```
---
## Collections
Collections are directories containing markdown files. They're scanned by Atlas and referenced in page definitions.
```
collections/
├── my_collection/
│ ├── .collection # Marker file (empty)
│ ├── intro.md
│ ├── installation.md
│ └── configuration.md
└── another_collection/
├── .collection
└── overview.md
```
Pages reference collections using `collection:page` format:
```heroscript
!!site.page src:"my_collection:intro" # Specifies collection
!!site.page src:"installation" # Reuses previous collection
!!site.page src:"another_collection:overview" # Switches collection
```
---
## Legacy Configuration
The older approach using `!!docusaurus.add` is still supported but not recommended:
```heroscript
!!docusaurus.define
path_build: "/tmp/docusaurus_build"
path_publish: "/tmp/docusaurus_publish"
reset: 1
install: 1
template_update: 1
!!docusaurus.add
sitename:"my_site"
path:"./path/to/my/site/source"
path_publish: "/tmp/docusaurus_publish" //optional
git_url:"https://git.threefold.info/tfgrid/docs_tfgrid4/src/branch/main/ebooks/tech" //optional: can use git to pull the site source
git_root:"/tmp/code" //optional: where to clone git repo
git_reset:1 //optional: reset git repo
git_pull:1 //optional: pull latest changes
play:true //required when using git_url: process heroscript files from source path
// Run the development server
!!docusaurus.dev site:"my_site" open:true watch_changes:true
path:"./path/to/site"
!!docusaurus.dev site:"my_site" open:true
```
## see sites to define a site
---
the site needs to be defined following the generic site definition, see the `lib/web/site` module for more details.
## HeroScript Actions Reference
```heroscript
### `!!atlas.scan`
//Configure the site using the generic 'site' module
!!site.config
name: "my_site"
title: "My Awesome Docs"
tagline: "The best docs ever"
url: "https://docs.example.com"
base_url: "/"
copyright: "Example Corp"
Scans a directory for markdown collections:
!!site.menu_item
label: "Homepage"
href: "https://example.com"
position: "right"
- `path` (string): Local path to scan
- `git_url` (string): Git URL to clone and scan
- `name` (string): Atlas instance name (default: `main`)
- `ignore` (list): Directory names to skip
// ... add footer, pages, etc. using !!site.* actions ...
### `!!atlas.export`
```
Exports scanned collections:
### Heroscript Actions
- `include` (bool): Include content in export (default: `true`)
- `destination` (string): Export directory
- `!!docusaurus.define`: Configures a Docusaurus factory instance.
- `name` (string): Name of the factory (default: `default`).
- `path_build` (string): Path to build the site.
- `path_publish` (string): Path to publish the final build.
- `reset` (bool): If `true`, clean the build directory before starting.
- `template_update` (bool): If `true`, update the Docusaurus template.
- `install` (bool): If `true`, run `bun install`.
### `!!docusaurus.define`
- `!!docusaurus.add`: Links a configured site to the Docusaurus factory.
- `site` (string, required): The name of the site defined in `!!site.config`.
- `path` (string, required): The local filesystem path to the site's source directory (e.g., for `static/` folder).
Configures the Docusaurus build environment:
- `!!docusaurus.dev`: Runs the Docusaurus development server.
- `site` (string, required): The name of the site to run.
- `host` (string): Host to bind to (default: `localhost`).
- `port` (int): Port to use (default: `3000`).
- `open` (bool): Open the site in a browser.
- `watch_changes` (bool): Watch for source file changes and auto-reload.
- `name` (string, required): Site name (must match `!!site.config` name)
- `path_build` (string): Build directory path
- `path_publish` (string): Publish directory path
- `reset` (bool): Clean build directory before starting
- `template_update` (bool): Update Docusaurus template
- `install` (bool): Run `bun install`
- `atlas_dir` (string): Atlas export directory
- `!!docusaurus.build`: Builds the static site for production.
- `site` (string, required): The name of the site to build.
### `!!site.config`
Core site configuration:
- `name` (string, required): Unique site identifier
- `title` (string): Site title
- `tagline` (string): Site tagline
- `url` (string): Full site URL
- `base_url` (string): Base URL path (e.g., `/my_ebook/`)
- `url_home` (string): Home page path (e.g., `docs/`)
- `default_collection` (string): Default collection for pages
- `favicon` (string): Favicon path
- `copyright` (string): Copyright notice
### `!!site.page`
Defines a documentation page:
- `src` (string, required): Source as `collection:page` or just `page` (reuses previous collection)
- `title` (string): Page title
- `description` (string): Page description
- `draft` (bool): Hide from navigation
- `hide_title` (bool): Don't show title on page
### `!!site.page_category`
Defines a sidebar category:
- `name` (string, required): Category identifier
- `label` (string): Display label
- `position` (int): Sort order
---
## See Also
- `lib/web/site` - Generic site configuration module
- `lib/data/atlas` - Atlas collection management

63
lib/web/site/readme.md
View File

@@ -505,28 +505,53 @@ Overrides specific metadata for SEO without changing core config.
## File Organization
Organize HeroScript files with numeric prefixes to control execution order:
### Recommended Ebook Structure
The modern ebook structure uses `.hero` files for configuration and `.heroscript` files for page definitions:
```
docs/
├── 0_config.heroscript
│ └── !!site.config and !!site.config_meta
│
├── 1_menu.heroscript
│ └── !!site.navbar and !!site.footer
│
├── 2_pages.heroscript
│ └── !!site.page_category and !!site.page actions
│
└── 3_publish.heroscript
└── !!site.publish destinations
my_ebook/
├── scan.hero # !!atlas.scan - collection scanning
├── config.hero # !!site.config - site configuration
├── menus.hero # !!site.navbar and !!site.footer
├── include.hero # !!docusaurus.define and !!atlas.export
├── 1_intro.heroscript # Page definitions (categories + pages)
├── 2_concepts.heroscript # More page definitions
└── 3_advanced.heroscript # Additional pages
```
**Why numeric prefixes?**
### File Types
Files are processed in alphabetical order. Numeric prefixes ensure:
- Site config runs first
- Navigation menu configures before pages
- Pages build the final structure
- Publishing configured last
- **`.hero` files**: Configuration files processed in any order
- **`.heroscript` files**: Page definition files processed alphabetically
Use numeric prefixes on `.heroscript` files to control page/category ordering in the sidebar.
### Example scan.hero
```heroscript
!!atlas.scan path:"../../collections/my_collection"
```
### Example include.hero
```heroscript
// Include shared configuration (optional)
!!play.include path:'../../heroscriptall' replace:'SITENAME:my_ebook'
// Or define directly
!!docusaurus.define name:'my_ebook'
!!atlas.export include:true
```
### Running an Ebook
```bash
# Development server
hero docs -d -p /path/to/my_ebook
# Build for production
hero docs -p /path/to/my_ebook
```