## 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`.
(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
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
+## 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 `<head>` of
+ the resulting document. This is especially useful for `<title>`,
+ `<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.
-- 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).
+### Microdata
- - 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 can use the H·T·M·L `@itemprop` attribute to define metadata for
+your site pages. The following values are supported :—
- ```make
- override redirects := $(patsubst public/%.$(XHTMLEXT),public/%.html,$(indices) $(pages))
+- `shrine-title`: The title of the page.
- all: $(redirects) # in addition to the previously declared prerequisites
+- `shrine-id`: A persistent, globally‐unique identifier for the page.
- $(redirects):
- # You may want a more involved redirect page than this, but it’s an example…
- echo '<!DOCTYPE html><meta http-equiv="refresh" content="0;url=./index.xhtml">' > $@
- ```
+- `shrine-updated`: The datetime that the page was last updated.
- This should be considered a last resort, but it can be used to get
- your site working on e·g Neocities.
+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.
- 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.
(`<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</title>`.
-
- 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
Lady’s Gitweb / Shrine-XSLT / blobdiff