diff --git a/README.md b/README.md index 0714260..d2fe6ef 100644 --- a/README.md +++ b/README.md @@ -1,13 +1,13 @@ # Pillar -A simple site generator with template support, written in plain (and now slightly more idiomatic) Rust, with support for extensions in whatever language you prefer. +A simple site generator with template support, written in somewhat idiomatic Rust, with support for extensions in whatever language you prefer. -Used in [[my site]](https://mineralexistence.com) +Used in [my site](https://mineralexistence.com) A little demo is available in the `examples/` folder of this repo, which shows off Pillar's features (and honestly is mostly a place for me to test and debug). ## Commands -Pillar has only a few commands. With no arguments, it will give you the help menu. That help menu will also be printed with the arguments `--help` or `-h`. Run `./pillar build` to generate your site, and `./pillar build --debug` to get the debug parser, where it will show you what it's doing step-by-step (note that this is *much* slower, so should be used only if you want to see how the parser works). +Pillar has only a few commands. With no arguments, it will give you the help menu. That help menu will also be printed with the arguments `--help` or `-h`. Run `./pillar build` to generate your site, and `./pillar build --debug` to get the debug parser, where it will show you what it's doing step-by-step (note that this is *much* slower, so should be used only if you want to see how the parser works). Use `--all` to build every page, disregarding file modification time. That's all of the command arguments, and anything else will just give you the help menu. ## Configuration @@ -24,14 +24,14 @@ music_path = "/home/user/Music/" [values] latest_length = 15 ``` -Pillar takes all .gn files in the `granite_path` directory and parses them into html, templating them with the templates in the `template_path` directory, and outputting the html to the `html_path` directory. Before the html is saved to the html directory, each page is passed through all the scripts in the `plugin_path` directory (see the [extensions](#Extensions) section). +Pillar takes all .gn files in the `granite_path` directory and parses them into html, templating them with the templates in the `template_path` directory, and outputting the html to the `html_path` directory. Before the html is saved to the html directory, each page is passed through all necessary scripts in the `plugin_path` directory. -The `latest_length` parameter is currently not used, but was originally intended to control the length of the list of latest pages (see the [extensions](#Extensions) section for more information on how extensions are currently handled). +The `latest_length` parameter not used necessary for pillar, but is used to control the length of the list of latest pages generated by the `latest` script (see the [extensions](#Extensions) section for more information on how extensions are currently handled). ## Granite Pillar uses the Granite (.gn) markup format, which is more similar HTML than it is to markdown. It also isn't too picky about whitespace. -Granite maps 1:1 with html, so the conversion process is relatively simple, and is done in a single pass. The syntax gets rid of close tags in favor of close square brackets, as so: +Granite maps 1:1 with html, so the conversion process is relatively simple, and is done in a single pass (sorta. this is a point for further optimization). The syntax gets rid of close tags in favor of close square brackets, like so: html: `

This is a paragraph

` @@ -51,7 +51,7 @@ As you can see, the Granite syntax is very similar to html, but is in my mind a - variables are declared with the `name: value` pattern (it's not too particular about whitespace) - the `title` variable is used to set the title (used for the `{{latest}}` substitution) - the `template` variable sets the template for the page, defaulting to `default`, where the value is the file name (without extension) of a template in the given template directory -- if the `static` variable is set to a value of "true", the page will always be parsed when pillar is run. This useful for pages which you want to be updated by a script every time pillar is run, and not just when that page is changed. +- if the `static` variable is set to a value of `true`, the page will always be parsed when pillar is run. This useful for pages which you want to be updated by a script every time pillar is run, and not just when that page is changed. Example: ``` @@ -60,6 +60,7 @@ title: Example page template: fancy_template !meta! ``` +In this example, the template used will be the `fancy_template.html` file in your template directory. ## Extensions @@ -68,9 +69,9 @@ Pillar supports extensions in the form of executable scripts in your defined plu - `{{doc-gen}}` generate documentation from comments in python plugins in the plugin directory - `{{feed}}` is a basic rss feed generator - `{{files}}` gives a list of files in a `/files` directory -- `{{latest}}` replaces with a given number of the latest updated pages in an unordered list -- `{{music}}` replaces with an unordered list of your album directory names in a designated music path -- `{{stats}}` just gives a list of orphaned pages (the algorithm is not super complete, and may not be entirely accurate) +- `{{latest}}` is replaced with a given number of the latest updated pages in an unordered list +- `{{music}}` is replaced with an unordered list of your album directory names in a designated music path +- `{{stats}}` just gives a list of orphaned pages - `{{title}}` is mostly for the html templates to get the title of a page based on its first h2 tag - `{{tree}}` is an in-development tree printout of page interconnectivity; non-functional