f9d338a8f1
- Adds a new library for building websites from configuration files and markdown content. Improves developer workflow by automating website construction. - Implements multiple parsing strategies for configuration files (Hjson, Simple, Auto) for flexibility and backward compatibility. - Includes support for cloning Git repositories, processing markdown, and uploading files to IPFS, streamlining the website deployment process. Facilitates easier website updates and content management. - Adds comprehensive README documentation explaining the library's usage and configuration options. Improves user onboarding and reduces the learning curve for new users.
129 lines
3.6 KiB
Markdown
129 lines
3.6 KiB
Markdown
# 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:
|
|
|
|
```rust
|
|
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:
|
|
|
|
```rust
|
|
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:
|
|
|
|
```rust
|
|
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`:
|
|
|
|
```hjson
|
|
{
|
|
"name": "my-site",
|
|
"title": "My Site",
|
|
"description": "My awesome site",
|
|
"url": "https://example.com",
|
|
"favicon": "favicon.ico",
|
|
"keywords": [
|
|
"website",
|
|
"awesome"
|
|
]
|
|
}
|
|
```
|
|
|
|
Example `collection.hjson`:
|
|
|
|
```hjson
|
|
[
|
|
{
|
|
"name": "docs",
|
|
"url": "https://github.com/example/docs.git",
|
|
"description": "Documentation",
|
|
"scan": true
|
|
}
|
|
]
|
|
```
|
|
|
|
Example `pages/pages.hjson`:
|
|
|
|
```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.
|