Lady’s Gitweb - Shrine-XSLT/blob - README.markdown

   1 # X·S·L·T Shrine Generator
   2
   3 A very lightweight and oldweb static site generator, mainly targeted
   4 at eliminating the need for `<iframe>` headers and footers without
   5 substantially changing the authoring flow.
   6
   7 ## Features
   8
   9 - Really simple shrine generation
  10 - One command: `make`
  11
  12 ## Prerequisites
  13
  14 These things come pre·installed on many platforms :—
  15
  16 - G·N·U `make` (run `make --version` to see if it is installed)
  17 - `xsltproc` (run `xsltproc --version` to see if it is installed)
  18
  19 You will also need to know how to write X·M·L, and how to navigate to a
  20 directory via the command line and run `make`.
  21
  22 Finally, you will need a copy of this repository, which serves as a
  23 template.
  24
  25 ## Basic Usage
  26
  27 In the `sources/` directory, create X·M·L files containing the unique
  28 content of your pages. Generally you will want a general landing page
  29 called `index.xml`, and a variety of other subpages. The root element
  30 of these files should typically be an H·T·M·L `<article>` element
  31 (remember to declare the X·H·T·M·L namespace!), and you should give it
  32 a `@lang` attribute as well. An example is provided.
  33
  34 The (entirely optional) `@data-shrine-header` and `@data-shrine-footer`
  35 attributes on the root elements of your pages specify the names of the
  36 header and footer to use on the page. You can use headers and footers
  37 to supply page navigation, branding, and so forth. For each header and
  38 footer you specify, you will need to create a corresponding
  39 `$-header.xml` or `$-footer.xml` (where `$` is the header/footer name)
  40 which provides the contents. These files should be placed in *this*
  41 (repository root) directory, not in `sources/`.
  42
  43 The `template.xml` file in this directory contains the main page
  44 template, and you should edit it to add styling and so forth to your
  45 page. The `<shrine-header>`, `<shrine-content>`, and `<shrine-footer>`
  46 elements will be replaced by the page header, content, and footer,
  47 respectively.
  48
  49 Finally, just run `make` from this directory, and H·T·M·L files
  50 corresponding to your source files will be created in the `public/`
  51 directory (which you can then serve statically from your server).
  52
  53 ## Advanced Features
  54
  55 ### Slots
  56
  57 You can use the `@slot` attribute with a few special values to insert
  58 content in various places :—
  59
  60 - `@slot="shrine-head"` will place the content into the `<head>` of
  61   the resulting document. This is especially useful for `<title>`,
  62   `<meta>`, and `<style>` elements.
  63
  64 - For `shrine-header` and `shrine-footer`, there are `-before` and
  65   `-after` slot names which will place content into the beginning or
  66   ending of the shrine header or footer, respectively.
  67
  68 - You can define your own slots with `<slot>` in templates, headers,
  69   and footers; this will enable a corresponding `@slot` name beginning
  70   with `shrine-template-slot-`, `shrine-header-slot-` or
  71   `shrine-footer-slot`, respectively.
  72
  73 ### Microdata
  74
  75 You can use the H·T·M·L `@itemprop` attribute to define metadata for
  76 your site pages. The following values are supported :—
  77
  78 - `shrine-title`: The title of the page.
  79
  80 - `shrine-id`: A persistent, globally‐unique identifier for the page.
  81
  82 - `shrine-updated`: The datetime that the page was last updated.
  83
  84 Multiple values for a single `@itemprop` are not currently supported.
  85 Where possible, X·M·L markup will be preserved when accessing metadata
  86 values.
  87
  88 ### Atom Feeds
  89
  90 Any `.atom` files you provide will automatically be filled out with
  91 `<id>`s, `<updated>` values, and other necessary information before
  92 being copied to the destination location. If you wish to use this
  93 feature, you will need to provide a `BASEIRI` variable when you run
  94 `make` to allow the X·S·L·T to transform relative links into absolute
  95 ones.
  96
  97 There’s an example `feed.atom` provided so you can see what this
  98 feature might look like in practice.
  99
 100 ## Additional Notes
 101
 102 - The created files have a `.html` extension and need to be served
 103   with a `text/html` media type.
 104
 105 - Files at `sources/index.xml` and `sources/index-*.xml` will produce
 106   output at `public/%.html` (where `%` is the filename).
 107
 108 - All other files at `sources/*.xml` and `sources/*/*.xml` will produce
 109   output at `public/%/index.html` (where `%` is the filename and
 110   optional subdirectory). Only one level of subdirectory is supported.
 111
 112 - For any files at `sources/*.xml` and `sources/*/*.xml`, files in the
 113   folder with the same name (minus the `.xml`) will be copied over
 114   verbatim.
 115
 116 - The transformation doesn’t do any rewriting of links. Make sure you
 117   write them to point to the *final* location of the files, not their
 118   location within the `sources/` directory.
 119
 120 - Any `@data-*` attributes (other than `@data-shrine-*` attributes) you
 121   add to the root (`<article>`) element will be copied onto the root
 122   (`<html>`) element of the template, as will `@lang` and `@xml:lang`.
 123   You can use this to help configure page‐specific styling.
 124
 125 - If you delete files from `sources/`, the corresponding files in
 126   `public/` will **not** be deleted and will need to be manually
 127   removed. An easy way to ensure that there are no outdated files in
 128   `public/` is just to delete the entire directory before running
 129   `make`.
 130
 131 - This repository is intended as a starting point; feel free to
 132   customize it to your needs!