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

...

Browse Source
This commit is contained in:
despiegk
2025-05-04 07:14:18 +03:00
parent 3682ef2420
commit 108d2019cd
2 changed files with 190 additions and 160 deletions
Download Patch File Download Diff File Expand all files Collapse all files

BIN
examples/webtools/docusaurus_example_complete
View File

Binary file not shown.

350
lib/web/docusaurus/readme.md
View File

@@ -1,56 +1,87 @@
# Docusaurus Library for V # Docusaurus Library for V
A V language library for creating, configuring, and managing [Docusaurus](https://docusaurus.io/) documentation sites with minimal effort.
## Overview
This library provides a convenient wrapper around Docusaurus, a powerful static website generator maintained by Meta. It allows you to: This library provides a convenient wrapper around Docusaurus, a powerful static website generator maintained by Meta. It allows you to:
- Create and manage multiple documentation sites - Create and manage multiple documentation sites
- Configure sites through structured JSON or HeroScript - Configure sites through HeroScript
- Build sites for production - Build sites for production
- Set up development environments with hot reloading - Set up development environments with hot reloading
- Handle file watching for automatic rebuilding - Handle file watching for automatic rebuilding
- Deploy sites to remote servers - Deploy sites to remote servers
- Import content from Git repositories - Import content from Git repositories
## Features
- **Simple API**: Create and manage Docusaurus sites with a few lines of V code
- **Flexible Configuration**: Configure sites using JSON files or programmatically
- **Development Mode**: Built-in development server with file watching
- **Remote Deployment**: Push to remote servers via SSH
- **Content Import**: Import content from Git repositories
- **Template Management**: Uses standard Docusaurus templates with custom configuration
## Installation
The library is part of the HeroLib package and can be imported as follows:
```v
import freeflowuniverse.herolib.web.docusaurus
```
## Usage ## Usage
### Basic Example
```v ```v
import freeflowuniverse.herolib.web.docusaurus import freeflowuniverse.herolib.web.docusaurus
import os
// Create a new docusaurus factory // Define your HeroScript configuration
hero_script := '
!!docusaurus.config
name:"my-documentation"
title:"My Documentation Site"
tagline:"Documentation made simple with V and Docusaurus"
url:"https://docs.example.com"
url_home:"docs/"
base_url:"/"
favicon:"img/favicon.png"
image:"img/hero.png"
copyright:"© 2025 Example Organization"
!!docusaurus.config_meta
description:"Comprehensive documentation for our amazing project"
image:"https://docs.example.com/img/social-card.png"
title:"My Documentation | Official Docs"
!!docusaurus.navbar
title:"My Project"
!!docusaurus.navbar_item
label:"Documentation"
href:"/docs"
position:"left"
!!docusaurus.navbar_item
label:"GitHub"
href:"https://github.com/example/repo"
position:"right"
!!docusaurus.footer
style:"dark"
!!docusaurus.footer_item
title:"Documentation"
label:"Introduction"
to:"/docs"
!!docusaurus.footer_item
title:"Community"
label:"GitHub"
href:"https://github.com/example/repo"
'
// Create a factory with the HeroScript configuration
mut docs := docusaurus.new( mut docs := docusaurus.new(
build_path: '~/docusaurus_projects' // Optional, defaults to ~/hero/var/docusaurus build_path: os.join_path(os.home_dir(), 'hero/var/docusaurus_demo')
heroscript: hero_script
)! )!
// Get or create a site // Create a site directory
site_path := os.join_path(os.home_dir(), 'hero/var/docusaurus_source')
os.mkdir_all(site_path)!
// Get or create a site using the factory
mut site := docs.get( mut site := docs.get(
name: 'my-docs', name: 'my-documentation'
path: '~/my-docs-source', path: site_path
init: true // Create if doesn't exist init: true
)! )!
// Run development server // Generate a site
site.generate()!
// Start development server
site.dev()! site.dev()!
// Or build for production // Or build for production
@@ -60,45 +91,12 @@ site.dev()!
// site.build_publish()! // site.build_publish()!
``` ```
### Configuration
Configuration is done via JSON files in the `cfg` directory of your site:
- `main.json`: Main site configuration (title, URL, metadata, etc.)
- `navbar.json`: Navigation bar configuration
- `footer.json`: Footer configuration
Example `main.json`:
```json
{
"title": "My Documentation",
"tagline": "Documentation Made Easy",
"favicon": "img/favicon.png",
"url": "https://docs.example.com",
"url_home": "docs/",
"baseUrl": "/",
"image": "img/logo.png",
"metadata": {
"description": "Comprehensive documentation for my project",
"image": "https://docs.example.com/img/logo.png",
"title": "My Documentation"
},
"buildDest": ["user@server:/path/to/deployment"],
"buildDestDev": ["user@server:/path/to/dev-deployment"]
}
```
### Directory Structure ### Directory Structure
A typical Docusaurus site managed by this library has the following structure: A typical Docusaurus site managed by this library has the following structure:
``` ```
my-site/ my-site/
├── cfg/
│ ├── main.json
│ ├── navbar.json
│ └── footer.json
├── docs/ ├── docs/
│ ├── intro.md │ ├── intro.md
│ └── ... │ └── ...
@@ -111,11 +109,116 @@ my-site/
### Development Workflow ### Development Workflow
1. Create a new site using `docs.get()` 1. Define your site configuration using HeroScript
2. Configure your site via JSON files or programmatically 2. Create a factory with the HeroScript configuration
3. Run `site.dev()` to start development server 3. Get or create a site using the factory
4. Edit files in the `docs` directory 4. Run `site.dev()` to start development server
5. When ready, run `site.build()` or `site.build_publish()` to deploy 5. Edit files in the `docs` directory
6. When ready, run `site.build()` or `site.build_publish()` to deploy
## HeroScript Configuration Options
### Main Site Configuration
```
!!docusaurus.config
name:"my-documentation" # Site name (used for directories, etc.)
title:"My Documentation" # Main title displayed in browser
tagline:"Documentation Made Easy"
url:"https://docs.example.com"
url_home:"docs/"
base_url:"/"
favicon:"img/favicon.png"
image:"img/hero.png"
copyright:"© 2025 My Organization"
```
### Metadata
```
!!docusaurus.config_meta
description:"Comprehensive documentation for my project"
image:"https://docs.example.com/img/social-card.png"
title:"My Documentation | Official Docs"
```
### Navigation Bar
```
!!docusaurus.navbar
title:"My Project"
!!docusaurus.navbar_item
label:"Documentation"
href:"/docs"
position:"left"
!!docusaurus.navbar_item
label:"GitHub"
href:"https://github.com/example/repo"
position:"right"
```
### Footer
```
!!docusaurus.footer
style:"dark"
!!docusaurus.footer_item
title:"Documentation"
label:"Introduction"
to:"/docs"
!!docusaurus.footer_item
title:"Community"
label:"GitHub"
href:"https://github.com/example/repo"
```
### Remote Deployment
```
!!docusaurus.ssh_connection
name:"production"
host:"example.com"
login:"deploy"
port:22
key_path:"~/.ssh/id_rsa"
!!docusaurus.build_dest
ssh_name:"production"
path:"/var/www/docs"
```
### Content Import
```
!!docusaurus.import_source
url:"https://github.com/example/external-docs"
dest:"external"
replace:"PROJECT_NAME:My Project, VERSION:1.0.0"
```
## Multiple Ways to Use HeroScript
### Option 1: Provide HeroScript directly to the factory
```v
mut docs := docusaurus.new(
build_path: '~/docusaurus_sites'
heroscript: hero_script
)!
```
### Option 2: Load HeroScript from a file
```v
mut docs := docusaurus.new(
build_path: '~/docusaurus_sites'
heroscript_path: '~/my_docusaurus_config.hero'
)!
```
## Features in Detail ## Features in Detail
@@ -125,102 +228,29 @@ The library includes a file watcher that automatically updates the build directo
### Remote Deployment ### Remote Deployment
Sites can be deployed to remote servers via SSH. Configure the deployment destinations in `main.json`: Sites can be deployed to remote servers via SSH by configuring the deployment destinations in your HeroScript:
```json ```
"buildDest": ["user@server:/path/to/deployment"], !!docusaurus.ssh_connection
"buildDestDev": ["user@server:/path/to/dev-deployment"] name:"production"
host:"example.com"
login:"deploy"
port:22
key_path:"~/.ssh/id_rsa"
!!docusaurus.build_dest
ssh_name:"production"
path:"/var/www/docs"
``` ```
### Content Import ### Content Import
You can import content from Git repositories: You can import content from Git repositories by configuring import sources in your HeroScript:
```json ```
"import": [ !!docusaurus.import_source
{ url:"https://github.com/example/external-docs"
"url": "https://github.com/username/repo", dest:"external"
"dest": "external-docs", replace:"PROJECT_NAME:My Project, VERSION:1.0.0"
"visible": true
}
]
``` ```
## Advanced Usage with HeroScript
You can configure your Docusaurus site using HeroScript in multiple ways:
### Option 1: Provide HeroScript directly to the factory
```v
import freeflowuniverse.herolib.web.docusaurus
// Create a factory with inline HeroScript
mut docs := docusaurus.new(
build_path: '~/docusaurus_sites'
heroscript: '
!!docusaurus.config
name:"my-docs"
title:"My Documentation"
tagline:"Documentation Made Easy"
url:"https://docs.example.com"
base_url:"/"
!!docusaurus.navbar
title:"My Project"
!!docusaurus.navbar_item
label:"GitHub"
href:"https://github.com/username/repo"
position:"right"
'
)!
```
### Option 2: Load HeroScript from a file
```v
import freeflowuniverse.herolib.web.docusaurus
// Create a factory using HeroScript from a file
mut docs := docusaurus.new(
build_path: '~/docusaurus_sites'
heroscript_path: '~/my_docusaurus_config.hero'
)!
```
### Option 3: Process HeroScript separately
```v
import freeflowuniverse.herolib.web.docusaurus
mut script := '
!!docusaurus.config
title:"My Documentation"
tagline:"Documentation Made Easy"
url:"https://docs.example.com"
base_url:"/"
!!docusaurus.navbar
title:"My Project"
!!docusaurus.navbar_item
label:"GitHub"
href:"https://github.com/username/repo"
position:"right"
'
// Process the HeroScript to get a Config object
mut config := docusaurus.play(heroscript: script)!
// Use the config when creating a site
mut site := docs.get(
name: 'my-site',
path: '~/my-site-source',
config: config
)!
```
## License
This library is part of the HeroLib project and follows its licensing terms.