diff --git a/examples/webtools/docusaurus_example_complete b/examples/webtools/docusaurus_example_complete deleted file mode 100755 index 0fb0f4e8..00000000 Binary files a/examples/webtools/docusaurus_example_complete and /dev/null differ diff --git a/lib/web/docusaurus/readme.md b/lib/web/docusaurus/readme.md index c366c936..0c61df0e 100644 --- a/lib/web/docusaurus/readme.md +++ b/lib/web/docusaurus/readme.md @@ -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. \ No newline at end of file