doctree/webbuilder/README.md

WebBuilder

WebBuilder is a library for building websites from configuration files and markdown content. It uses the DocTree library to process markdown content and includes, and exports the result to a webmeta.json file that can be used by a browser-based website generator.

Overview

WebBuilder scans directories for configuration files (in hjson format) and generates a webmeta.json file that can be used by a browser-based website generator. It can also clone Git repositories, process markdown content, and upload files to IPFS.

Parsing Configuration Files

WebBuilder supports multiple parsing strategies for configuration files:

Unified Parser

The recommended way to parse configuration files is to use the unified parser, which provides a consistent interface for all parsing strategies:

use webbuilder::{from_directory_with_strategy, ParsingStrategy};

// Use the recommended strategy (Hjson)
let webbuilder = from_directory_with_strategy("path/to/config", ParsingStrategy::Hjson)?;

// Or use the auto-detect strategy
let webbuilder = from_directory_with_strategy("path/to/config", ParsingStrategy::Auto)?;

// Or use the simple strategy (legacy)
let webbuilder = from_directory_with_strategy("path/to/config", ParsingStrategy::Simple)?;

You can also use the convenience functions:

use webbuilder::{from_directory, parse_site_config_recommended, parse_site_config_auto};

// Use the recommended strategy (Hjson)
let webbuilder = from_directory("path/to/config")?;

// Or parse the site configuration directly
let site_config = parse_site_config_recommended("path/to/config")?;
let site_config = parse_site_config_auto("path/to/config")?;

Parsing Strategies

WebBuilder supports the following parsing strategies:

• Hjson: Uses the deser-hjson library to parse hjson files. This is the recommended strategy.
• Simple: Uses a simple line-by-line parser that doesn't rely on external libraries. This is a legacy strategy.
• Auto: Tries the Hjson parser first, and falls back to the simple parser if it fails.

Building a Website

Once you have a WebBuilder instance, you can build a website:

use webbuilder::from_directory;

// Create a WebBuilder instance
let webbuilder = from_directory("path/to/config")?;

// Build the website
let webmeta = webbuilder.build()?;

// Save the webmeta.json file
webmeta.save("webmeta.json")?;

// Upload the webmeta.json file to IPFS
let ipfs_hash = webbuilder.upload_to_ipfs("webmeta.json")?;
println!("Uploaded to IPFS: {}", ipfs_hash);

Configuration Files

WebBuilder expects the following configuration files:

• main.hjson: Main configuration file with site metadata
• header.hjson: Header configuration
• footer.hjson: Footer configuration
• collection.hjson: Collection configuration (Git repositories)
• pages/*.hjson: Page configuration files

Example main.hjson:

{
    "name": "my-site",
    "title": "My Site",
    "description": "My awesome site",
    "url": "https://example.com",
    "favicon": "favicon.ico",
    "keywords": [
        "website",
        "awesome"
    ]
}

Example collection.hjson:

[
    {
        "name": "docs",
        "url": "https://github.com/example/docs.git",
        "description": "Documentation",
        "scan": true
    }
]

Example pages/pages.hjson:

[
    {
        "name": "home",
        "title": "Home",
        "description": "Home page",
        "navpath": "/",
        "collection": "docs",
        "draft": false
    }
]

License

This project is licensed under the MIT License - see the LICENSE file for details.