X-Git-Url: https://git.ladys.computer/Shrine-XSLT/blobdiff_plain/820c8ba68006a97a11027c972493391bf58b06e9..a88092b64fd8b21e71ae97d4ded3f11374334886:/README.markdown diff --git a/README.markdown b/README.markdown index c7b84ae..93ff7c1 100644 --- a/README.markdown +++ b/README.markdown @@ -7,7 +7,6 @@ substantially changing the authoring flow. ## Features - Really simple shrine generation - - One command: `make` ## Prerequisites @@ -32,14 +31,14 @@ of these files should typically be an H·T·M·L `
` element (remember to declare the X·H·T·M·L namespace!), and you should give it a `@lang` attribute as well. An example is provided. -The `@data-shrine-header` and `@data-shrine-footer` attributes on the -root elements of your pages specify the names of the header and footer -to use on the page. You can use headers and footers to supply page -navigation, branding, and so forth. For each header and footer you -specify, you will need to create a corresponding `$-header.xml` or -`$-footer.xml` (where `$` is the header/footer name) which provides -the contents. These files should be placed in *this* (repository root) -directory, not in `sources/`. +The (entirely optional) `@data-shrine-header` and `@data-shrine-footer` +attributes on the root elements of your pages specify the names of the +header and footer to use on the page. You can use headers and footers +to supply page navigation, branding, and so forth. For each header and +footer you specify, you will need to create a corresponding +`$-header.xml` or `$-footer.xml` (where `$` is the header/footer name) +which provides the contents. These files should be placed in *this* +(repository root) directory, not in `sources/`. The `template.xml` file in this directory contains the main page template, and you should edit it to add styling and so forth to your @@ -51,7 +50,54 @@ Finally, just run `make` from this directory, and H·T·M·L files corresponding to your source files will be created in the `public/` directory (which you can then serve statically from your server). -## Notes +## Advanced Features + +### Slots + +You can use the `@slot` attribute with a few special values to insert +content in various places :— + +- `@slot="shrine-head"` will place the content into the `` of + the resulting document. This is especially useful for ``, + `<meta>`, and `<style>` elements. + +- For `shrine-header` and `shrine-footer`, there are `-before` and + `-after` slot names which will place content into the beginning or + ending of the shrine header or footer, respectively. + +- You can define your own slots with `<slot>` in templates, headers, + and footers; this will enable a corresponding `@slot` name beginning + with `shrine-template-slot-`, `shrine-header-slot-` or + `shrine-footer-slot`, respectively. + +### Microdata + +You can use the H·T·M·L `@itemprop` attribute to define metadata for +your site pages. The following values are supported :— + +- `shrine-title`: The title of the page. + +- `shrine-id`: A persistent, globally‐unique identifier for the page. + +- `shrine-updated`: The datetime that the page was last updated. + +Multiple values for a single `@itemprop` are not currently supported. +Where possible, X·M·L markup will be preserved when accessing metadata +values. + +### Atom Feeds + +Any `.atom` files you provide will automatically be filled out with +`<id>`s, `<updated>` values, and other necessary information before +being copied to the destination location. If you wish to use this +feature, you will need to provide a `BASEIRI` variable when you run +`make` to allow the X·S·L·T to transform relative links into absolute +ones. + +There’s an example `feed.atom` provided so you can see what this +feature might look like in practice. + +## Additional Notes - The created files have a `.html` extension and need to be served with a `text/html` media type. @@ -63,6 +109,10 @@ directory (which you can then serve statically from your server). output at `public/%/index.html` (where `%` is the filename and optional subdirectory). Only one level of subdirectory is supported. +- For any files at `sources/*.xml` and `sources/*/*.xml`, files in the + folder with the same name (minus the `.xml`) will be copied over + verbatim. + - The transformation doesn’t do any rewriting of links. Make sure you write them to point to the *final* location of the files, not their location within the `sources/` directory. @@ -72,11 +122,6 @@ directory (which you can then serve statically from your server). (`<html>`) element of the template, as will `@lang` and `@xml:lang`. You can use this to help configure page‐specific styling. -- You can insert content into the `<head>` of the template by setting - `@slot="shrine-head"` on the appropriate elements. For example, one - might customize the title of a page like - `<title slot="shrine-head">My Title | My Cool Shrine`. - - If you delete files from `sources/`, the corresponding files in `public/` will **not** be deleted and will need to be manually removed. An easy way to ensure that there are no outdated files in