X-Git-Url: https://git.ladys.computer/Shrine-XSLT/blobdiff_plain/a47140cf7262ffb49c2fe4e109deb960dd9ca6dc..b165654fb546b6262512b33a590b2dacf00eb92c:/README.markdown diff --git a/README.markdown b/README.markdown index 216d4d8..00dd2b5 100644 --- a/README.markdown +++ b/README.markdown @@ -7,16 +7,14 @@ substantially changing the authoring flow. ## Features - Really simple shrine generation - - One command: `make` ## Prerequisites -These things come preinstalled on many platforms :— - -- G·N·U Make (run `make --version` to see if it is installed) +These things come pre·installed on many platforms :— -- libxslt (run `xsltproc --version` to see if it is installed) +- G·N·U `make` (run `make --version` to see if it is installed) +- `xsltproc` (run `xsltproc --version` to see if it is installed) You will also need to know how to write X·M·L, and how to navigate to a directory via the command line and run `make`. @@ -48,43 +46,51 @@ page. The ``, ``, and `` elements will be replaced by the page header, content, and footer, respectively. -Finally, just run `make` from this directory, and X·H·T·M·L files +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 +## 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 :— -- The created files have a `.xhtml` extension and *need* to be served - with a `application/xhtml+xml` (or `application/xml`) media type. Not - all servers know how to serve `.xhtml` files; if this is you, you may - have better luck with `make XHTMLEXT=xml` (which will produce `.xml` - files instead). +- You do *not* provide your own ``s and rely on the generated ones + (which will be an `oai:` URI derived from the file path). - - Some free hosting options require that “index” pages have an - extension of `.html`; these will unfortunately not work. It is - possible to extend the makefile to generate `index.html` redirects - to `index.xhtml` with the following code :— +- 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. - ```make - override redirects := $(patsubst public/%.$(XHTMLEXT),public/%.html,$(indices) $(pages)) +- 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/`). - all: $(redirects) # in addition to the previously declared prerequisites +There’s an example `feed.atom` provided so you can see what this + feature might look like in practice. - $(redirects): - # You may want a more involved redirect page than this, but it’s an example… - echo '' > $@ - ``` +## Notes - This should be considered a last resort, but it can be used to get - your site working on e·g Neocities. +- The created files have a `.html` extension and need to be served + with a `text/html` media type. - Files at `sources/index.xml` and `sources/index-*.xml` will produce - output at `public/%.xhtml` (where `%` is the filename). + output at `public/%.html` (where `%` is the filename). - All other files at `sources/*.xml` and `sources/*/*.xml` will produce - output at `public/%/index.xhtml` (where `%` is the filename and + 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. @@ -94,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