|
1 year ago | |
---|---|---|
src | 1 year ago | |
test_files | 1 year ago | |
.gitignore | 2 years ago | |
Cargo.lock | 1 year ago | |
Cargo.toml | 1 year ago | |
LICENSE-APACHE | 2 years ago | |
LICENSE-MIT | 2 years ago | |
README.md | 2 years ago |
README.md
A Rust Site Engine
A Rust Site Engine, or arse
, is static site generator written in Rust. It seeks to provide a simple
and flexible base for serving sites using:
- Tera for templates
- pulldown-cmark for CommonMark rendering
- routerify to serve the site
- simplecss for default styling
- rss for generating a full-site RSS feed
Usage
- Run an existing site given the path to its config TOML:
arse run config.toml
- Logging verbosity can be increased with
-v
or-vv
, the default level isINFO
. - Create and run a new site from user input:
arse new
$ arse new
2021-05-01T17:34:11.155427589+00:00 [INFO] Logging started
2021-05-01T17:34:11.155543182+00:00 [INFO] Generating new site configuration
Please enter a name for the site:
Example Site
Please enter the site author's name:
Arthur Writeson
Please enter the base URL for your site:
https://www.example.com
Please enter comma-separated site topics:
one, two, three
2021-05-01T17:34:26.501980660+00:00 [INFO] Creating site filesystem tree
2021-05-01T17:34:26.504816188+00:00 [INFO] Writing site configuration to disk
Configuration
An example config, as generated, is shown below:
[site]
name = 'Example Site'
author = 'Arthur Writeson'
url = 'https://www.example.com'
template = 'default.tmpl'
topics = [
'one',
'two',
'three',
]
[server]
bind = '0.0.0.0'
port = 9090
[docpaths]
templates = '/home/user/site/templates'
webroot = '/home/user/site/webroot'
Rendering and Styling
A default template, default.tmpl
, is provided statically within the binary. To change the Tera
template, add your custom template to the templates directory referenced in the [docpaths]
configuration
section of config.toml
. Once the template is in the templates directory, change the templates
parameter
in the [site]
configuration section to reference the template's file name. This template will now be loaded
at runtime.
The following elements are available within the Tera context for rendering:
site
, mapping directly to the fields available in thesite
configuration sectionpost
, available when serving single-posts from fromsite/:topic/posts/:post.md
- Used when serving
GET /:topic/posts/:post
where:post
is the markdown filename minus its extension
- Used when serving
posts
, a lexically reverse-sorted list of HTML rendered from markdown insite/:topic/posts/*.md
- Used when serving
GET /:topic
- Used when serving
Further Customizations
bind
andport
may be set in the[server]
section.- New topics are added as array elements
- For each new topic, create the necessary paths
site/:topic/posts
andsite/:topic/ext
- For each new topic, create the necessary paths
- Items in
[docpaths]
are generated as full paths for completeness, however relative paths will work if desired- From the example above the user is free to simply use
site/templates
andsite/webroot
and move the directory out of/home/user
- Note that
arse new
creates the site tree, and all other output files, in the current working directory.
- From the example above the user is free to simply use
- If
gallery
is one of the topics requested- A simple image slideshow will be generated for
/gallery/ext/*.jpg
- Display will follow the same lexical reverse order as posts.
- A simple image slideshow will be generated for
Path to 1.0
- Dynamic route handling
- Provide meaningful logging of binary activites at appropriate levels
- Context-specific Errors and handling
- Support custom Tera templates
- Support custom bind address and port
- Support favicons
- Support a special
gallery
topic - Support RSS feeds
- Support for adding/removing topics
License
Licensed under either of
- Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)
at your option.
Contribution
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.
Contact
To discuss features, offer assistance, or get help please join the project's Matrix room.