...
This commit is contained in:
Binary file not shown.
@@ -1,56 +1,87 @@
|
||||
# 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:
|
||||
|
||||
- Create and manage multiple documentation sites
|
||||
- Configure sites through structured JSON or HeroScript
|
||||
- Configure sites through HeroScript
|
||||
- Build sites for production
|
||||
- Set up development environments with hot reloading
|
||||
- Handle file watching for automatic rebuilding
|
||||
- Deploy sites to remote servers
|
||||
- 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
|
||||
|
||||
### Basic Example
|
||||
|
||||
```v
|
||||
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(
|
||||
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(
|
||||
name: 'my-docs',
|
||||
path: '~/my-docs-source',
|
||||
init: true // Create if doesn't exist
|
||||
name: 'my-documentation'
|
||||
path: site_path
|
||||
init: true
|
||||
)!
|
||||
|
||||
// Run development server
|
||||
// Generate a site
|
||||
site.generate()!
|
||||
|
||||
// Start development server
|
||||
site.dev()!
|
||||
|
||||
// Or build for production
|
||||
@@ -60,45 +91,12 @@ site.dev()!
|
||||
// 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
|
||||
|
||||
A typical Docusaurus site managed by this library has the following structure:
|
||||
|
||||
```
|
||||
my-site/
|
||||
├── cfg/
|
||||
│ ├── main.json
|
||||
│ ├── navbar.json
|
||||
│ └── footer.json
|
||||
├── docs/
|
||||
│ ├── intro.md
|
||||
│ └── ...
|
||||
@@ -111,11 +109,116 @@ my-site/
|
||||
|
||||
### Development Workflow
|
||||
|
||||
1. Create a new site using `docs.get()`
|
||||
2. Configure your site via JSON files or programmatically
|
||||
3. Run `site.dev()` to start development server
|
||||
4. Edit files in the `docs` directory
|
||||
5. When ready, run `site.build()` or `site.build_publish()` to deploy
|
||||
1. Define your site configuration using HeroScript
|
||||
2. Create a factory with the HeroScript configuration
|
||||
3. Get or create a site using the factory
|
||||
4. Run `site.dev()` to start development server
|
||||
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
|
||||
|
||||
@@ -125,102 +228,29 @@ The library includes a file watcher that automatically updates the build directo
|
||||
|
||||
### 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"],
|
||||
"buildDestDev": ["user@server:/path/to/dev-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
|
||||
|
||||
You can import content from Git repositories:
|
||||
You can import content from Git repositories by configuring import sources in your HeroScript:
|
||||
|
||||
```json
|
||||
"import": [
|
||||
{
|
||||
"url": "https://github.com/username/repo",
|
||||
"dest": "external-docs",
|
||||
"visible": true
|
||||
}
|
||||
]
|
||||
```
|
||||
!!docusaurus.import_source
|
||||
url:"https://github.com/example/external-docs"
|
||||
dest:"external"
|
||||
replace:"PROJECT_NAME:My Project, VERSION:1.0.0"
|
||||
```
|
||||
|
||||
## 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.
|
||||
Reference in New Issue
Block a user