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 `@data-shrine-header` and `@data-shrine-footer` attributes on the
  35 root elements of your pages specify the names of the header and footer
  36 to use on the page. You can use headers and footers to supply page
  37 navigation, branding, and so forth. For each header and footer you
  38 specify, you will need to create a corresponding `$-header.xml` or
  39 `$-footer.xml` (where `$` is the header/footer name) which provides
  40 the contents. These files should be placed in *this* (repository root)
  41 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 ## Atom Feeds
  54
  55 Any `.atom` files you provide will automatically be filled out with
  56 `<id>`s, `<updated>` values, and other necessary information before
  57 being copied to the destination location. If you wish to use this
  58 feature, you will need to provide a `BASEIRI` variable when you run
  59 `make` to allow the X·S·L·T to transform relative links into absolute
  60 ones.
  61
  62 It is recommended that :—
  63
  64 - You do *not* provide your own `<id>`s and rely on the generated ones
  65   (which will be an `oai:` URI derived from the file path).
  66
  67 - You *do* manually provide `<updated>` times for individual entries
  68   (although not the feed as a whole); otherwise every entry will be
  69   marked as updated every time the feed is generated.
  70
  71 - All `<link rel="alternate">` elements in `<entry>` elements use a
  72   relative `@href` with a leading slash. This should point to the
  73   *final* location of the entry (within, but not including, `public/`).
  74
  75 There’s an example `feed.atom` provided so you can see what this
  76   feature might look like in practice.
  77
  78 ## Notes
  79
  80 - The created files have a `.html` extension and need to be served
  81   with a `text/html` media type.
  82
  83 - Files at `sources/index.xml` and `sources/index-*.xml` will produce
  84   output at `public/%.html` (where `%` is the filename).
  85
  86 - All other files at `sources/*.xml` and `sources/*/*.xml` will produce
  87   output at `public/%/index.html` (where `%` is the filename and
  88   optional subdirectory). Only one level of subdirectory is supported.
  89
  90 - For any files at `sources/*.xml` and `sources/*/*.xml`, files in the
  91   folder with the same name (minus the `.xml`) will be copied over
  92   verbatim.
  93
  94 - The transformation doesn’t do any rewriting of links. Make sure you
  95   write them to point to the *final* location of the files, not their
  96   location within the `sources/` directory.
  97
  98 - Any `@data-*` attributes (other than `@data-shrine-*` attributes) you
  99   add to the root (`<article>`) element will be copied onto the root
 100   (`<html>`) element of the template, as will `@lang` and `@xml:lang`.
 101   You can use this to help configure page‐specific styling.
 102
 103 - You can use the `@slot` attribute with a few special values to insert
 104   content in various places :—
 105
 106   - `@slot="shrine-head"` will place the content into the `<head>` of
 107     the resulting document. This is especially useful for `<title>`,
 108     `<meta>`, and `<style>` elements.
 109
 110   - For `shrine-header` and `shrine-footer`, there are `-before` and
 111     `-after` slot names which will place content into the beginning or
 112     ending of the shrine header or footer, respectively.
 113
 114   - You can define your own slots with `<slot>` in templates, headers,
 115     and footers; this will enable a corresponding `@slot` name
 116     beginning with `shrine-template-slot-`, `shrine-header-slot-` or
 117     `shrine-footer-slot`, respectively.
 118
 119 - If you delete files from `sources/`, the corresponding files in
 120   `public/` will **not** be deleted and will need to be manually
 121   removed. An easy way to ensure that there are no outdated files in
 122   `public/` is just to delete the entire directory before running
 123   `make`.
 124
 125 - This repository is intended as a starting point; feel free to
 126   customize it to your needs!