X-Git-Url: https://git.ladys.computer/Shrine-XSLT/blobdiff_plain/820c8ba68006a97a11027c972493391bf58b06e9..b165654fb546b6262512b33a590b2dacf00eb92c:/README.markdown?ds=sidebyside diff --git a/README.markdown b/README.markdown index c7b84ae..00dd2b5 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 @@ -51,6 +50,31 @@ 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). +## Atom Feeds + +Any `.atom` files you provide will automatically be filled out with +``s, `` 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. + +It is recommended that :— + +- You do *not* provide your own ``s and rely on the generated ones + (which will be an `oai:` URI derived from the file path). + +- You *do* manually provide `` times for individual entries + (although not the feed as a whole); otherwise every entry will be + marked as updated every time the feed is generated. + +- All `` elements in `` elements use a + relative `@href` with a leading slash. This should point to the + *final* location of the entry (within, but not including, `public/`). + +There’s an example `feed.atom` provided so you can see what this + feature might look like in practice. + ## Notes - The created files have a `.html` extension and need to be served @@ -63,6 +87,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,10 +100,21 @@ directory (which you can then serve statically from your server). (``) 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 `` of the template by setting - `@slot="shrine-head"` on the appropriate elements. For example, one - might customize the title of a page like - `My Title | My Cool Shrine`. +- 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. - If you delete files from `sources/`, the corresponding files in `public/` will **not** be deleted and will need to be manually